Title: Adding an External Provider Describe the issue: Section 13.4 reads: 13.4. Adding an External Provider Summary All external (third party) resource providers are added using a single window that adapts to your input. You must add the resource provider before you can use the resource it provides in your Red Hat Enterprise Virtualization environment. Procedure 13.1. Adding an External Provider Select the External Providers entry in the tree pane. Click the Add button. Select one of supported resource providers from the Type drop-down menu. The available fields change based on the selected resource provider. Fill in the details of your resource provider, and click OK. Result You have added a resource provider, and can now consume the resources it provides in your Red Hat Enterprise Virtualization environment. Suggestions for improvement: This might just be me, but it seems like this section would be a great place to include the configuration information that comes a few sections later, in 13.7 and 13.8. I might not be able to make it through the flow described in 13.4 if I'm not sure what I should configure the settings to be. It would be more convenient to have that information here, in this section, if I needed it, rather than needing me to go flipping through the doc and hoping that there's more information somewhere else. If the way the sections are currently comprised makes more sense, it would be nice to at least add a note to 13.4 that if the customer needs more information, they can go to 13.7 and see what the possible config options are. It's not mentioned at all right now in this section, and they're closely related in my opinion. Additional information:
Fixed in 22626 and 30204.
Documentation Link ------------------------------ http://documentation-devel.engineering.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.4/html-single/Administration_Guide/index.html#Adding_a_Third_Party_Resource_Provider What Changed ------------------------------ The following topics were added to provide specific instructions on adding external providers. Adding a Foreman for Host Provisioning [30108] Adding an OpenStack Network Service (Neutron) for Network Provisioning [30109] Adding an OpenStack Image Service (Glance) for Image Management [30110] Updated revision history: [30102-624554] NVR ------------------------------ Red_Hat_Enterprise_Virtualization-Administration_Guide-3.4-en-US-3.4-5 Moving to ON_QA.
Hi Matt Can you please provide some QE on this bug? If it's solved to your satisfaction please change the bug's status to verified. Thanks
Having the specific procedures for the different types of resource you can add helps mitigate a lot of the possible ambiguity in the creation process. That's a clear improvement! I do have a couple other comments on the rest of the External Providers section however: I'm not sure I understand the value of having the duplicated tables of Table 13.1. Add Provider: General Settings and Table 13.2. Add Provider: General Settings vs Table 13.3. Edit Provider: General Settings and Table 13.4. Edit Provider: General Settings. As far as I can tell, they have slightly different intro text, and then the tables themselves are the same. Perhaps they could be consolidated into a single section that describes all the fields? It might make things more clear if the two tables were named more differently as well. Both tables in each section are called General Settings, despite dealing with different tabs, the second General Settings (tables 13.2 and 13.4) are for Agent Settings. Do you think the note about importing SSL certs should be listed as part of the procedure itself? Results: "If the Glance instance uses SSL, you will be prompted to import the certificates the Glance instance provides. The Glance instance is then added to the Red Hat Enterprise Virtualization Manager, and you can work with the images it provides." It seems a little odd to me to have that in the Result, I think of Results as what the procedure accomplished now that I'm done with it, and not a place where additional tasks might be detailed. Could easily be mentioned as part of the URL step, that if an https URL is entered, that they'll need to allow it to import the SSL cert. That would more closely associate the two together as well, I wasn't initially sure what was meant and how I would know if I needed to import SSL certs. The note after the general settings table is actually what helped me understand what the Result was trying to convey (but that's much less likely to get seen if they're following the new procedures): "When adding a provider that is secured (https), the certificates of that provider are detected. You are then given the option to add those certificates to your trusted certificates."
Hi Matt, I have now moved the instructions regarding enabling SSL into their own step as part of each of the procedures for adding an external provider. After testing the procedure in both a 3.4 and 3.5 environment, I have found that the option to import certificates was displayed on testing credentials, so I have added the content there. The changes can be found here: http://documentation-devel.engineering.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.5-Beta/html-single/Administration_Guide/index.html#Adding_a_Foreman_for_Host_Provisioning Kind regards, Andrew
Do you have to test the credentials to be able to accept the SSL cert? It doesn't look the OK button is disabled if you don't. Would they also be able to just click OK on the dialog and get guided to accept the cert? Should we be saying "Foreman Instance", to match how we're talking about the two OpenStack providers they can add, or is "Adding a Foreman for Host Provisioning" ok? Section Titles: 13.3.2. Adding a Foreman for Host Provisioning 13.3.3. Adding an OpenStack Networking (Neutron) Instance for Network Provisioning 13.3.4. Adding an OpenStack Image Service (Glance) Instance for Image Management
Hi Matt, Thank you for your feedback. On testing the procedure in both a Red Hat Enterprise Virtualization 3.3 and 3.4 environment, it seems that users are not prompted to import the SSL certificate when they click 'OK'; only when they test the credentials. While this step is included as part of the procedures, I can see how it might be better to put this in nice bold letters to make it clear that importing the SSL certificate is important. I will reach out to the engineers and see if they can provider further information that might make the procedure clearer. In regards to 'Foreman Instance', this is a bit of a tricky area. The reason for this is that Foreman is not technically one of the formal components of OpenStack, and is rather a semi-indepedent tool that can be used to deploy such components. As such, I felt it made more sense to use slightly different language here. Going forward, in Red Hat Enterprise Virtualization 3.5, all instances of 'Foreman' will need to be updated to 'Red Hat Enterprise Linux OpenStack Platform Installer' in accordance with the rebranding of the tool within Red Hat, so the nature of this issue will change slightly as well. For now, I personally feel that keeping 'Adding a Foreman for Host Provisioning' shouldn't be too much of an issue, but I would be happy to add more detail or work on improving the wording if you feel it seems odd to readers. As always, thank you for your feedback - I will leave a note once again when I hear from the engineers. Kind regards, Andrew
Hi Matt, In accordance with the response from engineering, I have added an 'important' box to each of the topics on adding external providers to ensure it is clear that users must import the certificate. I have also gone with adding 'instance' to Foreman in the title of the topic on adding Foreman to the Red Hat Enterprise Virtualization Manager given the use of the word 'instance' in conjunction with Foreman in other places. You can find the changes here: http://docbuilder.usersys.redhat.com/22720/#Adding_a_Foreman_for_Host_Provisioning Please let me know if you have any further feedback. Kind regards, Andrew
Sounds good!
Documentation Link ------------------------------ http://documentation-devel.engineering.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.4/html-single/Administration_Guide/index.html#sect-Adding_External_Providers What Changed ------------------------------ The following topics were added to provide specific instructions on adding external providers. In addition, to incorporate the new process for retrieving certificates from external providers, each of the topics on adding external providers now contains an 'Important' box outlining the need to retrieve the certificate, and the action to do so - testing credentials - has been formed into a formal step in these topics. Adding a Foreman for Host Provisioning [30108] Adding an OpenStack Network Service (Neutron) for Network Provisioning [30109] Adding an OpenStack Image Service (Glance) for Image Management [30110] Updated revision history: [41203-705955] NVR ------------------------------ Red_Hat_Enterprise_Virtualization-Administration_Guide-3.4-en-US-3.4-33 Moving to ON_QA.
Peer reviewed. The new topics clearly outline the individual procedures for adding each external provider type. The information in the procedures matches the UI. The important boxes have been placed within the procedure, so that the importance of retrieving a certificate (if applicable) is clear. VERIFIED.