Create Operations Guide


2016-12-19 17:00


docs, ops

Blueprint: Create OpenStack-Ansible Operations Guide *

This specification proposes the development of an OpenStack-Ansible Operations Guide for the Ocata release.

Problem description

During the Newton development cycle, the Installation Guide was revised which focused on providing a method for installing OpenStack for a test environment and production environment. As noted in the Installation Guide spec, the operations content did not belong in the Installation Guide as it reduced the user’s focus to install OpenStack, and was temporarily relocated to the following Developer Documentation pages:

There is a need to develop a standalone Openstack-Ansible operations guide that will address an operator’s need for information on managing and configuring an OpenStack cloud using OpenStack-Ansible.

Proposed change

The main focus of the operations guide is to re-organise the current content and develop new content so an OpenStack operator can easily search for information on maintaining their environment, troubleshooting, and resolving issues.

The proposed changes are:

  • A new ToC with input from developers and operations:

  • Removal of duplicated content from the OpenStack manuals operations guide (so that this guide focuses primarily upon OpenStack-Ansible operations).

  • Structuring the guide in a ‘runbook’ format for the following reasons:

    1. Ensuring the guide includes lower-level how-to’s for anyone starting to operate their own cloud.

    2. Ensuring the guide includes higher-level troubleshooting information for more experienced operator.

    3. It is structured to make it easy for operators to find the information they are looking for.

  • Review and update current operations content to follow the openstack-manuals documentation conventions.


  • The current operations content and any future content will remain in the Developer Documentation.

Playbook/Role impact


Upgrade impact


Security impact


Performance impact


End user impact

These changes will improve the end user experience, by providing a more structured and better flow of information to operate your OpenStack cloud.

Deployer impact


Developer impact






Primary assignee:

Alexandra Settle (asettle)

Other contributors:

Andy McCrae (andymccr), OpenStack-Ansible PTL Darren Chan (darrenc) Robb Romans (rromans)

Work items

  • Clarify and obtain consensus on the content structure

  • Gather information from SMEs as needed

  • Create a draft directory for operations guide changes

  • Create a work items list and allocate resources

  • Ensure documentation meets openstack-manuals writing conventions

  • Test draft documentation before publication


The testing will be conducted by the community once a draft is available. OpenStack-Ansible users will be asked to utilise the new operations guide to perform the OpenStack operations and evaluate if the information provided is accurate, clear, and concise.

Documentation impact

This is a documentation change, N/A.