openstack
/
openstack-ansible-plugins
Code Issues Proposed changes

[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 2017-02-16 03:35:20 -08:00
parent 14d2727c04
commit 5202eb38dd
13 changed files with 484 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
doc/source/actions.rst Normal file
View File

@ -0,0 +1,8 @@
=======
Actions
=======
.. toctree::
:glob:
actions/*

22
doc/source/actions/config_template.rst Normal file
View 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
View 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
View 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
View 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
View 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
View 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
View 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
View 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
View 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
View 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

61
doc/source/index.rst
View File

@ -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
View 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"
# }
# }