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 1517838 - Document the requirement for the "User Interface" server role to also require the "Web Services" server role
Summary: Document the requirement for the "User Interface" server role to also require...
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: Red Hat CloudForms Management Engine
Classification: Red Hat
Component: Documentation
Version: 5.8.0
Hardware: Unspecified
OS: Unspecified
medium
medium
Target Milestone: GA
: 5.9.0
Assignee: Dayle Parker
QA Contact: Chris Budzilowicz
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2017-11-27 15:07 UTC by Robb Manes
Modified: 2018-01-11 06:49 UTC (History)
6 users (show)

Fixed In Version:
Doc Type: If docs needed, set a value
Doc Text:
Clone Of:
Environment:
Last Closed: 2018-01-11 06:49:04 UTC
Category: ---
Cloudforms Team: ---


Attachments (Terms of Use)
General Config guide roles descriptions (deleted)
2017-12-08 05:07 UTC, Dayle Parker
no flags Details
Deployment Guide - new Roles section (deleted)
2017-12-08 05:09 UTC, Dayle Parker
no flags Details


Links
System ID Priority Status Summary Last Updated
Red Hat Bugzilla 1517336 None None None 2017-11-27 15:08:36 UTC
Red Hat Knowledge Base (Solution) 3251321 None None None 2017-11-27 15:08:17 UTC

Description Robb Manes 2017-11-27 15:07:01 UTC
Document URL:
=============
One of the below, depending on preference:
- Deployment Planning Guide: https://access.redhat.com/documentation/en-us/red_hat_cloudforms/4.5/html/deployment_planning_guide
- General Configuration: https://access.redhat.com/documentation/en-us/red_hat_cloudforms/4.5/html/general_configuration/

Section Number and Name: 
========================
Suggestions for added content:

A new section in the Settings section of the General Configuration guide (Chapter 4)
https://access.redhat.com/documentation/en-us/red_hat_cloudforms/4.5/html/general_configuration/configuration#settings

A new section in the Planning section of the Deployment Planning Guide
https://access.redhat.com/documentation/en-us/red_hat_cloudforms/4.5/html/deployment_planning_guide/planning

I am not sure where this content can best serve and defer to better judgement.

Describe the issue: 
===================
A common issue found during planning and setup of environments is, when assigning server roles, selecting the "User Interface" server role on an appliance without also selecting "Web Services".  The web_services role is vital for the user_interface role to function as the user_interface queries the API to receive tokens for login - without this role enabled, customers frequently open cases wherein, although the UI loads, users cannot log in, getting the error "Incorrect username or password".  The Web Services role needs to be enabled to resolve this issue.

I cannot think of a scenario wherein you would want User Interface disabled without also enabling Web Services, and this should be documented.

A KCS outlining the problem is present here:

Using CloudForms Management Engine Operations UI, any attempts to log in to any user, including the admin user, produce the error "Incorrect username or password" 
https://access.redhat.com/solutions/3251321

Suggestions for improvement:
============================
Adding a section on roles, specifically outlining that if the UI role is to be enabled that the Web Services role should also be enabled, would potentially help in reducing the amount of issues we see concerning this common issue.

Comment 1 Andrew Dahms 2017-12-04 00:18:10 UTC
Assigning to Dayle for review.

Dayle - it might be good to add a simple section to the Deployment Planning Guide to cover this particular issue first, then use that section to add some more detail about planning roles later.

What do you think?

Comment 2 Dayle Parker 2017-12-08 05:07:44 UTC
Created attachment 1364624 [details]
General Config guide roles descriptions

Comment 3 Dayle Parker 2017-12-08 05:09:41 UTC
Created attachment 1364626 [details]
Deployment Guide - new Roles section

Hi Robb,

Thanks for the details -- agreed, this could be made more clear so it doesn't trip users up.

Looking at the two guides, I think it fits less in the Deployment Planning Guide, but it's also probably easier to find the information there. For this reason, I added a new section just after the "Regions" section, mentioning the assigning of roles (as Andrew suggested in Comment 1), and have linked to the detailed table on server roles that is in the General Configuration guide (which might be a bit hard to find in the docs currently).

I also edited the descriptions of the User Interface and Web Services roles in the General Config guide to mention both should be enabled.

However -- the 4.5 General Configuration guide says both Web Services & User Interface are enabled by default. So is this perhaps only a problem in certain earlier versions of CloudForms? Do you know what version starts enabling Web Services by default?

Also, if these roles are totally interdependent, I think there should be a product bug to maybe combine these two roles (or something similar). Is there an engineering bug for this?

I'd love to hear your thoughts on the two docs fixes (in screenshots), and on my questions above. (@Andrew, would love to know if this is the approach you had in mind)

Many thanks,
Dayle

Comment 4 Robb Manes 2018-01-08 13:12:20 UTC
(In reply to Dayle Parker from comment #3)
> Looking at the two guides, I think it fits less in the Deployment Planning
> Guide, but it's also probably easier to find the information there. For this
> reason, I added a new section just after the "Regions" section, mentioning
> the assigning of roles (as Andrew suggested in Comment 1), and have linked
> to the detailed table on server roles that is in the General Configuration
> guide (which might be a bit hard to find in the docs currently).

That sounds excellent, thank you.

> 
> I also edited the descriptions of the User Interface and Web Services roles
> in the General Config guide to mention both should be enabled.
> 
> However -- the 4.5 General Configuration guide says both Web Services & User
> Interface are enabled by default. So is this perhaps only a problem in
> certain earlier versions of CloudForms? Do you know what version starts
> enabling Web Services by default?

I did a fresh install and can confirm the images we ship actually do have both roles enabled by default.  I think the previous confusion is from thinking "Web Services" is just for the API and the UI doesn't rely on it, therefore customers think "I do not need to expose the API, just turn the UI on for them" and that in turn stops the UI from being functional.  Since they are (reasonably) unaware that the UI relies upon the API, this is where the tickets come in for CEE.

> Also, if these roles are totally interdependent, I think there should be a
> product bug to maybe combine these two roles (or something similar). Is
> there an engineering bug for this?

Agreed, I spent some time looking around and as we move towards containerization it seems we're _more_ likely to make the UI dependant on the API, not less.

They're not totally required for each other.  I think flipping the User Interface role should also automatically enable the Web Services role, but you should be able to have the API functional without a UI on.  I can open a BZ for this.

> I'd love to hear your thoughts on the two docs fixes (in screenshots), and
> on my questions above. (@Andrew, would love to know if this is the approach
> you had in mind)

LGTM, one suggestion being that in GenConfig-rolesdescription.png we can also state in the Web Services role that it provides API access and doesn't necessarily need the User Interface role to work, but must be enabled if User Interface is on.  If you strictly want API-only access then Web Services can be enabled.  Overall, very clear and provides documentation we can point to.  Thanks!

Comment 5 Dayle Parker 2018-01-09 03:47:21 UTC
Hi Robb,

Thank you for your feedback and for the thorough explanation. I understand the issues much better now, and have edited the wording just a little bit so the idea of the role reliancy is now stated in the Deployment Planning Guide, and the difference between the two roles is clearer in the General Config guide, using your suggestion above.

It sounds like we probably don't need an engineering bug for this (now that i understand it more), especially as both roles are enabled by default -- but please let me know if you create one, in case it might affect the docs.

Thanks again for all your help :)
Dayle


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