Architecture Design Guide Restructure

Architecture Design Guide Restructure

Problem description

Currently, the Architecture Design Guide is primarily organised by use case. However, a combination of features from different use cases is often used when designing an OpenStack cloud.

It is recommended to reorganise information so the user can consider all the requirements, to help determine their OpenStack cloud architecture. Additional information should be provided when designing an OpenStack cloud in a development, staged or production environment. The proposal is to develop a more detailed structure that creates an abstraction between cloud architecture concepts and various OpenStack projects. This will make it easier to maintain and update the guide.

Proposed change

The proposed structure of the guide is to first describe common cloud use cases, then general architectural concepts, followed by a Design chapter with a detailed breakdown of the major cloud architecture components.

The section headings in the Design chapter would be as follows:

  1. Technical Detail
  2. Capacity and Scale
  3. High Availability
  4. Operator Requirements
  5. Deployment Considerations
  6. Maintenance Considerations

The headings are intended as a guideline to the type of information that should be provided. It will be used only when there is a specific need to call out the information.

Proposed Table of Contents

The new proposed structure for the Architecture Design Guide is as follows:

  1. General Overview

  2. Use Cases

    1. Development Cloud
      1. Stakeholder
      2. User Stories
      3. Design Model
      4. Component Block Diagram
    2. General Compute Cloud
      1. Stakeholders
      2. User Stories
      3. Design Model
      4. Component Block Diagram
    3. Web Scale Cloud
      1. Stakeholders
      2. User Stories
      3. Design Model
      4. Component Block Diagram
    4. Public Cloud
      1. Stakeholders
      2. User Stories
      3. Design Model
      4. Component Block Diagram
  3. High Availability

    1. Overview
  4. Capacity and Scale

    1. Overview
  5. Design

    1. Compute

      All topics related to the implementation of the compute platform, i.e. hypervisors, nova, ironic, etc.

    2. Storage

      All topics related to storage choices and the implementation of projects like cinder, manila, etc.

    3. Networking

      All topics related to networking design choices such as SDN, LBaaS and neutron.

    4. Identity

      Topics about authentication, authorisation and assignment at all levels for keystone and any other related projects.

    5. Image

      Topics about the management, creation, distribution and deployment of images for glance and other related projects.

    6. Control Plane

      Topics discussing the general implementation of the OpenStack control components and the decision making that goes into the choices that need to be made.

    7. Dashboard and APIs

      Topics about the interaction with cloud services using a graphical interface or the OpenStack APIs. This would include horizon and other Cloud Management Platform (CMP) tools.


Leave the guide as is



Primary assignee:
  • shilla-saebi
Other contributors:
  • dazzachan
  • shaunom

Work Items

  • Reach a consensus on the information architecture
  • Rework the abstract to clearly identify the audience and purpose of the book
  • Move content to improve information architecture
  • Identify information gaps and submit and fix bugs




Testing will follow the standard documentation review process.


  • Discussion can occur using any official medium including IRC in #openstack-doc, the openstack-docs mailing list with [arch-guide] in the subject, biweekly Ops Guide specialty team meeting, weekly documentation team meeting, and potentially etherpads.
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.