Bug 1461674 - [RFE] Improve auto-attach documentation
[RFE] Improve auto-attach documentation
Status: CLOSED DEFERRED
Product: Red Hat Satellite 6
Classification: Red Hat
Component: Docs Architecture Guide (Show other bugs)
6.3.0
Unspecified Unspecified
medium Severity medium (vote)
: 6.2.12
: 6.2
Assigned To: Sergei Petrosian
Russell Dickenson
: FutureFeature, Reopened
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2017-06-15 02:58 EDT by Lukas Zapletal
Modified: 2017-09-19 06:55 EDT (History)
7 users (show)

See Also:
Fixed In Version:
Doc Type: If docs needed, set a value
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2017-09-19 06:55:23 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Lukas Zapletal 2017-06-15 02:58:54 EDT
Hello,

several customers asked on how auto-attach works, specifically how heuristic algorithm selects the "best" subscription to be consumed. Please elaborate that part in our docs.

Michael Stead mentioned that the best resource today would be

http://www.candlepinproject.org/docs/candlepin/autobind.html

Thanks
Comment 3 Andrew Dahms 2017-06-15 20:41:41 EDT
Assigning to Sergei for review.

Sergei - we need to do a few things here, and this will take a little work to get everything into the right shape in the right place.

Satellite, and RHSM itself, have a feature that allows you to auto-attach entitlements to subscribed systems when you register them with a Satellite Server or with the CDN itself.

What we need to do is take the content in [1] above and make a new chapter in the Architecture Guide that outlines this behavior and how it all works.

We'll need to change the structure a bit and add a conceptual introduction, so I would expect something like the following -

* A new chapter about entitlements
* An introduction that tells users that this auto-attach option exists
* An adapted version of the content in [1] that tells users how this works

Later on, we can use this new chapter as the location to add more information about entitlements, so this will be the first step to doing that.
Comment 7 Andrew Dahms 2017-07-04 21:49:16 EDT
It has now been two weeks since the above needinfo request was raised; cancelling.

Given previous requests from support teams to provide more specific instructions on the attachment of entitlements, and the need to focus on content core to the functionality of Satellite, I am closing this request for now.

If there is a strong customer interest in providing more information and guidance around the auto-attach feature, we can revisit this topic and investigate it in more detail as necessary.

Kind regards,

Andrew
Comment 8 Rich Jerrido 2017-07-10 10:19:24 EDT
I am reopening this BZ. There is definitely strong customer need to understand the behavior of the auto-attach algorithm. While we generally don't recommend its usage for interactive use-cases (preferring the user to use activation keys or interactively attaching a subscription), the auto-attach algorithm is also used

