The number of new roles in OSA has dropped over time, as roles are added and the number of new projects being created within the OpenStack ecosystem slows up. This has meant the need to create new roles has dropped quite a bit. That said, I've been working through the process to add a role for the Manila project. I'll walk through the process, starting with the first step, setting up the base repository.

Setting up your repository

There are a few files in the base directory that are required for various reasons, and can easily be copied from the existing repositories that are up to date. I picked the os_cinder role, but it's a good idea to pick a role that is well maintained and use that as a base. Always keep in mind, the review process should help you catch anything you miss out - reviews are great, and while it doesn't mean you can be careless, it does mean that you're not alone!

Some base files

There are a few files that are common to all repos and you can pretty much just copy and edit.

.gitignore - this is common list of files that can easily be ignored by git, for example the testing repository that gets cloned during testing. You don't need to change anything there.

.gitreview - this file handles the git-review location, change the project field to match your new role's path.

CONTRIBUTING.rst - Contribution guidelines, this has a few references to the project in the title - other than that this is the same for each OSA role.

LICENSE - All OpenStack projects use the Apache 2.0 License, so this would be the same across all OSA roles.

README.rst - The README file really just links to the documentation for the role. Given this will be a new role it won't exist yet - but documentation is super important (I'll be covering that later!), in this case I'd edit the paths to match the new role, the links won't work at first but once your documentation is created it should.

bindep.txt - This file handles the packages that will get installed during gating. As a start copy the existing bindep.txt from another project. NB This is not packages that are required by the role specifically, but more packages that are required for gating to work successfully, prior to Ansible running. If the package is required by the role itself, it should be installed as part of the role.

setup.cfg - These handle the sphinx doc builds, as well as pbr and a few other things. You can copy these over directly. setup.cfg containers a few references to the role name, which should be changed.

tox.ini - This file determines how testing is setup and run, and which scenarios exist. This is a bit trickier because you don't want to copy all the existing scenarios. I would remove any scenarios (listed inside [ ]) that call the script, apart from the base [functional] job, as well as an [upgrade] job if it exists. This will remove any upgrade tests, as well as any additional scenarios (for example, the Keystone role carries a test to use Apache with uWSGI instead of the default NGINX with uWSGI), but won't remove any lint, pep8 or other generally good style tests. You can read more about tox here.

That's it for the main files in the base repository.
I'll cover over the next 4 main directories involved in a base repository in the following post.

  • doc directory
  • examples directory
  • meta directory
  • releasenotes directory

Aside from that, the only other non-ansible bits are the zuul.d and tests directories which we will discuss later.