Bug 1248223

Summary:	Document passing extra environment files to openstack overcloud commands
Product:	Red Hat OpenStack	Reporter:	Zane Bitter <zbitter>
Component:	documentation	Assignee:	Dan Macpherson <dmacpher>
Status:	CLOSED CURRENTRELEASE	QA Contact:	Zane Bitter <zbitter>
Severity:	urgent	Docs Contact:
Priority:	high
Version:	Director	CC:	adahms, yeylon
Target Milestone:	ga	Keywords:	Documentation
Target Release:	Director
Hardware:	Unspecified
OS:	Unspecified
Whiteboard:
Fixed In Version:		Doc Type:	Bug Fix
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2016-01-11 10:09:21 UTC	Type:	Bug
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:

Description Zane Bitter 2015-07-29 22:20:02 UTC

It is common to customise overclouds by passing extra environment files to the "openstack overcloud deploy" command - in particular, network isolation is configured in this way. Whenever this is the case, the user must also pass the same extra environment files to any command that results in an update of the overcloud stack in Heat, such as:

* openstack overcloud deploy (for modifying or scaling up an existing overcloud)
* openstack overcloud node delete
* openstack overcloud update stack

Failure to include the environment files on a subsequent update will result in Heat attempting to reconfigure the stack as if they were never passed. This will always be bad news for the user, and in the case of network isolation specifically it is known to leave the Heat stack in an unrecoverable state. Therefore it is imperative that we remind the user at every possible opportunity that they must include any extra environment files with every command. Appropriate sections to do this would be:

* 7.3 Scaling the Overcloud
* 7.4 Removing Nodes from the Overcloud
* 7.7 Updating the Overcloud
* 6.2.6 Scenario 2: Using the CLI to Create a Basic Overcloud -> Creating the Overcloud
* 6.3.7 Scenario 3: Using the CLI to Create an Advanced Overcloud with Ceph Nodes -> Creating the Overcloud

This upstream docs patch gives a good guide: https://review.gerrithub.io/#/c/240812/

Comment 3 Andrew Dahms 2015-07-30 14:06:20 UTC

Assigning to Dan for review.

Comment 4 Dan Macpherson 2015-08-04 18:26:32 UTC

I've not notes in the following sections regarding adding the additional environment files.

Basic Scenario:
http://file.bne.redhat.com/~dmacpher/OpenStack/7.0/Director/#sect-Creating_the_Basic_Overcloud

Advanced Scenario:
http://file.bne.redhat.com/~dmacpher/OpenStack/7.0/Director/#sect-Advanced-Creating_the_Advanced_Overcloud

Post Deployment Functions:
Scaling - http://file.bne.redhat.com/~dmacpher/OpenStack/7.0/Director/#sect-Scaling_the_Overcloud
Removing Nodes - http://file.bne.redhat.com/~dmacpher/OpenStack/7.0/Director/#sect-Removing_Nodes_from_the_Overcloud
Updating Overcloud Packages - http://file.bne.redhat.com/~dmacpher/OpenStack/7.0/Director/#sect-Updating_Overcloud_Packages

Comment 5 Zane Bitter 2015-08-05 14:49:51 UTC

The parts in the Post Deployment Functions sections look good. However, the parts in the Basic/Advanced Scenario seem to vague to convey both the meaning and level of seriousness of the warning:

"Note the environment files added to the Overcloud using the -e option. The director uses these environment files for certain functions in Chapter 7, Performing Tasks after Overcloud Creation."

It's not that the environment files are used for certain functions per se, it's that they form part of the stack's definition and must be passed to every command that updates the stack otherwise the stack will be updated with a bogus definition. So something along the lines of:

"If you pass any extra environment files using the -e option, you must pass the same environment files to any subsequent commands that accept them, as detailed in Chapter 7, Performing Tasks after Overcloud Creation. Failure to include these files may, and likely will, result in irretrievable destruction of your overcloud."

would make more explicit both what the user needs to do and the importance of not forgetting to do it.

Comment 8 Dan Macpherson 2015-08-10 15:28:06 UTC

This is now live:

https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux_OpenStack_Platform/7/html/Director_Installation_and_Usage/sect-Advanced-Scenario_3_Using_the_CLI_to_Create_an_Advanced_Overcloud_with_Ceph_Nodes.html#sect-Advanced-Creating_the_Advanced_Overcloud

Zane, how are the changes? Is there anything else related to this item that needs a fix?

Comment 9 Andrew Dahms 2016-01-11 10:09:21 UTC

This content is live on the Customer Portal.

Closing.