- when subscriptions expire. 
- when a system first boots (if it doesn't have a valid sub). 
- when systems are migrated from one hypervisor to another. 

I'd like to see this documented sooner than later due to the reasons above.
Comment 9 Stephen Wadeley 2017-07-10 10:24:35 EDT
Hello Rich &  lzap


Do you know who wrote the code for auto attach? Perhaps they have described it somewhere before?

My objection to describing things in the guides that we do not use in a procedure still stands.


Thank you
Comment 10 Stephen Wadeley 2017-07-10 10:33:10 EDT
(In reply to Stephen Wadeley from comment #9)
> Hello Rich &  lzap
> 
> 
> Do you know who wrote the code for auto attach? Perhaps they have described
> it somewhere before?

Hello lzap
I see comment 0 has link to a description of –auto-attach, is that what you meant by heuristics? Those 5 bullet points?
Comment 11 Rich Jerrido 2017-07-10 12:17:05 EDT
(In reply to Stephen Wadeley from comment #9)
> Hello Rich &  lzap
> 
> 
> Do you know who wrote the code for auto attach? Perhaps they have described
> it somewhere before?
> 
> My objection to describing things in the guides that we do not use in a
> procedure still stands.
> 
> 
> Thank you

Understood. But is this not the purpose of the architecture guide? To describe 

- How it all works. 
- How to put it all together. 

Documenting auto-attach seems to fit well within the former.
Comment 12 Andrew Dahms 2017-07-10 18:46:50 EDT
Hi Rich,

Thank you for re-opening this bug, and for setting us straight.

Moving back to assigned so that this content can be worked on and added to the Architecture Guide.

In addition to the work here, this looks like a good opportunity for us to raise additional bugs and address the 'auto-attach' functionality under the Content Host Bulk Subscriptions tag, and provide some guidance that the preferred use case is to interactively attach subscriptions instead.

I'll look into raising some bugs to cover that so that we are providing guidance across the board.

Kind regards,

Andrew
Comment 13 Lukas Zapletal 2017-07-11 03:00:20 EDT
Hey Stephen,

by "heuristic" I did not mean any particular algorithm other than what Candlepin currently does. Unfortunately all I was able to find is the link in the original comment. This will involve little bit of digging or talking to Candlepin guys I can imagine.

Guys, in the first cut we do not need to go deep, just rough description how this mechanism works would be appropriate so customers are not surprised when it happens (auto-attach and most importantly auto-healing). Frankly, I don't exactly know how this works myself.
Comment 14 Stephen Wadeley 2017-07-11 03:06:51 EDT
(In reply to Rich Jerrido from comment #11)
> (In reply to Stephen Wadeley from comment #9)
> > Hello Rich &  lzap
> > 
> > 
> > Do you know who wrote the code for auto attach? Perhaps they have described
> > it somewhere before?
> > 
> > My objection to describing things in the guides that we do not use in a
> > procedure still stands.
> > 
> > 
> > Thank you
> 
> Understood. But is this not the purpose of the architecture guide? To
> describe 
> 
> - How it all works. 
But not in unnecessary detail, which is subjective of course. This is supposed to be were Steve Bream comes in.

> - How to put it all together. 
> 
> Documenting auto-attach seems to fit well within the former.

Only if we can link the information to changes a user can make to influence the outcome. Perhaps you or lzap could think of what a user can *do* with the information one they have it. Can the edit or configure something for example.


Thank you
Comment 15 Michael Stead 2017-07-11 08:31:20 EDT
The candlepin team currently has a task on the sprint to produce better documentation around the auto attach process. It is on our radar, but at this time, we are not sure when it will be completed due to other high priority items on our plate. Our hope is that the output will be something a little simpler for a customer to follow/digest.
Comment 16 Stephen Wadeley 2017-07-24 11:09:09 EDT
Hello


I found where auto-attach is mentioned in the web UI; on an Activation Key's "Subscriptions" page there is an "Auto-Attach" check box followed by this text:

 When Auto Attach is enabled, registering systems will be attached to all associated custom products and only associated Red Hat subscriptions required to satisfy the system's installed products.

I wonder did someone mean "and any associated"?

We should search the guides for activation key procedures and add info there on how Auto Attach makes its decisions.
Comment 18 Stephen Wadeley 2017-08-02 10:32:34 EDT
Hello

I noticed in the "Managing Activation Keys" chapter of the Hammer CLI Guide[1]

Activation key providing a custom subscription pool for auto attach – hosts using the activation key select the best fitting subscription from the list specified in the activation key. See Example 4.2, “Creating an Activation Key with Custom Subscription Pool”. 



[1] https://access.redhat.com/documentation/en-us/red_hat_satellite/6.2/html/hammer_cli_guide/chap-cli_guide-managing_activation_keys
Comment 24 Steve Bream 2017-09-06 10:28:22 EDT
Hello Sergei,

Have a look at comment 21 - I don't think that we should include any information about the auto attach logic. It's very murky, and customers can't influence it in any way. Customers *do* need to know what the outcome of selecting the auto attach option. 

It looks like Julie's bugs will address Rich's scenarios from comment 8, but I think it would be good to summarize the impact that auto attach will have in those scenarios and use it to expand the information in comment 21.

Feel free to ping me if this doesn't make sense - it's a lot of bouncing around through the bug.

Thanks!
Comment 25 Sergei Petrosian 2017-09-19 06:55:23 EDT
I'm closing the bug because the required content is already included in the Content Management guide [1]:


[1] - https://doc-stage.usersys.redhat.com/documentation/en-us/red_hat_satellite/6.3-beta/html-single/content_management_guide/#Managing_Activation_Keys-Enabling_Auto_Attach

Note You need to log in before you can comment on or make changes to this bug.