Bug 1248223 - Document passing extra environment files to openstack overcloud commands
Document passing extra environment files to openstack overcloud commands
Product: Red Hat OpenStack
Classification: Red Hat
Component: documentation (Show other bugs)
Unspecified Unspecified
high Severity urgent
: ga
: Director
Assigned To: Dan Macpherson
Zane Bitter
: Documentation
Depends On:
  Show dependency treegraph
Reported: 2015-07-29 18:20 EDT by Zane Bitter
Modified: 2016-01-11 05:09 EST (History)
2 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Last Closed: 2016-01-11 05:09:21 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---

Attachments (Terms of Use)

  None (edit)
Description Zane Bitter 2015-07-29 18:20:02 EDT
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 10:06:20 EDT
Assigning to Dan for review.
Comment 5 Zane Bitter 2015-08-05 10:49:51 EDT
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 9 Andrew Dahms 2016-01-11 05:09:21 EST
This content is live on the Customer Portal.


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