Overhaul of the current OpenStack-Ansible Installation Guide


2016-05-31 00:00



Blueprint: Overhaul of the current OpenStack-Ansible Installation Guide

After the 2016 Austin summit, there was a discussion and a consensus surrounding the current state of the OpenStack-Ansible Installation Guide.


A blueprint and spec were previously created with the intention of improving the documentation that pushed the summit discussion.

Currently, the OpenStack-Ansible install guide has minimal installation information, and a lot of configuration information. This specification proposes a more formalized plan to separate this information and streamline the installation guide to make it easier and quicker to install OpenStack.

Problem description

The OpenStack-Ansible Installation Guide contains information that does not necessarily pertain to that of an installation guide structure. It has accumulated a lot of configuration information and reference information that reduces the user’s focus and simplicity to install OpenStack.

The current installation guide also does not follow the openstack-manuals documentation conventions.

Proposed change

The main focus of the installation guide is reorganising and developing content so a deployer makes very few decisions and minimal configuration to deploy an OpenStack test environment and production environment.

The proposed changes are:

  • Clearly define reference architecture and develop use case configuration examples in an appendix.

  • Removal of the configuration information from the current installation guide and including it in the OpenStack-Ansible role documentation.

  • Migrate operations content temporarily to openstack-ansible-ops repo until an operations guide can be produced.

  • Restructure the guide to include basic deployment configuration.

  • Appendices that include configuration file examples, neutron plugins, cinder options and additional resources relevant to an OpenStack-Ansible installation.

  • Include links to role based documentation from the Installation Guide.


  • Leaving the installation guide as is, and migrating only the configuration information to the developer docs.

  • Consider revising the installation guide to meet criteria in project-specific installation guide and publish to docs.openstack.org

Playbook/Role impact


Upgrade impact


Security impact


Performance impact


End user impact

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

Deployer impact


Developer impact

Move existing content over to the roles first, then developers must submit any new documentation to the role repositories.





Primary assignee:

Alexandra Settle (asettle)

Other contributors:

Darren Chan (darrenc), Jesse Pretorius (odyssey4me), Travis Truman (automagically), Major Hayden (mhayden)

Work items

  • Clarify and obtain consensus on the content structure

  • Gather information from SMEs as needed

  • Create a draft directory for installation 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 follow the new installation guide to install OpenStack and evaluate if the information provided is accurate, clear, and concise.

Documentation impact

This is a documentation change, N/A.