[Docs] Describe variable files locations
Our best practices don't include variable files locations. This should fix it. Change-Id: Ic80afad76b425ec46e6ffb04d9de795ee71184e8
This commit is contained in:
Jean-Philippe Evrard
parent
a474993ad7
commit
2a0766bb54
@ -7,7 +7,7 @@ or infrastructure service, or to improve an existing role, the
|
||||
OpenStack-Ansible project would welcome that contribution and your assistance
|
||||
in maintaining it.
|
||||
|
||||
Recommended procedure to develop a Role
|
||||
Recommended procedure to develop a role
|
||||
---------------------------------------
|
||||
|
||||
#. Deploy OpenStack-Ansible (possibly using
|
||||
@ -22,36 +22,10 @@ Recommended procedure to develop a Role
|
||||
|
||||
.. _an AIO: quickstart-aio.html
|
||||
|
||||
Writing a new Role
|
||||
Writing a new role
|
||||
------------------
|
||||
Most OpenStack services will follow a common series of stages to install or
|
||||
update a service deployment. This is apparent when you review `tasks/main.yml`
|
||||
for existing roles.
|
||||
|
||||
#. pre-install: prepare the service user group and filesystem directory paths
|
||||
on the host or container
|
||||
#. install: install system packages, prepare the (optional) service virtual
|
||||
environment, install service and requirements (into a virtual environment)
|
||||
#. post-install: apply all configuration files
|
||||
#. messaging and db setup: db user and database prepared, message queue vhost
|
||||
and user prepared
|
||||
#. service add: register the service (each of: service type, service project,
|
||||
service user, and endpoints) within Keystone's service catalog.
|
||||
#. service setup: install a service-startup script (init, upstart, SystemD,
|
||||
etc.) so that the service will start up when the container or host next
|
||||
starts.
|
||||
#. service init/startup: signal to the host or container to start the services
|
||||
|
||||
There may be other specialized steps required by some services but most of the
|
||||
roles will perform all of these at a minimum. Begin by reviewing a role for a
|
||||
service that has something in common with your service and think about how you
|
||||
can fit most of the common service setup and configuration steps into that
|
||||
model.
|
||||
|
||||
.. HINT:: Following the patterns you find in other roles can help ensure your role
|
||||
is easier to use and maintain.
|
||||
|
||||
Steps to writing the role:
|
||||
Here are the steps to write the role:
|
||||
|
||||
#. You can review roles which may be currently in development by checking our
|
||||
`specs repository`_ and `unmerged specs`_ on review.openstack.org. If you
|
||||
@ -69,6 +43,7 @@ Steps to writing the role:
|
||||
#. Generate a meta/main.yml right away. This file is important to Ansible to
|
||||
ensure your dependent roles are installed and available and provides others
|
||||
with the information they will need to understand the purpose of your role.
|
||||
|
||||
#. Develop task files for each of the install stages in turn, creating any
|
||||
handlers and templates as needed. Ensure that you notify handlers after any
|
||||
task which impacts the way the service would run (such as configuration
|
||||
@ -79,13 +54,50 @@ Steps to writing the role:
|
||||
discover a need for them. You can also develop documentation for your
|
||||
role at the same time.
|
||||
|
||||
#. Add tests to the role.
|
||||
#. Ensuring the role deploys with an AIO.
|
||||
|
||||
Writing tasks in a role
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Most OpenStack services will follow a common series of stages to install or
|
||||
update a service deployment. This is apparent when you review `tasks/main.yml`
|
||||
for existing roles.
|
||||
|
||||
#. pre-install: prepare the service user group and filesystem directory paths
|
||||
on the host or container
|
||||
#. install: install system packages, prepare the (optional) service virtual
|
||||
environment, install service and requirements (into a virtual environment)
|
||||
#. post-install: apply all configuration files
|
||||
#. service add: register the service (each of: service type, service project,
|
||||
service user, and endpoints) within Keystone's service catalog.
|
||||
#. service setup: install a service-startup script (init, upstart, systemd,
|
||||
etc.) so that the service will start up when the container or host next
|
||||
starts.
|
||||
#. service init/startup: signal to the host or container to start the services,
|
||||
make sure the service runs on boot.
|
||||
|
||||
There may be other specialized steps required by some services but most of the
|
||||
roles will perform all of these at a minimum. Begin by reviewing a role for a
|
||||
service that has something in common with your service and think about how you
|
||||
can fit most of the common service setup and configuration steps into that
|
||||
model.
|
||||
|
||||
.. HINT:: Following the patterns you find in other roles can help ensure your role
|
||||
is easier to use and maintain.
|
||||
|
||||
.. _(see also the spec template): https://git.openstack.org/cgit/openstack/openstack-ansible-specs/tree/specs/templates/template.rst
|
||||
.. _specs repository: https://git.openstack.org/cgit/openstack/openstack-ansible-specs
|
||||
.. _unmerged specs: https://review.openstack.org/#/q/status:+open+project:openstack/openstack-ansible-specs
|
||||
.. _Best Practice: https://docs.ansible.com/ansible/playbooks_best_practices.html#directory-layout
|
||||
|
||||
Adding tests to a Role
|
||||
----------------------
|
||||
Keep in mind a role candidate for inclusion should respect our
|
||||
`Ansible Style Guide`_.
|
||||
|
||||
.. _Ansible Style Guide: contribute.html#ansible-style-guide
|
||||
|
||||
Adding tests to a role
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Each of the role tests is in its tests/ folder.
|
||||
|
||||
@ -110,9 +122,9 @@ This folder contains at least the following files:
|
||||
|
||||
.. _tests repository: https://git.openstack.org/cgit/openstack/openstack-ansible-tests
|
||||
|
||||
Deploying the role
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Deploying the Role
|
||||
------------------
|
||||
#. Include your role on the deploy host. See also `Adding Galaxy roles`_.
|
||||
#. Perform any other host preparation (such as the tasks performed by the
|
||||
``bootstrap-aio.yml`` playbook). This includes any preparation tasks that
|
||||
|
||||
@ -314,6 +314,35 @@ The following convention is used:
|
||||
|
||||
* A tag including the word ``upgrade`` handles all the upgrade tasks.
|
||||
|
||||
Variable files conventions
|
||||
--------------------------
|
||||
|
||||
The variables files in a role are split in 3 locations:
|
||||
|
||||
#. The `defaults/main.yml` file
|
||||
#. The `vars/main.yml` file
|
||||
#. The `vars/<platform specific>.yml` file
|
||||
|
||||
The variables with lower priority should be in the `defaults/main.yml`.
|
||||
This allows their overriding with group variables or host variables.
|
||||
A good example for this are default database connection details, default
|
||||
queues connection details, or debug mode.
|
||||
|
||||
In other words, `defaults/main.yml` contains variables that are meant to
|
||||
be overridable by a deployer or a continuous integration system.
|
||||
These variables should be limited as much as possible, to avoid
|
||||
increasing the test matrix.
|
||||
|
||||
The `vars/main.yml` is always included. It contains generic
|
||||
variables that aren't meant to be changed by a deployer. This includes
|
||||
for example static information that aren't distribution specific (like
|
||||
aggregation of role internal variables for example).
|
||||
|
||||
The `vars/<platform specific>.yml` is the place where distribution
|
||||
specific content will be stored. For example, this file will hold
|
||||
the package names, repositories urls and keys, file paths, service
|
||||
names/init scripts.
|
||||
|
||||
Development cycle checklist
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user