SUSE OpenStack Cloud Documentation

This is the source for the official SUSE OpenStack Cloud documentation.

The following guides are available:

• SUSE OpenStack Cloud:

  • Deployment Guide

  • Operations Guide

• SUSE OpenStack Cloud Crowbar:

  • Deployment Guide

  • Operations Guide

  • Crowbar Proof of Concept Guide

• SUSE OpenStack Cloud, General:

  • Security Guide

  • Supplement to Administrator Guide and User Guide

These guides are all maintained and created in this GitHub repository. Released versions of these guides have been published at https://documentation.suse.com/soc.

The following guides are built directly from upstream OpenStack sources:

• Administration Guide

• User Guide

These guides are all maintained upstream in the various OpenStack project repositories. Released versions of the upstream OpenStack guides have been built using the suse_sphinx_theme.

Released versions of these guides have also been published at https://documentation.suse.com/soc.

Licensing

Guides for the SUSE OpenStack Cloud documentation are licensed using Creative Commons 3.0: https://creativecommons.org/licenses/by/3.0/legalcode

Some parts of the guides are pre-existing Fujitsu content, which is licensed with Apache 2.0: https://www.apache.org/licenses/LICENSE-2.0

Upstream OpenStack guides are licensed using a combination of Creative Commons 3.0: https://creativecommons.org/licenses/by/3.0/legalcode and Apache 2.0: https://www.apache.org/licenses/LICENSE-2.0

Branches

Important

Do not add further changes to the master branch! It is only used as an archive now. In the final months of 2019 and in early Jan 2020, we maintained two branches in the doc-cloud repo: master maintenance/cloud_9 (cloud_9 for short) The original plan was to use master for SOC 10 documentation. Since SOC 10 was cancelled, we were in a less than perfect situation: The cloud_9 was several commits ahead of master and in turn, the master branch had some SOC 9 content that had not been backported to cloud_9. To solve the problem and to simplify the overall arrangement, we have merged the outstanding commits from master into cloud_9. We also made cloud_9 the default branch. For all SOC 9-related documentation updates, please use maintenance/cloud_9. We do not foresee further active use of the master branch. It will be kept purely as an archive.

• Use the maintenance/cloud_9 branch as the basis of your commits for new feature branches.

• The master branch serves as an archive only. If you add changes to the master branch, they may never be published.

• The develop branch has been deleted on the server. Do not push a new develop branch.

Table 1. Overview of important branches

Name	Purpose
maintenance/cloud_9	Maintenance branch for SOC 9 (default)
master	Archive branch
maintenance/cloud_1.0	Maintenance branch for SC 1.0
maintenance/cloud_2.0	Maintenance branch for SC 2.0
maintenance/cloud_3.0	Maintenance branch for SC 3.0
maintenance/cloud_4	Maintenance branch for SC 4
maintenance/cloud_5	Maintenance branch for SC 5
maintenance/openstack_cloud_6	Maintenance branch for SOC 6
maintenance/cloud_7	Maintenance branch for SOC 7
maintenance/cloud_8	Maintenance branch for SOC 8

• If you created a local clone or GitHub fork of this repo before June 21, 2019, do the following:

  1. Make sure that your master and develop branches do not contain any important changes. If there are on either branch, export them using git format-patch or put them on a different branch.

  2. Update the repo: git fetch (To also delete references to branches that do not exist anymore on the server, you can use git fetch -p.)

  3. Go to the master branch: git checkout master

  4. Hard-reset the state of the master branch to the state on GitHub: git reset --hard origin/master

  5. Delete your local develop branch: git branch -D develop

Contributing

Thank you for contributing to this repo. Please adhere to the following guidelines when creating a pull request:

1. Make your pull request against the master branch (not develop) if you are contributing to the most recent release (currently Cloud 10). The master branch is protected and cannot be merged without review.

2. If you are contributing to a previous release, please see maintenance/cloud<RELEASENUMBER>_. This branch is also protected and cannot be merged without review.

3. Your contributions can be in ASCIIdoc .adoc or DocBook XML .xml.

4. Commit messages must conform to the following:

   1. Line lengths must be 80 characters or less.

   2. Commit body content is required.

   3. The subject line cannot start with "SOC".

   4. At the end of the subject line, there must be a bug reference or an explanation for a missing bug reference:

      • Bugzilla or Jira references: (bsc#0123456) or (SOC-0123456)

      • Multiple Bugzilla or Jira references: (bsc#0123456),(SOC-0123456)

      • One of (trivial), (typo), or (noref). No combinations are allowed.

5. Make sure all validation (Travis CI) checks are passed, and tag relevant SMEs from the development team (if applicable) and members of the Cloud doc team: Carl Symons (@csymons-suse), Dmitri Popov (@dmpop) or Alexandra Settle (@asettle).

   **NOTE:** If your pull request has multiple files and reorganization changes, please build locally using DAPS or daps2docker
   (see instructions below) to verify and build the files. Travis CI only validates, and does not ensure the XML builds
   are correct.

6. Implement any required changes, or fix any merge conflicts if relevant. If you have any questions, ping a documentation team member in #cloud-documentation on RocketChat.

7. Once a review has been received from a documentation team member and any other SMEs, please merge your own PR.

   **NOTE:** If you need something merged ASAP, and a documentation team member is not available to re-review, but you have
   implemented any necessary changes, please use your best judgement and merge your own PR if STRICTLY NECESSARY. Alert
   a team member by pinging them in the #cloud-documentation channel.

Building documentation

If you’re contributing to the cloud documentation in this repo and want to build using our DAPS tooling, see the DAPS Quickstart for more information: https://opensuse.github.io/daps/doc/art.daps.quick.html

If you are interested in building DAPS documentation (defaulting to HTML and PDF), you can utilize our daps2docker project: https://github.com/openSUSE/daps2docker

1. Install Docker

2. Clone the daps2docker repository.

3. Run ./daps2docker.sh /PATH/TO/DOC-DIR or /daps2docker.sh /PATH/TO/DC-FILE.

Running Travis-CI tests locally

You can run the Travis-CI validation tests locally using the travis-validate.sh script. Note that Docker is required.

Building upstream docs

If you’re required to build the upstream Administration and User Guides, you can build and view each individual guide upstream: https://docs.openstack.org/doc-contrib-guide/docs-builds.html

If you want to build the SUSE version, equivalent to what is published at at documentation.suse.com, see the instructions on how to build here: https://github.com/SUSE-Cloud/doc-cloud-upstream/blob/rocky/README

Quick start building the docs

Assuming daps is already installed, call

daps -d DC-suse-openstack-cloud-crowbar-operations html

You can build other DC files and also other formats (e.g. PDF) of course.