Bug 1411945 - [Docs][Installation] Installing Cloudforms 4.2 on RHEV, Section 2.4, Configuring an Internal Database, does not match the menu dialog
Summary: [Docs][Installation] Installing Cloudforms 4.2 on RHEV, Section 2.4, Configur...
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: Red Hat CloudForms Management Engine
Classification: Red Hat
Component: Documentation
Version: 5.7.0
Hardware: All
OS: All
high
high
Target Milestone: GA
: 5.7.0
Assignee: Dayle Parker
QA Contact: Red Hat CloudForms Documentation
URL:
Whiteboard: doc
: 1410529 1417397 (view as bug list)
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2017-01-10 19:47 UTC by Greg Scott
Modified: 2017-02-01 11:51 UTC (History)
13 users (show)

Fixed In Version:
Doc Type: If docs needed, set a value
Doc Text:
Clone Of:
Environment:
Last Closed: 2017-02-01 11:51:42 UTC
Category: ---
Cloudforms Team: ---
Target Upstream Version:


Attachments (Terms of Use)

Description Greg Scott 2017-01-10 19:47:00 UTC
Document URL: https://access.redhat.com/documentation/en/red-hat-cloudforms/4.2/paged/installing-red-hat-cloudforms-on-red-hat-enterprise-virtualization/

Section Number and Name: 2.4, Configuring an Internal Database

Describe the issue: 

Step 8 in the documentation is wrong.  The documentation shows one choice, choose a disk. In fact, the menu presents 2 choices.  1 - Choose a disk, and 2 - don't partition the disk.  Why does the menu offer choice #2 to not partition the database disk?  Why is there a menu choice to *not* partition it?  What happens if I select this choice?

After selecting choice 1, /dev/vdb, the next prompt is, 
"Configure this server as a dedicated database instance? (Y/N):"

I have no clue how to answer this question. Is it asking me if this server will act as a database server for other Cloudforms systems?  Or it is asking me if I want a plain, internal database instance? I'm in uncharted territory with a vague question in the menu and no guidance from the documentation.

I selected "N", and now the next prompt seems to match step 9. It asks for a database region number.  The documentation says enter a 3 digit number.  I entered "1" and the menu did not complain.  Why does the documentation want 3 digits, but the menu doesn't enforce it?  What will my "1" choice break?

And we're off the reservation again.  The next prompt asks for a database password and password confirmation.

Step 10 in the documentation never happens.  The menu asks for a *password* confirmation, but does not ask to confirm the configuration.

After I confirm the password, it never asks to confirm the configuration  Instead, it does this:

Activating the configuration using the following settings...
Host:     127.0.0.1
Username: root
Database: vmdb_production
Region:   1

Initialize postgresql disk starting
Initialize postgresql disk complete
Initialize postgresql starting
Initialize postgresql complete
Checking for connections to the database...

Create region starting
Create region complete

Configuration activated successfully.

Press any key to continue.


Suggestions for improvement: 

Make the documentation match the menu choices.  Explain what the choices mean when the menu wording is vague. Don't make me guess.  

Additional information:

Comment 2 Dayle Parker 2017-01-11 06:33:10 UTC
Thanks for filing this bug, Greg. 

I actually had another conversation today where this same issue was brought up; it turns out this needs fixing in all of the "Installing Cloudforms on X Platform" guides thanks to the appliance console menu change, so I'll take care of them all as part of this bug.

Comment 3 Dayle Parker 2017-01-19 07:42:41 UTC
*** Bug 1410529 has been marked as a duplicate of this bug. ***

Comment 4 Dayle Parker 2017-01-19 07:43:36 UTC
(In reply to Dayle Parker from comment #2)
> it turns out this needs fixing in all of the "Installing Cloudforms on X
> Platform" guides 

Loic noted in https://bugzilla.redhat.com/show_bug.cgi?id=1410529 that it's not present in the Installing on OpenShift Container Platform guide.

Comment 5 Dayle Parker 2017-01-19 09:36:15 UTC
Hi Marianne, Gregg, Loic,

Can you or someone on your team help with answers about new options in the appliance console database configuration steps for 4.2?

As Greg mentions above, the "2.4. Configuring an Internal Database" procedure in [1] and other install guides has changed.

In step 8, "Choose a disk for the database."
--> What do the two choices mean and when would you want to use each? What are the consequences of choosing each option below?

1) /dev/vdb: 4096 MB   (Is this the extra disk I added, or the appliance console VM's disk...?)
2) Don't partition the disk 

--> In the question "Configure this server as a dedicated database instance?" What do Yes and No lead to? From my testing, it seems that choosing "yes" configures an appliance with no UI (anything else to note)? And choosing "no" just appears to be how to install a regular CloudForms appliance. Is this correct?

--> When selecting a region number, our docs mention a 3-digit region number. Is a 3-digit number recommended? Or should we change it to "specify a region number of up to 3 digits"?

[1] https://access.redhat.com/documentation/en/red-hat-cloudforms/4.2/paged/installing-red-hat-cloudforms-on-red-hat-enterprise-virtualization/

Thanks for your help!
Cheers,
Dayle

Comment 7 Marianne Feifer 2017-01-20 15:47:01 UTC
Nick, any chance you can help out in GT's absence?

