Bug 1248220 - [Docs] [Director] Issues with overcloud package update documentation
[Docs] [Director] Issues with overcloud package update documentation
Product: Red Hat OpenStack
Classification: Red Hat
Component: documentation (Show other bugs)
Unspecified Unspecified
medium Severity medium
: ga
: Director
Assigned To: Dan Macpherson
Zane Bitter
: Documentation
Depends On:
  Show dependency treegraph
Reported: 2015-07-29 18:02 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:09 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:02:07 EDT
A small grab-bag of issues with section 7.7 (Updating the Overcloud):


* The title is potentially misleading, since this section refers to updating packages installed on nodes that make up the overcloud, not to making changes to the Heat stack named 'overcloud'.

* The title of section 7.7.2 has been copied-and-pasted from elsewhere, and refers to deleting nodes instead of updating packages.

* The explanation of the -i option is misleading, as it is implied that without this option no breakpoints will be set. In fact, breakpoints are always set. With the -i option, the CLI remains in the foreground and prompts the user to clear the breakpoints at the appropriate times. Without it, the CLI exits immediately and the user is left to clear the breakpoints manually (which is both non-obvious and almost impossible to do at the correct times and in the correct sequence). Note that if the user forgets to pass -i or if the CLI process dies for any reason (e.g. Ctrl-C), the user can resume an in-progress update by running the command again (and passing -i). Changes to the upstream docs that landed today make this a little clearer than it was: https://repos.fedorapeople.org/repos/openstack-m/docs/master/post_deployment/package_update.html
Comment 3 Andrew Dahms 2015-07-30 10:07:21 EDT
Assigning to Dan for review.
Comment 5 Zane Bitter 2015-08-05 10:38:20 EDT
The first two look good now, but the breakpoint part is still potentially misleading - this doesn't really describe the situation:

"The breakpoint process is usually automatic. However, the -i option provides an interactive mode that requires confirmation at each breakpoint."

The breakpoint process is automatic (with manual confirmations) when you specify the -i option.

When you don't specify the -i option, nothing happens at all. No packages are updated. The overcloud stack moves to the UPDATE_IN_PROGRESS state and stays there for several hours (holding a lock that prevents you from making other changes to the stack), until it finally times out and moves to UPDATE_FAILED without having ever attempted to update any packages. This is because the command line client, which is responsible for clearing the breakpoints, has exited, so Heat hits the first breakpoint and stops.

The user should always, always, always use -i, because that's the only way the breakpoints get cleared. If you accidentally run the command without -i (or you run it with -i but accidentally exit prematurely, e.g. with Ctrl-C), the fix is to run it again with -i - it will automatically detect the existing operation in progress and continue clearing breakpoints where it left off.
Comment 6 Dan Macpherson 2015-08-06 17:42:12 EDT
No prob, I can update this.

However, this also raises a question: Why have -i as an option if it's compulsory? If users should always include the -i, why not remove the -i option and make the -i happen automatically? Is there ever a situation where they wouldn't use -i?
Comment 7 Zane Bitter 2015-08-06 17:45:49 EDT
Yep, I agree it was probably a mistake to make it an option.
Comment 8 Dan Macpherson 2015-08-06 18:06:20 EDT
How does this sound:

Running an update on all nodes in parallel might cause problems. For example, an update of a package might involve restarting a service, which can disrupt other nodes. This is why the update process updates each node using a set of breakpoints. This means nodes are updated one by one. When one node completes the package update, the update process moves on to the next node.

The update process also requires the <option>-i</option> option. This puts the command an interactive mode that requires confirmation at each breakpoint. Without the <option>-i</option> option, the Overcloud nodes will not update their packages.
Comment 9 Zane Bitter 2015-08-06 18:13:58 EDT
A lot better. Consider changing the last sentence to something like:

"Without the <option>-i</option> option, the update will remain paused at the first breakpoint. The update process can be resumed by running the command again with the <option>-i</option> option."

so that people know how to recover when they inevitably miss the option out.
Comment 10 Dan Macpherson 2015-08-06 19:11:37 EDT
Good idea. Adding that in.
Comment 12 Dan Macpherson 2015-08-10 11:26:27 EDT
This is now live:


Zane, how are the changes? Anything else in that section that needs a fix?
Comment 13 Andrew Dahms 2016-01-11 05:09:09 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.