aa0be5a88b
This patch adds missing navigation links to pages which currently don't have them in order to ensure consistency in the documentation. Change-Id: Ibc1e756ddd0ba959251c6430db1796d63e3517b0
140 lines
7.3 KiB
ReStructuredText
140 lines
7.3 KiB
ReStructuredText
`Home <index.html>`_ OpenStack-Ansible Developer Documentation
|
|
|
|
Adding new Roles and Services
|
|
=============================
|
|
|
|
If you would like to contribute towards a role to introduce an OpenStack
|
|
service or an infrastructure service to support an OpenStack deployment, the
|
|
OpenStack-Ansible project would welcome that contribution and your assistance
|
|
in maintaining it.
|
|
|
|
Recommended procedure to develop a Role
|
|
---------------------------------------
|
|
|
|
#. Deploy OpenStack-Ansible (possibly using
|
|
`an AIO`_
|
|
deploy) so that you have the rest of an OpenStack cluster to integrate with
|
|
in your testing.
|
|
#. Deploy your service on another VM, or possibly directly on the AIO host, by
|
|
hand. Configure the service to coordinate with the OpenStack cluster
|
|
appropriately. When all the related systems are communicating with each
|
|
other you can use the resulting configuration as a reference later.
|
|
#. Develop a role for your service. A recommended process is detailed below.
|
|
|
|
.. _an AIO: quickstart-aio.html
|
|
|
|
Writing the 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, 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:
|
|
|
|
#. You can review roles which may be currently in development by checking our
|
|
`specs repository`_ and `unmerged specs`_ on review.openstack.org. If you
|
|
do not find a spec for the role, propose a blueprint/spec `(see also the
|
|
spec template)`_ outlining the new Role. By proposing a draft spec you can
|
|
help the OpenStack-Ansible community keep track of what roles are being
|
|
developed and perhaps connect you with others who may be interested and
|
|
able to help you in the process.
|
|
#. Create a source repository (e.g. on Github) to start your work on the Role.
|
|
#. Generate the reference directory structure for an Ansible role which is
|
|
the necessary subset of the documented `Best Practice`_. You might use
|
|
Ansible Galaxy tools to do this for you (e.g. ``ansible-galaxy init``).
|
|
You may additionally want to include directories such as ``docs`` and
|
|
``examples`` and ``tests`` for your 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
|
|
file modifications). Also take care that file ownership and permissions are
|
|
appropriate.
|
|
|
|
.. HINT:: Fill in variable defaults, libraries, and prerequisites as you
|
|
discover a need for them. You can also develop documentation for your
|
|
role at the same time.
|
|
|
|
.. _(see also the spec template): https://github.com/openstack/openstack-ansible-specs/blob/master/specs/template.rst
|
|
.. _specs repository: https://github.com/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
|
|
|
|
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
|
|
are particular to your service.
|
|
#. Generate files to include your service in the Ansible inventory
|
|
using `env.d`_ and `conf.d`_ files for use on your deploy host.
|
|
|
|
.. HINT:: You can follow examples from other roles, making the appropriate
|
|
modifications being sure that group labels in ``env.d`` and ``conf.d``
|
|
files are consistent.
|
|
|
|
#. Generate secrets, if any, `as described in the Install Guide`_. You can
|
|
append your keys to an existing ``user_secrets.yml`` file or add a new file
|
|
to the ``openstack_deploy`` directory to contain them. Provide overrides
|
|
for any other variables you will need at this time as well, either in
|
|
``user_variables.yml`` or another file. This is explained in more depth
|
|
under `Extending OpenStack-Ansible`_.
|
|
#. If your service is installed from source or relies on python packages which
|
|
need to be installed from source, specify a repository for the source
|
|
code of each requirement by adding a file to your deploy host under
|
|
``playbooks/defaults/repo_packages`` in the OpenStack-Ansible source repository
|
|
and following the pattern of files currently in that directory. You could
|
|
also simply add an entry to an existing file there. Be sure to run the
|
|
``repo-build.yml`` play later so that wheels for your packages will be
|
|
included in the repository infrastructure.
|
|
#. Make any required adjustments to the load balancer configuration
|
|
(e.g. modify ``playbooks/vars/configs/haproxy_config.yml`` in the
|
|
OpenStack-Ansible source repository on your deploy host) so that your
|
|
service can be reached through a load balancer, if appropriate, and be sure
|
|
to run the ``haproxy-install.yml`` play later so your changes will be
|
|
applied.
|
|
#. Put together a service install playbook file for your role. This can also
|
|
be modeled from any existing service playbook that has similar
|
|
dependencies to your service (database, messaging, storage drivers,
|
|
container mount points, etc.). A common place to keep playbook files in a
|
|
Galaxy role is in an ``examples`` directory off the root of the role.
|
|
|
|
.. HINT:: If you adhere to the pattern of isolating your role's extra
|
|
deployment requirements (secrets and var files, HAProxy yml fragments,
|
|
repo_package files, etc.) in their own files it makes it easy for you to
|
|
automate these additional steps when testing your role.
|
|
|
|
.. _Adding Galaxy roles: extending.html#adding-galaxy-roles
|
|
.. _env.d: extending.html#env-d
|
|
.. _conf.d: extending.html#conf-d
|
|
.. _as described in the Install Guide: ../install-guide/configure-creds.html#configuring-service-credentials
|
|
.. _Extending OpenStack-Ansible: extending.html#user-yml-files
|
|
|
|
--------------
|
|
|
|
.. include:: navigation.txt
|