Comment 8 Nick Carboni 2017-01-20 16:37:20 UTC
(In reply to Dayle Parker from comment #5)
> Hi Marianne, Gregg, Loic,
> 
> Can you or someone on your team help with answers about new options in the
> appliance console database configuration steps for 4.2?
> 
> As Greg mentions above, the "2.4. Configuring an Internal Database"
> procedure in [1] and other install guides has changed.
> 
> In step 8, "Choose a disk for the database."
> --> What do the two choices mean and when would you want to use each? What
> are the consequences of choosing each option below?

This prompt is only displayed if there is an unpartitioned disk attached to the VM. If there is not one, you will get the following:

No partition found for database disk. You probably want to add an unpartitioned
disk and try again.
Are you sure you don't want to partion the database disk? (Y/N):

It is highly recommended (and in some cased required https://bugzilla.redhat.com/show_bug.cgi?id=1387672) that users use a separate volume for the database. This should also probably be noted somewhere.

> 
> 1) /dev/vdb: 4096 MB   (Is this the extra disk I added, or the appliance
> console VM's disk...?)

This is the option that should be selected in nearly every use case, but it is up to the user to know which device file corresponds to the disk they want to use for the database.

This option will create a logical volume using this device and mount the volume to the appliance in a location appropriate for storing the database. In 5.7 this is /var/opt/rh/rh-postgresql95/lib/pgsql and can be found in the environment variable $APPLIANCE_PG_MOUNT_POINT.

> 2) Don't partition the disk 

Selecting this option will lead to us using the root filesystem for the data directory. And is also a bad idea (like the note above about always using a separate disk).

> 
> --> In the question "Configure this server as a dedicated database
> instance?" What do Yes and No lead to? From my testing, it seems that
> choosing "yes" configures an appliance with no UI (anything else to note)?
> And choosing "no" just appears to be how to install a regular CloudForms
> appliance. Is this correct?

There has been a good amount of discussion already around this question's wording. This (https://github.com/ManageIQ/manageiq-gems-pending/pull/27) change specifically should clear this up. That change adds more clarity to the prompt and adds a default (N) which will be what most users want and what would get you the same behavior as all the previous versions (i.e. configure the database and start evmserverd locally). This change will be present in the 5.7.1 errata.

> 
> --> When selecting a region number, our docs mention a 3-digit region
> number. Is a 3-digit number recommended? Or should we change it to "specify
> a region number of up to 3 digits"?

There is no reason to specify a particular length. Technically region numbers can range from 0 to 9,223,371 inclusive, but the convention is to use lower numbers for remote regions (0-10) and 99 for the global region.

> 
> [1]
> https://access.redhat.com/documentation/en/red-hat-cloudforms/4.2/paged/
> installing-red-hat-cloudforms-on-red-hat-enterprise-virtualization/
> 
> Thanks for your help!
> Cheers,
> Dayle

Let me know if any of that needs more clarification.

Nick

Comment 9 Dayle Parker 2017-01-25 04:34:07 UTC
Hi Nick,

Thanks for all the info, and sorry for my delay in replying. I've made changes to the procedure with the info above -- would you mind having a look and letting me know of any corrections needed?

In case it's easier, I created a PR (but can't figure out how to add you as a reviewer):
https://github.com/ManageIQ/manageiq_docs/pull/210

Many thanks!
Dayle

Comment 10 Nick Carboni 2017-01-25 13:44:09 UTC
Added a few comments to the PR.

Comment 11 Andrew Dahms 2017-01-31 00:27:01 UTC
*** Bug 1417397 has been marked as a duplicate of this bug. ***

Comment 12 Dayle Parker 2017-01-31 00:29:18 UTC
Thanks for your review, Nick!

Suyog, would you mind peer reviewing this and merging please?

https://github.com/ManageIQ/manageiq_docs/pull/210

Many thanks,
Dayle

Comment 14 Dayle Parker 2017-02-01 11:51:42 UTC
Thank you for your reviews, Suyog!

The procedure for "Configuring an Internal Database" has been updated with the new appliance console workflow for CloudForms 4.2. 

This content is now updated and live in the following guides:

* Installing Red Hat CloudForms on Amazon Elastic Compute Cloud
https://access.redhat.com/documentation/en/red-hat-cloudforms/4.2/single/installing-red-hat-cloudforms-on-amazon-elastic-compute-cloud-amazon-ec2/


* Installing Red Hat CloudForms on Red Hat Enterprise Linux OpenStack Platform
https://access.redhat.com/documentation/en/red-hat-cloudforms/4.2/single/installing-red-hat-cloudforms-on-red-hat-enterprise-linux-openstack-platform/


* Installing Red Hat CloudForms on Red Hat Enterprise Virtualization
https://access.redhat.com/documentation/en/red-hat-cloudforms/4.2/single/installing-red-hat-cloudforms-on-red-hat-enterprise-virtualization/


* Installing Red Hat CloudForms on VMware vSphere
https://access.redhat.com/documentation/en/red-hat-cloudforms/4.2/single/installing-red-hat-cloudforms-on-vmware-vsphere/


* Installing Red Hat CloudForms on Google Compute Engine
https://access.redhat.com/documentation/en/red-hat-cloudforms/4.2/single/installing-red-hat-cloudforms-on-google-compute-engine/


* Installing Red Hat CloudForms on Microsoft Azure
https://access.redhat.com/documentation/en/red-hat-cloudforms/4.2/single/installing-red-hat-cloudforms-on-microsoft-azure/


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