Title: Add Provider General Settings Explained Describe the issue: My understanding is that this is a tech preview feature, but the details around configuring an external provider could be more clear. The definitions are not actually definitions, if you don't already know what a Provider URL is by reading the label: "Provider URL", having the definition be "The URL of the provider" isn't going to help you understand what it is or should look like, or what format it should be entered in. This applies to many of the fields described in this section. Suggestions for improvement: Provide more context, or examples, or define it using language that doesn't repeat the field label, so that the customer has a greater chance of understanding what we're asking for, and knows how to provide it in a way that RHEV can use. RHEV and OpenStack use a lot of different language, it would be nice if we were more specific here on what to point to. Is the provider the Networking Node? The Compute node? Does it matter if it's Neutron Networking? How do I know if I'm using Linux Bridge or Open vSwitch? What's an OpenStack tenant? What's the difference between OpenStack Server vs OpenStack Image? Why would I pick one over the other? Additional information: It's also worth pointing out that while the docs say the possible Provider types are "Foreman, OpenStack Image, and OpenStack Server", RHEV actually has the following options "Foreman, OpenStack Image, and OpenStack Network". Not all the terms match up between doc and UI here.
Created attachment 878699 [details] Adding Providers Table
Fixed in 23161, 25146, 25098, and 25147.
Documentation Link ------------------------------ http://documentation-devel.engineering.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.4/html-single/Administration_Guide/index.html#Explanation_of_Settings_and_Controls_in_the_Add_Provider_and_Edit_Provider_Windows What Changed ------------------------------ The following topics were revised to add further details to each of the settings and clarify their use, along with which passwords and user names must be used to authenticate with each type of external provider. Add Provider General Settings Explained [23161-624543] Add Provider Agent Configuration Settings Explained [25146-624549] Edit Provider General Settings Explained [25098-624544] Edit Provider Agent Configuration Settings Explained [25147-624548] 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 and if you think it looks good, change the bug status to verified? Thanks
I'm still not quite sure when one should select Linux Bridge or Open vSwitch. In the procedure we say: "Click the text field for Network Plugin and select either Linux Bridge or Open vSwitch in accordance with the plug-in set up in your OpenStack environment." In the table, we describe it as: "The network plug-in with which to connect to the OpenStack server. Users can select either Linux Bridge or Open vSwitch." Is it a safe assumption that users will know which to select? I don't think I would from those descriptions. Does one relate back to Neutron and the other to Nova? Minor, but if we're saying the field is "Username", in the description of it, we probably should keep it as one word, we switch to "user name" there. Some of the service/server instances may need to be prefixed by a "the". For example: "Username: A user name for connecting to OpenStack Image Service. This user name must be the user name for OpenStack Image Service registered in the Keystone instance of which the OpenStack Image Service instance is a member. By default, this user name is glance." Some of the times things like "OpenStack Image Service" are mentioned, we say "the OpenStack Image Service", and other times we don't. Some of the times we don't sound a little awkward to me (like in the above example). Overall though, these are much more descriptive and I would think people reading the docs would know what they're being asked for, if it wasn't obvious to them from the dialog.
Hi Matt, Thank you for your feedback, and my sincere apologies for the delay in getting back to you. To address your concerns, I have made the following changes - * I have used the same wording in the settings table as used in the procedure with regard to the Linux Bridge and Open vSwitch. In regards to which is appropriate, when users set up the OpenStack components to act as external providers, they must set up a plug-in as outlined in the OpenStack documentation, and specify the type of plug-in they set up here. By way of helping users find the right information, I have added a 'note' box to "Introduction to External Providers in Red Hat Enterprise Virtualization" to clarify that users must set up the components first, including a link to related documentation on the OpenStack side. I will also follow up with the OpenStack documentation and see if further information can be added on that side as well. * I have now added 'the' to the instances of the service names in the tables. * I also agree with you in that 'username' and 'user name' should match. At current, our overall standard is to use 'user name' as two distinct words, which is in conflict with the user interface element here 'username'. If possible, I would be inclined to use 'user name' to follow our overall standard here, and will see if I can submit a patch against the user interface to change 'username' to 'user name' so that the two match. You can find the changes here: http://docbuilder.usersys.redhat.com/22720/#Introduction_to_Third_Party_Resource_Providers_in_Red_Hat_Enterprise_Virtualization Please let me know if you have any further feedback. Kind regards, Andrew
Verified in the 3.4 guide. The content will be available in the next async release.
Andrew, We should always have the docs reflect what is in the UI, regardless of any other standards. (The only exception is a real typo, like if it were "uesr name" or something.)
Hi Deon, Thank you for your feedback. I have now updated the documentation to use 'username' in all places in the relevant topics, and have given the same treatment to 'plug-in' as well. Please let me know if Matt or yourself have any further feedback or concerns. Kind regards, Andrew
Documentation Link ------------------------------ https://documentation-devel.engineering.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.4/html-single/Administration_Guide/index.html#chap-External_Providers What Changed ------------------------------ The following topics were revised to add further details to each of the settings and clarify their use, along with which passwords and user names must be used to authenticate with each type of external provider. Furthermore, the topics on settings for editing external provider settings have been removed, and a 'Note' box was added to the introductory topic to help point users towards documentation that will assist in setting up a RHEL-OSP environment and identifying several of the key values required to add providers. Introduction to External Providers in Red Hat Enterprise Virtualization [23158-705627] Add Provider General Settings Explained [23161-706017] Add Provider Agent Configuration Settings Explained [25146-705970] Updated revision history: [30102-624554] NVR ------------------------------ Red_Hat_Enterprise_Virtualization-Administration_Guide-3.4-en-US-3.4-33.0 Moving to ON_QA.
Reviewed for the additional changes. Moving to Verified. Once published, move this bug to Closed-current release.