kolla-ansible/doc/source/contributor/CONTRIBUTING.rst

How To Contribute

Basics

1. Our source code is hosted on OpenDev Kolla-Ansible Git. Bugs should be filed on launchpad.
2. Please follow OpenStack Gerrit Workflow to contribute to Kolla-ansible.
3. Note the branch you're proposing changes to. master is the current focus of development. Kolla project has a strict policy of only allowing backports in stable/branch, unless when not applicable. A bug in a stable/branch will first have to be fixed in master.
4. Please file a blueprint of kolla-ansible for any significant code change and a bug for any significant bug fix, or add a TrivialFix tag to commit message for simple changes. See how to reference a bug or a blueprint in the commit message.
5. TrivialFix tags or bugs are not required for documentation changes.
6. We use a whiteboard to keep track of CI gate status, release status, stable backports, planning and feature development status.

Development Environment

Please follow our /user/quickstart to deploy your environment and test your changes.

Please use the existing sandbox repository, available at sandbox, for learning, understanding and testing the Gerrit Workflow.

Adding a release note

Kolla Ansible (just like Kolla) uses the following release notes sections:

• features --- for new features or functionality; these should ideally refer to the blueprint being implemented;
• fixes --- for fixes closing bugs; these must refer to the bug being closed;
• upgrade --- for notes relevant when upgrading from previous version; these should ideally be added only between major versions; required when the proposed change affects behaviour in a non-backwards compatible way or generally changes something impactful;
• deprecations --- to track deprecated features; relevant changes may consist of only the commit message and the release note;
• prelude --- filled in by the PTL before each release or RC.

Other release note types may be applied per common sense. Each change should include a release note unless being a TrivialFix change or affecting only docs or CI. Such changes should not include a release note to avoid confusion. Remember release notes are mostly for end users which, in case of Kolla, are OpenStack administrators/operators. In case of doubt, the core team will let you know what is required.

To add a release note, run the following command:

tox -e venv -- reno new <summary-line-with-dashes>

All release notes can be inspected by browsing releasenotes/notes directory.

To generate release notes in HTML format in releasenotes/build, run:

tox -e releasenotes

Note this requires the release note to be tracked by git so you have to at least add it to the git's staging area.

Adding a new service

Kolla aims to both containerise and deploy all services within the OpenStack ecosystem. This is a constantly moving target as the ecosystem grows, so these guidelines aim to help make adding a new service to Kolla a smooth experience.

When adding a role for a new service in Ansible, there are couple of patterns that Kolla uses throughout that should be followed.

• The sample inventories

  Entries should be added for the service in each of ansible/inventory/multinode and ansible/inventory/all-in-one.

• The playbook

  The main playbook that ties all roles together is in ansible/site.yml, this should be updated with appropriate roles, tags, and conditions. Ensure also that supporting hosts such as haproxy are updated when necessary.

• The common role

  A common role exists which sets up logging, kolla-toolbox and other supporting components. This should be included in all services within meta/main.yml of your role.

• Common tasks

  All services should include the following tasks:

  • deploy.yml : Used to bootstrap, configure and deploy containers for the service.
  • reconfigure.yml : Used to push new configuration files to the host and restart the service.
  • pull.yml : Used to pre fetch the image into the Docker image cache on hosts, to speed up initial deploys.
  • upgrade.yml : Used for upgrading the service in a rolling fashion. May include service specific setup and steps as not all services can be upgraded in the same way.

• Logrotation

  • For OpenStack services there should be a cron-logrotate-PROJECT.conf.j2 template file in ansible/roles/common/templates with the following content:

    "/var/log/kolla/PROJECT/*.log"
    {
    }

  • For OpenStack services there should be an entry in the services list in the cron.json.j2 template file in ansible/roles/common/templates.

• Log delivery

  • For OpenStack services the service should add a new rewriterule in the match element in the 01-rewrite.conf.j2 template file in ansible/roles/common/templates/conf/filter to deliver log messages to Elasticsearch.

• Documentation

  • For OpenStack services there should be an entry in the list OpenStack services in the README.rst file.
  • For infrastructure services there should be an entry in the list Infrastructure components in the README.rst file.

• Syntax

  • All YAML data files should start with three dashes (---).

Other than the above, most service roles abide by the following pattern:

• Register: Involves registering the service with Keystone, creating endpoints, roles, users, etc.
• Config: Distributes the config files to the nodes to be pulled into the container on startup.
• Bootstrap: Creating the database (but not tables), database user for the service, permissions, etc.
• Bootstrap Service: Starts a one shot container on the host to create the database tables, and other initial run time config.

Ansible handlers are used to create or restart containers when necessary.