diff --git a/doc/source/actions.rst b/doc/source/actions.rst new file mode 100644 index 0000000..4f2cc79 --- /dev/null +++ b/doc/source/actions.rst @@ -0,0 +1,8 @@ +======= +Actions +======= + +.. toctree:: + :glob: + + actions/* diff --git a/doc/source/actions/config_template.rst b/doc/source/actions/config_template.rst new file mode 100644 index 0000000..d4ac03e --- /dev/null +++ b/doc/source/actions/config_template.rst @@ -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: """ diff --git a/doc/source/actions/dist_sort.rst b/doc/source/actions/dist_sort.rst new file mode 100644 index 0000000..606e25d --- /dev/null +++ b/doc/source/actions/dist_sort.rst @@ -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: """ diff --git a/doc/source/actions/keystone.rst b/doc/source/actions/keystone.rst new file mode 100644 index 0000000..2b2e834 --- /dev/null +++ b/doc/source/actions/keystone.rst @@ -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: """ diff --git a/doc/source/actions/magnum.rst b/doc/source/actions/magnum.rst new file mode 100644 index 0000000..5c9fd7a --- /dev/null +++ b/doc/source/actions/magnum.rst @@ -0,0 +1,13 @@ +magnum +~~~~~~~~ + +Synopsis +-------- +Manage OpenStack magnum cluster templates. + +Examples +-------- +.. literalinclude:: ../../../library/magnum + :language: yaml + :start-after: EXAMPLES = """ + :end-before: """ diff --git a/doc/source/actions/memcached.rst b/doc/source/actions/memcached.rst new file mode 100644 index 0000000..d3c6389 --- /dev/null +++ b/doc/source/actions/memcached.rst @@ -0,0 +1,13 @@ +memcached +~~~~~~~~~ + +Synopsis +-------- +Add, remove, and get items from memcached. + +Examples +-------- +.. literalinclude:: ../../../library/memcached + :language: yaml + :start-after: EXAMPLES = """ + :end-before: """ diff --git a/doc/source/actions/name2int.rst b/doc/source/actions/name2int.rst new file mode 100644 index 0000000..328090a --- /dev/null +++ b/doc/source/actions/name2int.rst @@ -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: """ diff --git a/doc/source/actions/neutron.rst b/doc/source/actions/neutron.rst new file mode 100644 index 0000000..01491f4 --- /dev/null +++ b/doc/source/actions/neutron.rst @@ -0,0 +1,13 @@ +neutron +~~~~~~~ + +Synopsis +-------- +Basic module for interacting with OpenStack neutron. + +Examples +-------- +.. literalinclude:: ../../../library/neutron + :language: yaml + :start-after: EXAMPLES = """ + :end-before: """ diff --git a/doc/source/actions/provider_networks.rst b/doc/source/actions/provider_networks.rst new file mode 100644 index 0000000..f16ed80 --- /dev/null +++ b/doc/source/actions/provider_networks.rst @@ -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: """ diff --git a/doc/source/callbacks.rst b/doc/source/callbacks.rst new file mode 100644 index 0000000..8ab75be --- /dev/null +++ b/doc/source/callbacks.rst @@ -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. diff --git a/doc/source/filters.rst b/doc/source/filters.rst new file mode 100644 index 0000000..317bbaa --- /dev/null +++ b/doc/source/filters.rst @@ -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 diff --git a/doc/source/index.rst b/doc/source/index.rst index 8fcee1a..72f1942 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 - - diff --git a/doc/source/lookups.rst b/doc/source/lookups.rst new file mode 100644 index 0000000..9c96330 --- /dev/null +++ b/doc/source/lookups.rst @@ -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" + # } + # }