Newton Installation Guide

Newton Installation Guide

Problem description

With the growing OpenStack Big Tent, many projects need to create install guides, new infrastructure is planned to enable projects to write and maintain their own install guides, and to have them published on as first class OpenStack citizens. As a complement to this, the current install guide needs to be updated and improved to ensure it remains a good source of installation information, with an increased focus on the fact that the install guide is used as training material, and is not recommended as a way to install clouds for production.

This spec proposes some changes to the install guide to meet this end, and is the product of discussion at the Newton design summit (see references).

Proposed change

The basic install guide serves as a reference to reach the first step where administrators have all the underlying services like MySQL and RabbitMQ and a base set of functionality installed and working. It is essential for every reader of the guide to have high-quality, proactively-checked, easy-to-understand content. The intent for a central, basic install guide is to train and orient readers so they can understand multiple OpenStack services while making informed decisions for their situation.

Then additional project-specific guides can be written that pick up from that base first step, assuming their readers have completed that first step successfully.

Scope of basic install guide

The content of the basic install guide will cover the infrastructure and centralized projects that every cloud needs. This includes the defcore projects defined as starter-kit:compute plus a few others:

  • Compute service (nova): Part of starter-kit:compute.
  • Image service (glance): Part of starter-kit:compute.
  • Identity service (keystone): Part of starter-kit:compute.
  • Networking service (neutron): Part of starter-kit:compute.
  • Block storage service (cinder): Part of current install guide and expected by most users.
  • Dashboard (horizon): Part of current install guide and expected by most users.

No further projects will be added to the guide unless they are required by one of the existing projects or generally required to run an OpenStack based cloud.

The documentation team updates and tests the basic install guide for each release.

The install guide will be enhanced to link to additional project specific install guides. For this, it will have in a separate chapter for each official project a small section where each official project can give a short summary of their project together with a link to their own install guide. The chapter will also explain that all these projects are first-class citizens of the big tent of OpenStack.

For example, Orchestration could store their install guide in the heat repository, and publish to .

Then the chapter “Additional projects” would contain a small section to introduce the service and link to it:

Orchestration service (heat)

The Orchestration service ...

Installation is documented at
. index

The project specific install guides will be listed not only in the install guide but also be found from the web page. An exact location will need to be found based on the number of guides.


  • Packaged install guides separated out, with no single-sourced install guide: each distribution publishes their own installation guide. These guides can be published to or to a web domain they own, sourced and reviewed from their own repositories with their teams. These teams can set their own publishing schedule. This alternative solution does not address the project teams needs, but alleviates the resource drain on a centralized docs team.

  • Stop writing package-based install guides in the OpenStack git namespace entirely. Instead, have a central team write a starter-kit-based guide that describes the multiple available deployment options and publish to This solution may be already available when readers browse the distro marketplace at

  • Each project team can write an “installation from source” installation guide that includes all the basic project infrastructure set up.

  • Change scope of install guide, add a few more or less projects as proposed in this spec to it. This does not address the current single- sourcing with packages problem described, however.

  • Status quo: One central install guide that is maintained by the documentation team and no project specific guides for those projects that are not part of the central guide. This approach does not scale unless we receive a commitment of resources from each project in the installation guide.

  • One central guide that is reviewed by the documentation team - like today - and only projects are documented when the project team has committed writing, testing, and updating the chapter.

    This does not scale since reviewing would still be done by the documentation team. Experience in the past has shown that project teams need to be reminded of their commitment, so in the end the documentation team would play a large coordination and shepherding role for such a large guide - instead of following the enablement role that is sought by this proposal.



  • Lana Brindley (loquacities) - Docs PTL
  • Andreas Jaeger (AJaeger) - Infrastructure
  • Install Guide Speciality Team

Work Items

  • Update the title (what to?) to reflect that it is for training and not production, and add preamble to explain that purpose.
  • Document from packages to best use existing content, but continue to revisit this problem over time, as more data emerges about which installation method users prefer.
  • Edit the existing content so that it uses manual configuration only.
  • Create scripts that can be run and automatically tested and include snippets of these scripts verbatim in the guide. This will accelerate testing of the guide.
  • Create a ‘cookie cutter’ template that can be used for all services (AJaeger):
  • Document the process of adding a big tent project under the new governance, including what tests and dependencies are required.
  • Move Shared File Systems (Manila), Object Storage (Swift), Orchestration (Heat), Telemetry (Ceilometer), Database (Trove) to project repositories and link them in the “Additional projects” chapter.



Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.