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/
Assigning to Dan for review.
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
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.
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?
This content is live on the Customer Portal. Closing.