Merge "Documentation for adding roles to OSA"
This commit is contained in:
commit
976feceef3
135
doc/source/developer-docs/additional-roles.rst
Normal file
135
doc/source/developer-docs/additional-roles.rst
Normal file
@ -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
Block a user