[DOCS] Add docs for plugins
Add basic information and examples for the action, callback, filter, and lookup plugins provided by this repo. Partial-Bug: 1579091 Change-Id: If7cea759bb790c6f6d266eff560ac7a67309219d
This commit is contained in:
Jimmy McCrory
parent
14d2727c04
commit
5202eb38dd
8
doc/source/actions.rst
Normal file
8
doc/source/actions.rst
Normal file
@ -0,0 +1,8 @@
|
||||
=======
|
||||
Actions
|
||||
=======
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
|
||||
actions/*
|
||||
22
doc/source/actions/config_template.rst
Normal file
22
doc/source/actions/config_template.rst
Normal file
@ -0,0 +1,22 @@
|
||||
config_template
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Synopsis
|
||||
--------
|
||||
Renders template files providing a create/update override interface
|
||||
|
||||
- The module contains the template functionality with the ability to override
|
||||
items in config, in transit, through the use of a simple dictionary without
|
||||
having to write out various temp files on target machines. The module renders
|
||||
all of the potential jinja a user could provide in both the template file and
|
||||
in the override dictionary which is ideal for deployers who may have lots of
|
||||
different configs using a similar code base.
|
||||
- The module is an extension of the **copy** module and all of attributes that
|
||||
can be set there are available to be set here.
|
||||
|
||||
Examples
|
||||
--------
|
||||
.. literalinclude:: ../../../library/config_template
|
||||
:language: yaml
|
||||
:start-after: EXAMPLES = """
|
||||
:end-before: """
|
||||
20
doc/source/actions/dist_sort.rst
Normal file
20
doc/source/actions/dist_sort.rst
Normal file
@ -0,0 +1,20 @@
|
||||
dist_sort
|
||||
~~~~~~~~~
|
||||
|
||||
Synopsis
|
||||
--------
|
||||
Deterministically sort a list to distribute the elements in the list evenly.
|
||||
Based on external values such as host or static modifier. Returns a string as
|
||||
named key ``sorted_list``.
|
||||
|
||||
- This module returns a list of servers uniquely sorted based on a index from a
|
||||
look up value location within a group. The group should be an existing
|
||||
Ansible inventory group. This will module returns the sorted list as a
|
||||
delimited string.
|
||||
|
||||
Examples
|
||||
--------
|
||||
.. literalinclude:: ../../../library/dist_sort
|
||||
:language: yaml
|
||||
:start-after: EXAMPLES = """
|
||||
:end-before: """
|
||||
13
doc/source/actions/keystone.rst
Normal file
13
doc/source/actions/keystone.rst
Normal file
@ -0,0 +1,13 @@
|
||||
keystone
|
||||
~~~~~~~~
|
||||
|
||||
Synopsis
|
||||
--------
|
||||
Manage OpenStack Identity (keystone) users, projects, roles, and endpoints.
|
||||
|
||||
Examples
|
||||
--------
|
||||
.. literalinclude:: ../../../library/keystone
|
||||
:language: yaml
|
||||
:start-after: EXAMPLES = """
|
||||
:end-before: """
|
||||
13
doc/source/actions/magnum.rst
Normal file
13
doc/source/actions/magnum.rst
Normal file
@ -0,0 +1,13 @@
|
||||
magnum
|
||||
~~~~~~~~
|
||||
|
||||
Synopsis
|
||||
--------
|
||||
Manage OpenStack magnum cluster templates.
|
||||
|
||||
Examples
|
||||
--------
|
||||
.. literalinclude:: ../../../library/magnum
|
||||
:language: yaml
|
||||
:start-after: EXAMPLES = """
|
||||
:end-before: """
|
||||
13
doc/source/actions/memcached.rst
Normal file
13
doc/source/actions/memcached.rst
Normal file
@ -0,0 +1,13 @@
|
||||
memcached
|
||||
~~~~~~~~~
|
||||
|
||||
Synopsis
|
||||
--------
|
||||
Add, remove, and get items from memcached.
|
||||
|
||||
Examples
|
||||
--------
|
||||
.. literalinclude:: ../../../library/memcached
|
||||
:language: yaml
|
||||
:start-after: EXAMPLES = """
|
||||
:end-before: """
|
||||
13
doc/source/actions/name2int.rst
Normal file
13
doc/source/actions/name2int.rst
Normal file
@ -0,0 +1,13 @@
|
||||
name2int
|
||||
~~~~~~~~
|
||||
|
||||
Synopsis
|
||||
--------
|
||||
Hash a host name and return an integer.
|
||||
|
||||
Examples
|
||||
--------
|
||||
.. literalinclude:: ../../../library/name2int
|
||||
:language: yaml
|
||||
:start-after: EXAMPLES = """
|
||||
:end-before: """
|
||||
13
doc/source/actions/neutron.rst
Normal file
13
doc/source/actions/neutron.rst
Normal file
@ -0,0 +1,13 @@
|
||||
neutron
|
||||
~~~~~~~
|
||||
|
||||
Synopsis
|
||||
--------
|
||||
Basic module for interacting with OpenStack neutron.
|
||||
|
||||
Examples
|
||||
--------
|
||||
.. literalinclude:: ../../../library/neutron
|
||||
:language: yaml
|
||||
:start-after: EXAMPLES = """
|
||||
:end-before: """
|
||||
13
doc/source/actions/provider_networks.rst
Normal file
13
doc/source/actions/provider_networks.rst
Normal file
@ -0,0 +1,13 @@
|
||||
provider_networks
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Synopsis
|
||||
--------
|
||||
Parse a list of networks and return data that Ansible can use.
|
||||
|
||||
Examples
|
||||
--------
|
||||
.. literalinclude:: ../../../library/provider_networks
|
||||
:language: yaml
|
||||
:start-after: EXAMPLES = """
|
||||
:end-before: """
|
||||
9
doc/source/callbacks.rst
Normal file
9
doc/source/callbacks.rst
Normal file
@ -0,0 +1,9 @@
|
||||
=========
|
||||
Callbacks
|
||||
=========
|
||||
|
||||
Debug message collector
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This plugin watches for debug tasks, collects the messages from those tasks,
|
||||
and displays them at the end of the playbook run.
|
||||
166
doc/source/filters.rst
Normal file
166
doc/source/filters.rst
Normal file
@ -0,0 +1,166 @@
|
||||
=======
|
||||
Filters
|
||||
=======
|
||||
|
||||
bit_length_power_of_2
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
This filter will return the smallest power of 2 greater than a given numeric
|
||||
value.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
{{ 1000 | bit_length_power_of_2 }}
|
||||
# => 1024
|
||||
|
||||
deprecated
|
||||
~~~~~~~~~~
|
||||
This filter will return the old_var value, if defined, along with a
|
||||
deprecation warning that will inform the user that the old variable
|
||||
should no longer be used.
|
||||
|
||||
In order to use this filter the old and new variable names must be provided
|
||||
to the filter as a string which is used to render the warning message. The
|
||||
removed_in option is used to give a date or release name where the old
|
||||
option will be removed. Optionally, if fatal is set to True, the filter
|
||||
will raise an exception if the old variable is used.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
old_var: "old value"
|
||||
old_var_name: "old_var"
|
||||
new_var_name: "new_var"
|
||||
removed_in: "Next release"
|
||||
fatal_deprecations: false
|
||||
|
||||
{{ new_var | deprecated(old_var,
|
||||
old_var_name,
|
||||
new_var_name,
|
||||
removed_in,
|
||||
fatal_deprecations) }}
|
||||
# WARNING => Deprecated Option provided: Deprecated variable:
|
||||
# "old_var", Removal timeframe: "Next release", Future usage:
|
||||
# "new_var"
|
||||
# => "old value"
|
||||
|
||||
git_link_parse
|
||||
~~~~~~~~~~~~~~
|
||||
This filter will return a dict containing the parts of a given git repo URL.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
{{ 'https://git.openstack.org/openstack/openstack-ansible@master' |
|
||||
git_link_parse }}
|
||||
# =>
|
||||
# {
|
||||
# "url": "https://git.openstack.org/openstack/openstack-ansible",
|
||||
# "plugin_path": null,
|
||||
# "version": "master",
|
||||
# "name": "openstack-ansible",
|
||||
# "original":
|
||||
# "https://git.openstack.org/openstack/openstack-ansible@master"
|
||||
# }
|
||||
|
||||
git_link_parse_name
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
This filter will return the name of a given git repo URL.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
{{ 'https://git.openstack.org/openstack/openstack-ansible@master' |
|
||||
git_link_parse_name }}
|
||||
# => "openstack-ansible"
|
||||
|
||||
filtered_list
|
||||
~~~~~~~~~~~~~
|
||||
This filter takes two lists as inputs. The first list will be returned to the
|
||||
user after removing any duplicates found within the second list.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
{{ ['a', 'b'] | filtered_list(['b', 'c']) }}
|
||||
# => [ "a" ]
|
||||
|
||||
netloc
|
||||
~~~~~~
|
||||
This filter will return the netloc from a given URL.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
{{ 'https://172.29.236.100:5000/v3/auth/tokens' | netloc }}
|
||||
# => "172.29.236.100:5000"
|
||||
|
||||
netloc_no_port
|
||||
~~~~~~~~~~~~~~
|
||||
This filter will return the netloc, without a port, from a given URL.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
{{ 'https://172.29.236.100:5000/v3/auth/tokens' | netloc_no_port }}
|
||||
# => "172.29.236.100"
|
||||
|
||||
netorigin
|
||||
~~~~~~~~~
|
||||
This filter will return the scheme and netloc from a given URL.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
{{ 'https://172.29.236.100:5000/v3/auth/tokens' | netorigin }}
|
||||
# => "https://172.29.236.100:5000"
|
||||
|
||||
pip_constraint_update
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
This filter will return a merged list from a given list of pip packages and a
|
||||
list of pip package constraints to a apply to that list.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
pip_package_list:
|
||||
- pip==8.1.2
|
||||
- setuptools==25.1.0
|
||||
- wheel==0.29.0
|
||||
pip_package_constraint_list:
|
||||
- babel==2.3.4
|
||||
- pip==8.1.0
|
||||
|
||||
{{ pip_package_list | pip_constraint_update(pip_package_constraint_list) }}
|
||||
# => [ "babel==2.3.4", "pip==8.1.0", "setuptools==25.1.0", "wheel==0.29.0" ]
|
||||
|
||||
pip_requirement_names
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
This filter will return of list of package names from a given list of pip
|
||||
packages.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
pip_package_list:
|
||||
- pip==8.1.2
|
||||
- setuptools==25.1.0
|
||||
- wheel==0.29.0
|
||||
|
||||
{{ pip_package_list | pip_requirement_names }}
|
||||
# => [ "pip", "setuptools", "wheel" ]
|
||||
|
||||
splitlines
|
||||
~~~~~~~~~~
|
||||
This filter will return of list from a string with line breaks.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
string_with_line_breaks: |
|
||||
a string
|
||||
with
|
||||
line
|
||||
breaks
|
||||
|
||||
{{ string_with_line_breaks | splitlines }}
|
||||
# => [ "a string", "with", "line", "breaks" ]
|
||||
|
||||
string_2_int
|
||||
~~~~~~~~~~~~
|
||||
This filter will hash a given string, convert it to a base36 int, and return
|
||||
the modulo of 10240.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
{{ 'openstack-ansible' | string_2_int }}
|
||||
# => 3587
|
||||
@ -2,52 +2,15 @@
|
||||
OpenStack-Ansible plugins
|
||||
=========================
|
||||
|
||||
Actions
|
||||
~~~~~~~
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
This project provides the Ansible modules:
|
||||
actions.rst
|
||||
callbacks.rst
|
||||
filters.rst
|
||||
lookups.rst
|
||||
|
||||
* config_template
|
||||
* dist_sort
|
||||
* keystone
|
||||
* memcached
|
||||
* name2int
|
||||
* neutron
|
||||
* provider_networks
|
||||
|
||||
Filters
|
||||
~~~~~~~
|
||||
|
||||
This project provides the Ansible Jinja2 filters:
|
||||
|
||||
* bit_length_power_of_2
|
||||
* netloc
|
||||
* netloc_no_port
|
||||
* netorigin
|
||||
* string_2_int
|
||||
* pip_requirement_names
|
||||
* pip_constraint_update
|
||||
* splitlines
|
||||
* filtered_list
|
||||
* git_link_parse
|
||||
* git_link_parse_name
|
||||
* deprecated
|
||||
|
||||
Lookups
|
||||
~~~~~~~
|
||||
|
||||
This project provides the lookup:
|
||||
|
||||
* with_py_pkgs
|
||||
|
||||
Callbacks
|
||||
~~~~~~~~~
|
||||
|
||||
This project provides an Ansible callback that will report
|
||||
task profiling timings
|
||||
|
||||
|
||||
Example ``ansible.cfg`` file
|
||||
Example ansible.cfg file
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. literalinclude:: ../../examples/example.ini
|
||||
@ -57,12 +20,10 @@ Example ``ansible.cfg`` file
|
||||
Example role requirement overload for automatic plugin download
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Ansible role requirement file can be used to overload the ``ansible-
|
||||
galaxy`` command to automatically fetch the plugins for you in a given
|
||||
project. To do this add the following lines to your ``ansible-role-
|
||||
requirements.yml`` file.
|
||||
The Ansible role requirement file can be used to overload the
|
||||
``ansible-galaxy`` command to automatically fetch the plugins for
|
||||
you in a given project. To do this add the following lines to your
|
||||
``ansible-role-requirements.yml`` file.
|
||||
|
||||
.. literalinclude:: ../../examples/playbook.yml
|
||||
:language: yaml
|
||||
|
||||
|
||||
|
||||
170
doc/source/lookups.rst
Normal file
170
doc/source/lookups.rst
Normal file
@ -0,0 +1,170 @@
|
||||
=======
|
||||
Lookups
|
||||
=======
|
||||
|
||||
py_pkgs
|
||||
~~~~~~~
|
||||
The ``py_pkgs`` lookup crawls a given list of directories to parse variables
|
||||
and generate lists of Python packages, git repo information and Ansible group
|
||||
memberships which is used within OpenStack-Ansible's repo_build role to build
|
||||
wheels and virtual environments.
|
||||
|
||||
Files and paths containing the following strings are evaluated:
|
||||
- test-requirements.txt
|
||||
- dev-requirements.txt
|
||||
- requirements.txt
|
||||
- global-requirements.txt
|
||||
- global-requirement-pins.txt
|
||||
- /defaults/
|
||||
- /vars/
|
||||
- /user_*
|
||||
|
||||
Variables parsed within any evaluated files include:
|
||||
- service_pip_dependencies
|
||||
- pip_common_packages
|
||||
- pip_container_packages
|
||||
- pip_packages
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
- name: Load local packages
|
||||
debug:
|
||||
msg: "Loading Packages"
|
||||
with_py_pkgs: "{{ pkg_locations }}"
|
||||
register: local_packages
|
||||
vars:
|
||||
pkg_locations:
|
||||
- "/etc/ansible/roles/os_nova"
|
||||
# => {
|
||||
# "packages": [
|
||||
# "httplib2",
|
||||
# "keystonemiddleware",
|
||||
# "libvirt-python",
|
||||
# "nova",
|
||||
# "nova-lxd",
|
||||
# "nova-powervm",
|
||||
# "pyasn1-modules",
|
||||
# "pycrypto",
|
||||
# "pylxd",
|
||||
# "pymysql",
|
||||
# "python-ironicclient",
|
||||
# "python-keystoneclient",
|
||||
# "python-memcached",
|
||||
# "python-novaclient",
|
||||
# "virtualenv",
|
||||
# "virtualenv-tools",
|
||||
# "websockify"
|
||||
# ],
|
||||
# "remote_package_parts": [
|
||||
# {
|
||||
# "egg_name": "nova",
|
||||
# "fragment": null,
|
||||
# "name": "nova",
|
||||
# "original":
|
||||
# "git+https://git.openstack.org/openstack/nova@stable/newton#egg=nova&gitname=nova&projectgroup=all",
|
||||
# "project_group": "all",
|
||||
# "url": "https://git.openstack.org/openstack/nova",
|
||||
# "version": "stable/newton"
|
||||
# },
|
||||
# {
|
||||
# "egg_name": "nova_lxd",
|
||||
# "fragment": null,
|
||||
# "name": "nova-lxd",
|
||||
# "original":
|
||||
# "git+https://git.openstack.org/openstack/nova-lxd@stable/newton#egg=nova_lxd&gitname=nova-lxd&projectgroup=all",
|
||||
# "project_group": "all",
|
||||
# "url": "https://git.openstack.org/openstack/nova-lxd",
|
||||
# "version": "stable/newton"
|
||||
# },
|
||||
# {
|
||||
# "egg_name": "novnc",
|
||||
# "fragment": null,
|
||||
# "name": "novnc",
|
||||
# "original":
|
||||
# "git+https://github.com/kanaka/novnc@master#egg=novnc&gitname=novnc&projectgroup=all",
|
||||
# "project_group": "all",
|
||||
# "url": "https://github.com/kanaka/novnc",
|
||||
# "version": "master"
|
||||
# },
|
||||
# {
|
||||
# "egg_name": "spice_html5",
|
||||
# "fragment": null,
|
||||
# "name": "spice-html5",
|
||||
# "original":
|
||||
# "git+https://github.com/SPICE/spice-html5@master#egg=spice_html5&gitname=spice-html5&projectgroup=all",
|
||||
# "project_group": "all",
|
||||
# "url": "https://github.com/SPICE/spice-html5",
|
||||
# "version": "master"
|
||||
# }
|
||||
# ],
|
||||
# "remote_packages": [
|
||||
# "git+https://git.openstack.org/openstack/nova-lxd@stable/newton#egg=nova_lxd&gitname=nova-lxd&projectgroup=all",
|
||||
# "git+https://git.openstack.org/openstack/nova@stable/newton#egg=nova&gitname=nova&projectgroup=all",
|
||||
# "git+https://github.com/SPICE/spice-html5@master#egg=spice_html5&gitname=spice-html5&projectgroup=all",
|
||||
# "git+https://github.com/kanaka/novnc@master#egg=novnc&gitname=novnc&projectgroup=all"
|
||||
# ],
|
||||
# "role_packages": {
|
||||
# "os_nova": [
|
||||
# "httplib2",
|
||||
# "keystonemiddleware",
|
||||
# "libvirt-python",
|
||||
# "nova",
|
||||
# "nova-lxd",
|
||||
# "nova-powervm",
|
||||
# "pyasn1-modules",
|
||||
# "pycrypto",
|
||||
# "pylxd",
|
||||
# "pymysql",
|
||||
# "python-ironicclient",
|
||||
# "python-keystoneclient",
|
||||
# "python-memcached",
|
||||
# "python-novaclient",
|
||||
# "virtualenv",
|
||||
# "virtualenv-tools",
|
||||
# "websockify"
|
||||
# ]
|
||||
# },
|
||||
# "role_project_groups": {
|
||||
# "os_nova": "nova_all"
|
||||
# },
|
||||
# "role_requirement_files": {},
|
||||
# "role_requirements": {
|
||||
# "os_nova": {
|
||||
# "nova_compute_ironic_pip_packages": [
|
||||
# "python-ironicclient"
|
||||
# ],
|
||||
# "nova_compute_lxd_pip_packages": [
|
||||
# "nova-lxd",
|
||||
# "pylxd"
|
||||
# ],
|
||||
# "nova_compute_pip_packages": [
|
||||
# "libvirt-python"
|
||||
# ],
|
||||
# "nova_compute_powervm_pip_packages": [
|
||||
# "nova-powervm",
|
||||
# "pyasn1-modules"
|
||||
# ],
|
||||
# "nova_novnc_pip_packages": [
|
||||
# "websockify"
|
||||
# ],
|
||||
# "nova_pip_packages": [
|
||||
# "keystonemiddleware",
|
||||
# "nova",
|
||||
# "pycrypto",
|
||||
# "pymysql",
|
||||
# "python-keystoneclient",
|
||||
# "python-memcached",
|
||||
# "python-novaclient"
|
||||
# ],
|
||||
# "nova_requires_pip_packages": [
|
||||
# "httplib2",
|
||||
# "python-keystoneclient",
|
||||
# "virtualenv",
|
||||
# "virtualenv-tools"
|
||||
# ],
|
||||
# "project_group": "nova_all"
|
||||
# }
|
||||
# }
|
||||
Loading…
Reference in New Issue
Block a user