Deployment guides

Deployment guides

As of the Newton release, a new method of publishing deployment guides has been implemented. This allows each deployment projects to create their own deployment guide, based on a standard template, in their own repository. These guides are then centrally published to Deployment Guides.

Note

This set up is designed for deployment projects to make their installation information public. This does not include further content for end users. For example, configuration content, troubleshooting, or administration procedures.

If you would like to refer users to more content, use cross reference links to your developer documentation within the guide.

Setting up

  1. Install cookiecutter:

    # pip install cookiecutter
    
  2. Run the Install Guide cookiecutter to create a skeleton for your project:

    Important

    The Install Guide cookiecutter is also used for the deployment guides. However, the rest of these instructions are specific to the deployment guide creation.

    $ cookiecutter https://git.openstack.org/openstack/installguide-cookiecutter.git --checkout HEAD^1
    

    You will be prompted to answer questions to complete the installation. Content is then added to the deploy-guide directory in the top-level of the project repository.

  3. Create a tox.ini environment for the deploy-guide in your project repository, using this content:

    [testenv:deploy-guide]
    commands = sphinx-build -a -E -W -d deploy-guide/build/doctrees -b html deploy-guide/source deploy-guide/build/html
    
  4. Add your deployment guide content, and test the build locally with tox:

    $ tox -e deploy-guide
    

    The local build is in deploy-guide/build/html.

  5. Add the Python package openstackdocstheme to the test-requirements.txt file. Copy the exact requirement line from the global file:

    openstackdocstheme>=1.5.0  # Apache-2.0
    
  6. Commit the changes to your project repository for review.

To create or update the master index file, create or update the www/project-deploy-guide/RELEASE/index.html file at the openstack-manuals repository.

For draft (unreleased) version, replace RELEASE with draft.

After these changes merge, you can set up the jobs for building in the OpenStack Infra project-config repository:

  1. Clone the project-config repo:

    $ git clone https://git.openstack.org/openstack-infra/project-config
    
  2. In jenkins/jobs/projects.yaml, add deploy-guide-jobs within the entry for your project:

    - project:
      name: <project-name>
    
      jobs:
      ...
       - deploy-guide-jobs:
           service: <service-name>
    

    project-name and service-name are the project name, and the specific serivce name. One example is orchestration for heat.

    This defines the jobs using the JJB deploy-guide-jobs job-template.

  3. In zuul/layout.yaml, locate the entry for your project and add the deploy-guide-jobs template:

    - name: openstack/<project-name>
      template:
        - name: deploy-guide-jobs
    

    This schedules the Deploy Guide jobs.

  4. Commit the changes to the infra repository for review.

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.