Note: This is a beta release of Red Hat Bugzilla 5.0. The data contained within is a snapshot of the live data so any changes you make will not be reflected in the production Bugzilla. Also email is disabled so feel free to test any aspect of the site that you want. File any problems you find or give feedback here.
Bug 1081195 - Admin Guide - Options for configuring an external provider aren't explained in the Add an External Provider section (13.4), they live in 13.7 & 13.8
Summary: Admin Guide - Options for configuring an external provider aren't explained i...
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: Red Hat Enterprise Virtualization Manager
Classification: Red Hat
Component: Documentation
Version: 3.4.0
Hardware: Unspecified
OS: Unspecified
unspecified
medium
Target Milestone: ---
: 3.5.0
Assignee: Andrew Dahms
QA Contact: Lucy Bopf
URL:
Whiteboard:
Depends On:
Blocks: RHEV-RHCI
TreeView+ depends on / blocked
 
Reported: 2014-03-26 17:59 UTC by Matt Reid
Modified: 2014-09-19 01:32 UTC (History)
10 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
Environment:
Build Name: 13109, Administration Guide-3.3-1 Build Date: 09-01-2014 15:36:24 Topic ID: 23160-566688 [Latest]
Last Closed: 2014-09-19 01:32:55 UTC
oVirt Team: ---


Attachments (Terms of Use)

Description Matt Reid 2014-03-26 17:59:05 UTC
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:

Comment 1 Andrew Dahms 2014-03-27 02:11:49 UTC
Fixed in 22626 and 30204.

Comment 2 Andrew Dahms 2014-04-27 04:07:21 UTC
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.

Comment 3 Jodi Biddle 2014-07-14 15:11:24 UTC
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

Comment 4 Matt Reid 2014-07-14 20:30:19 UTC
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."

Comment 6 Andrew Dahms 2014-08-19 10:33:45 UTC
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

Comment 7 Matt Reid 2014-08-26 15:24:44 UTC
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

Comment 8 Andrew Dahms 2014-08-26 22:09:31 UTC
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

Comment 10 Andrew Dahms 2014-09-02 01:41:00 UTC
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

Comment 11 Matt Reid 2014-09-02 15:33:00 UTC
Sounds good!

Comment 12 Andrew Dahms 2014-09-03 03:15:32 UTC
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.

Comment 13 Lucy Bopf 2014-09-04 00:07:40 UTC
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.


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