Documentation for adding roles to OSA
Potential contributors, particularly those coming from other parts of the OpenStack community, have asked for guidance on how to add a role to OpenStack-Ansible for a particular service which is not currently represented. They may or may not be aquainted with Ansible already. This guide is not intended to teach them how to work with Ansible but rather to supplement the general Ansible documentation and provide guidance on what to do with Ansible to build a role for OpenStack-Ansible. Closes-Bug: #1535915 Change-Id: I4d03885ad2a91eb3c626ca444afdbadddef7cf31
This commit is contained in:
Steve Lewis
parent
8c0c41b8b3
commit
fdb0578b4d
|
|
@ -0,0 +1,135 @@
|
|||
`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/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
|
||||
|
|
@ -14,4 +14,5 @@ Contents:
|
|||
playbooks
|
||||
extending
|
||||
contribute
|
||||
additional-roles
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue