Ansible docs are generated from <ahref="https://github.com/ansible/ansible">GitHub sources</a> using <ahref="http://sphinx-doc.org/">Sphinx</a> using a theme provided by <ahref="http://readthedocs.org">Read the Docs</a>. {% if pagename.endswith("_module") %}Module documentation is not edited directly, but is generated from the source code for the modules. To submit an update to module docs, edit the 'DOCUMENTATION' metadata in the <ahref="https://github.com/ansible/ansible/tree/devel/lib/ansible/modules">modules directory</a> of the <ahref="https://github.com/ansible/ansible/">core source code repository</a>. {% endif %}
Ansible docs are generated from <ahref="https://github.com/ansible/ansible">GitHub sources</a> using <ahref="http://sphinx-doc.org/">Sphinx</a> using a theme provided by <ahref="http://readthedocs.org">Read the Docs</a>.
Ansible docs are generated from <ahref="https://github.com/ansible/ansible">GitHub sources</a> using <ahref="http://sphinx-doc.org/">Sphinx</a> using a theme provided by <ahref="http://readthedocs.org">Read the Docs</a>. {% if pagename.endswith("_module") %}Module documentation is not edited directly, but is generated from the source code for the modules. To submit an update to module docs, edit the 'DOCUMENTATION' metadata in the <ahref="https://github.com/ansible/ansible/tree/devel/lib/ansible/modules">modules directory</a> of the <ahref="https://github.com/ansible/ansible/">core source code repository</a>. {% endif %}
Ansible docs are generated from <ahref="https://github.com/ansible/ansible">GitHub sources</a> using <ahref="http://sphinx-doc.org/">Sphinx</a> using a theme provided by <ahref="http://readthedocs.org">Read the Docs</a>.
@ -23,6 +23,64 @@ Ansible accepts code via **pull requests** ("PRs" for short). GitHub provides a
Because Ansible receives many pull requests, we use an automated process to help us through the process of reviewing and merging pull requests. That process is managed by **Ansibullbot**.
Because Ansible receives many pull requests, we use an automated process to help us through the process of reviewing and merging pull requests. That process is managed by **Ansibullbot**.
Backport Pull Request Process
-----------------------------
After the pull request submitted to Ansible for the ``devel`` branch is
accepted and merged, the following instructions will help you create a
pull request to backport the change to a previous stable branch.
..note::
These instructions assume that ``stable-2.5`` is the targeted release
branch for the backport.
..note::
These instructions assume that ``https://github.com/ansible/ansible.git``
is configured as a ``git remote`` named ``upstream``. If you do not use
a ``git remote`` named ``upstream``, adjust the instructions accordingly.
..note::
These instructions assume that ``https://github.com/<yourgithubaccount>/ansible.git``
is configured as a ``git remote`` named ``origin``. If you do not use
a ``git remote`` named ``origin``, adjust the instructions accordingly.
#. Prepare your devel, stable, and feature branches:
The Cisco Application Centric Infrastructure (ACI) allows application requirements to define the network. This architecture simplifies, optimizes, and accelerates the entire application deployment life cycle.
The Cisco Application Centric Infrastructure (ACI) allows application requirements to define the network. This architecture simplifies, optimizes, and accelerates the entire application deployment life cycle.
The Cisco Application Policy Infrastructure Controller (APIC) API enables applications to directly connect with a secure, shared, high-performance resource pool that includes network, compute, and storage capabilities.
The APIC manages the scalable ACI multi-tenant fabric. The APIC provides a unified point of automation and management, policy programming, application deployment, and health monitoring for the fabric. The APIC, which is implemented as a replicated synchronized clustered controller, optimizes performance, supports any application anywhere, and provides unified operation of the physical and virtual infrastructure.
The APIC manages the scalable ACI multi-tenant fabric. The APIC provides a unified point of automation and management, policy programming, application deployment, and health monitoring for the fabric. The APIC, which is implemented as a replicated synchronized clustered controller, optimizes performance, supports any application anywhere, and provides unified operation of the physical and virtual infrastructure.
The APIC enables network administrators to easily define the optimal network for applications. Data center operators can clearly see how applications consume network resources, easily isolate and troubleshoot application and infrastructure problems, and monitor and profile resource usage patterns.
The APIC enables network administrators to easily define the optimal network for applications. Data center operators can clearly see how applications consume network resources, easily isolate and troubleshoot application and infrastructure problems, and monitor and profile resource usage patterns.
The Cisco Application Policy Infrastructure Controller (APIC) API enables applications to directly connect with a secure, shared, high-performance resource pool that includes network, compute, and storage capabilities.
ACI Fabric
ACI Fabric
..........
..........
The Cisco Application Centric Infrastructure (ACI) Fabric includes Cisco Nexus 9000 Series switches with the APIC to run in the leaf/spine ACI fabric mode. These switches form a "fat-tree" network by connecting each leaf node to each spine node; all other devices connect to the leaf nodes. The APIC manages the ACI fabric.
The Cisco Application Centric Infrastructure (ACI) Fabric includes Cisco Nexus 9000 Series switches with the APIC to run in the leaf/spine ACI fabric mode. These switches form a "fat-tree" network by connecting each leaf node to each spine node; all other devices connect to the leaf nodes. The APIC manages the ACI fabric.
@ -30,6 +35,7 @@ All the switch nodes contain a complete copy of the concrete model. When an admi
The APIC is responsible for fabric activation, switch firmware management, network policy configuration, and instantiation. While the APIC acts as the centralized policy and network management engine for the fabric, it is completely removed from the data path, including the forwarding topology. Therefore, the fabric can still forward traffic even when communication with the APIC is lost.
The APIC is responsible for fabric activation, switch firmware management, network policy configuration, and instantiation. While the APIC acts as the centralized policy and network management engine for the fabric, it is completely removed from the data path, including the forwarding topology. Therefore, the fabric can still forward traffic even when communication with the APIC is lost.
More information
More information
................
................
Various resources exist to start learning ACI, here is a list of interesting articles from the community.
Various resources exist to start learning ACI, here is a list of interesting articles from the community.
@ -39,6 +45,8 @@ Various resources exist to start learning ACI, here is a list of interesting art
- `Cisco DevNet Learning Labs about ACI <https://learninglabs.cisco.com/labs/tags/ACI>`_
- `Cisco DevNet Learning Labs about ACI <https://learninglabs.cisco.com/labs/tags/ACI>`_
.._aci_guide_modules:
Using the ACI modules
Using the ACI modules
---------------------
---------------------
The Ansible ACI modules provide a user-friendly interface to managing your ACI environment using Ansible playbooks.
The Ansible ACI modules provide a user-friendly interface to managing your ACI environment using Ansible playbooks.
@ -57,34 +65,99 @@ For instance ensuring that a specific tenant exists, is done using the following
description: Customer XYZ
description: Customer XYZ
state: present
state: present
A complete list of existing ACI modules is available for `the latest stable release <http://docs.ansible.com/ansible/latest/list_of_network_modules.html#aci>`_ as well as `the current development version <http://docs.ansible.com/ansible/devel/module_docs/list_of_network_modules.html#aci>`_.
A complete list of existing ACI modules is available for `the latest stable release <http://docs.ansible.com/ansible/latest/modules/list_of_network_modules.html#aci>`_ as well as `the current development version <http://docs.ansible.com/ansible/devel/modules/list_of_network_modules.html#aci>`_.
Standard module parameters
Common parameters
..........................
.................
Every Ansible ACI module accepts the following parameters that influence the module's communication with the APIC REST API:
Every Ansible ACI module accepts the following parameters that influence the module's communication with the APIC REST API:
- ``host`` -- Hostname or IP address of the APIC
host
- ``port`` -- Port to use for communication (defaults to ``443`` for HTTPS, and ``80`` for HTTP)
Hostname or IP address of the APIC.
- ``username`` -- User name used to log on to the APIC (defaults to ``admin``)
- ``password`` -- Password for ``username`` to log on to the APIC (using password-based authentication)
port
- ``private_key`` -- Private key for ``username`` to log on to APIC (using signature-based authentication)
Port to use for communication. (Defaults to ``443`` for HTTPS, and ``80`` for HTTP)
- ``certificate_name`` -- Name of the certificate in the ACI Web GUI (defaults to ``private_key`` file base name)
- ``timeout`` -- Timeout value for socket-level communication
username
- ``use_proxy`` -- Use system proxy settings (defaults to ``yes``)
User name used to log on to the APIC. (Defaults to ``admin``)
- ``use_ssl`` -- Use HTTPS or HTTP for APIC REST communication (defaults to ``yes``)
- ``validate_certs`` -- Validate certificate when using HTTPS communication (defaults to ``yes``)
password
- ``output_level`` -- Influence the level of detail ACI modules return to the user (one of ``normal``, ``info`` or ``debug``)
Password for ``username`` to log on to the APIC, using password-based authentication.
Module return values
private_key
....................
Private key for ``username`` to log on to APIC, using signature-based authentication. *New in version 2.5*
By default the ACI modules (excluding :ref:`aci_rest <aci_rest>`) return the resulting state of the managed object in a key ``current``.
certificate_name
Name of the certificate in the ACI Web GUI. (Defaults to ``private_key`` file base name) *New in version 2.5*
timeout
Timeout value for socket-level communication.
use_proxy
Use system proxy settings. (Defaults to ``yes``)
use_ssl
Use HTTPS or HTTP for APIC REST communication. (Defaults to ``yes``)
validate_certs
Validate certificate when using HTTPS communication. (Defaults to ``yes``)
output_level
Influence the level of detail ACI modules return to the user. (One of ``normal``, ``info`` or ``debug``) *New in version 2.5*
Proxy support
.............
By default, if an environment variable ``<protocol>_proxy`` is set on the target host, requests will be sent through that proxy. This behaviour can be overridden by setting a variable for this task (see :ref:`playbooks_environment`), or by using the ``use_proxy`` module parameter.
HTTP redirects can redirect from HTTP to HTTPS so you should be sure that your proxy environment for both protocols is correct.
If you don't need proxy support, but the system may have it configured nevertheless, you can add this parameter setting: ``use_proxy: no`` to avoid accidental proxy usage.
..hint:: Selective proxy support using the ``no_proxy`` environment variable is also supported.
Return values
.............
..versionadded:: 2.5
The following values are always returned:
current
The resulting state of the managed object.
The following values are returned when ``output_level: info``:
By increasing the ``output_level`` to ``info``, the modules give access to the ``previous`` state of the object, but also the ``proposed`` and ``sent`` configuration payload.
previous
The original state of the managed object (before any change was made).
For troubleshooting purposes setting ``output_level: debug`` or defining environment variable ``ANSIBLE_DEBUG=1`` enables more detailed information on the actual APIC REST communication, incl. ``filter_string``, ``method``, ``response``, ``status`` and ``url``.
proposed
The proposed config payload, based on user-supplied values.
sent
The sent config payload, based on user-supplied values and the existing configuration.
The following values are returned when ``output_level: debug`` or ``ANSIBLE_DEBUG=1``:
filter_string
The filter used for specific APIC queries.
method
The HTTP method used for the sent payload. (Either ``GET`` for queries, ``DELETE`` or ``POST`` for changes)
response
The HTTP response from the APIC.
status
The HTTP status code for the request.
url
The url used for the request.
..note:: The module return values are documented in detail as part of each module's documentation.
..note:: The module return values are documented in detail as part of each module's documentation.
More information
More information
................
................
Various resources exist to start learn more about ACI programmability, we recommend the following links:
Various resources exist to start learn more about ACI programmability, we recommend the following links:
@ -93,7 +166,7 @@ Various resources exist to start learn more about ACI programmability, we recomm
- `Cisco DevNet Learning Labs about ACI and Ansible <https://learninglabs.cisco.com/labs/tags/ACI,Ansible>`_
- `Cisco DevNet Learning Labs about ACI and Ansible <https://learninglabs.cisco.com/labs/tags/ACI,Ansible>`_
.._aci_auth:
.._aci_guide_auth:
ACI authentication
ACI authentication
------------------
------------------
@ -113,12 +186,14 @@ Password-based authentication is very simple to work with, but it is not the mos
..warning:: Never store passwords in plain text.
..warning:: Never store passwords in plain text.
The "Vault" feature of Ansible allows you to keep sensitive data such as passwords or keys in encrypted files, rather than as plain text in your playbooks or roles. These vault files can then be distributed or placed in source control. See :doc:`playbooks_vault` for more information.
The "Vault" feature of Ansible allows you to keep sensitive data such as passwords or keys in encrypted files, rather than as plain text in your playbooks or roles. These vault files can then be distributed or placed in source control. See :ref:`playbooks_vault` for more information.
Signature-based authentication using certificates
Signature-based authentication using certificates
.................................................
.................................................
..versionadded:: 2.5
Using signature-based authentication is more efficient and more reliable than password-based authentication.
Using signature-based authentication is more efficient and more reliable than password-based authentication.
Generate certificate and private key
Generate certificate and private key
@ -171,14 +246,14 @@ You need the following parameters with your ACI module(s) for it to work:
private_key: pki/admin.key
private_key: pki/admin.key
certificate_name: admin # This could be left out !
certificate_name: admin # This could be left out !
.. note:: If you use a certificate name in ACI that matches the private key's basename, you can leave out the ``certificate_name`` parameter like the example above.
..hint:: If you use a certificate name in ACI that matches the private key's basename, you can leave out the ``certificate_name`` parameter like the example above.
More information
More information
,,,,,,,,,,,,,,,,
,,,,,,,,,,,,,,,,
More information about Signature-based Authentication is available from `Cisco APIC Signature-Based Transactions <https://www.cisco.com/c/en/us/td/docs/switches/datacenter/aci/apic/sw/kb/b_KB_Signature_Based_Transactions.html>`_.
Detailed information about Signature-based Authentication is available from `Cisco APIC Signature-Based Transactions <https://www.cisco.com/c/en/us/td/docs/switches/datacenter/aci/apic/sw/kb/b_KB_Signature_Based_Transactions.html>`_.
.._aci_rest:
.._aci_guide_rest:
Using ACI REST with Ansible
Using ACI REST with Ansible
---------------------------
---------------------------
@ -186,15 +261,21 @@ While already a lot of ACI modules exists in the Ansible distribution, and the m
The :ref:`aci_rest <aci_rest>` module provides you with direct access to the APIC REST API and enables you to perform any task not already covered by the existing modules. This may seem like a complex undertaking, but you can generate the needed REST payload for any action performed in the ACI web interface effortlessly.
The :ref:`aci_rest <aci_rest>` module provides you with direct access to the APIC REST API and enables you to perform any task not already covered by the existing modules. This may seem like a complex undertaking, but you can generate the needed REST payload for any action performed in the ACI web interface effortlessly.
Using the aci-rest module
Built-in idempotency
....................
Because the APIC REST API is intrinsically idempotent and can report whether a change was made, the :ref:`aci_rest <aci_rest>` module automatically inherits both capabilities and is a first-class solution for automating your ACI infrastructure. As a result, users that require more powerful low-level access to their ACI infrastructure don't have to give up on idempotency and don't have to guess whether a change was performed when using the :ref:`aci_rest <aci_rest>` module.
Using the aci_rest module
.........................
.........................
The :ref:`aci_rest <aci_rest>` module accepts the native XML and JSON payloads, but additionally accepts inline YAML payload (structured like JSON). The XML payload requires you to use a path ending with ``.xml`` whereas JSON or YAML require path to end with ``.json``.
The :ref:`aci_rest <aci_rest>` module accepts the native XML and JSON payloads, but additionally accepts inline YAML payload (structured like JSON). The XML payload requires you to use a path ending with ``.xml`` whereas JSON or YAML require the path to end with ``.json``.
When you're making modifications, you can use the POST or DELETE methods, whereas doing just queries require the GET method.
When you're making modifications, you can use the POST or DELETE methods, whereas doing just queries require the GET method.
For instance, if you would like to ensure a specific tenant exists on ACI, these below four examples are identical:
For instance, if you would like to ensure a specific tenant exists on ACI, these below four examples are functionally identical:
**XML** (Native ACI)
**XML** (Native ACI REST)
..code-block:: yaml
..code-block:: yaml
@ -207,7 +288,7 @@ For instance, if you would like to ensure a specific tenant exists on ACI, these
@ -227,7 +308,7 @@ For instance, if you would like to ensure a specific tenant exists on ACI, these
}
}
}
}
**YAML** (Ansible-style)
**YAML** (Ansible-style REST)
..code-block:: yaml
..code-block:: yaml
@ -255,21 +336,28 @@ For instance, if you would like to ensure a specific tenant exists on ACI, these
description: Customer XYZ
description: Customer XYZ
state: present
state: present
..hint:: The XML format is more practical when there is a need to template the REST payload (inline), but the YAML format is more convenient for maintaing your infrastructure-as-code and feels more naturely integrated with Ansible playbooks. The dedicated modules offer a more simple, abstracted, but also a more limited experience. Use what feels best for your use-case.
More information
More information
................
................
Plenty of resources exist to learn about ACI's APIC REST interface, we recommend the links below:
Plenty of resources exist to learn about ACI's APIC REST interface, we recommend the links below:
- `APIC REST API Configuration Guide <https://www.cisco.com/c/en/us/td/docs/switches/datacenter/aci/apic/sw/2-x/rest_cfg/2_1_x/b_Cisco_APIC_REST_API_Configuration_Guide.html>`_
- `APIC REST API Configuration Guide <https://www.cisco.com/c/en/us/td/docs/switches/datacenter/aci/apic/sw/2-x/rest_cfg/2_1_x/b_Cisco_APIC_REST_API_Configuration_Guide.html>`_ -- Detailed guide on how the APIC REST API is designed and used, incl. many examples
- `APIC Management Information Model reference <https://developer.cisco.com/docs/apic-mim-ref/>`_ -- Complete reference of the APIC object model
- `Cisco DevNet Learning Labs about ACI and REST <https://learninglabs.cisco.com/labs/tags/ACI,REST>`_
- `Cisco DevNet Learning Labs about ACI and REST <https://learninglabs.cisco.com/labs/tags/ACI,REST>`_
.._aci_ops:
.._aci_guide_ops:
Operational examples
Operational examples
--------------------
--------------------
Here is a small overview of useful operational tasks to reuse in your playbooks.
Here is a small overview of useful operational tasks to reuse in your playbooks.
Feel free to contribute more snippets that are useful to others.
Feel free to contribute more useful snippets.
Waiting for all controllers to be ready
Waiting for all controllers to be ready
.......................................
.......................................
@ -280,16 +368,15 @@ You can use the below task after you started to build your APICs and configured
until: topsystem|success and topsystem.totalCount|int >= groups['apic']|count >= 3
until: aci_ready|success and aci_ready.totalCount|int >= groups['apic']|count
retries: 20
retries: 20
delay: 30
delay: 30
Waiting for cluster to be fully-fit
Waiting for cluster to be fully-fit
...................................
...................................
The below example waits until the cluster is fully-fit. In this example you know the number of APICs in the cluster and you verify each APIC reports a 'fully-fit' status.
The below example waits until the cluster is fully-fit. In this example you know the number of APICs in the cluster and you verify each APIC reports a 'fully-fit' status.
@ -299,90 +386,91 @@ The below example waits until the cluster is fully-fit. In this example you know
# all(apic.infraWiNode.attributes.health == 'fully-fit' for apic in aci_fit.imdata)
# all(apic.infraWiNode.attributes.health == 'fully-fit' for apic in infrawinode.imdata)
retries: 30
retries: 30
delay: 30
delay: 30
.._aci_errors:
.._aci_guide_errors:
APIC error messages
APIC error messages
-------------------
-------------------
The following error messages may occur and this section can help you understand what exactly is going on.
The following error messages may occur and this section can help you understand what exactly is going on and how to fix/avoid them.
- **APIC Error 122: unknown managed object class 'polUni'**
APIC Error 122: unknown managed object class 'polUni'
In case you receive this error while you are certain your :ref:`aci_rest <aci_rest>` payload and object classes are seemingly correct, the issue might be that your payload is not in fact correct JSON (e.g. the sent payload is using single quotes, rather than double quotes), and as a result the APIC is not correctly parsing your object classes from the payload. One way to avoid this is by using a YAML or an XML formatted payload, which are easier to construct correctly and modify later.
In case you receive this error while you are certain your :ref:`aci_rest <aci_rest>` payload and object classes are seemingly correct, the issue might be that your payload is not in fact correct JSON (e.g. the sent payload is using single quotes, rather than double quotes), and as a result the APIC is not correctly parsing your object classes from the payload. One way to avoid this is by using a YAML or an XML formatted payload.
APIC Error 400: invalid data at line '1'. Attributes are missing, tag 'attributes' must be specified first, before any other tag
Although the JSON specification allows unordered elements, the APIC REST API requires that the JSON ``attributes`` element precede the ``children`` array or other elements. So you need to ensure that your payload conforms to this requirement. Sorting your dictionary keys will do the trick just fine. If you don't have any attributes, it may be necessary to add: ``attributes: {}`` as the APIC does expect the entry to precede any ``children``.
- **APIC Error 400: invalid data at line '1'. Attributes are missing, tag 'attributes' must be specified first, before any other tag**
While JSON does not care about the order of dictionary keys, the APIC is very strict in accepting only ``attributes`` before ``children``. So you need to ensure that your payload conforms to this requirement. Sorting your dictionary keys will do the trick just fine.
APIC Error 801: property descr of uni/tn-TENANT/ap-AP failed validation for value 'A "legacy" network'
Some values in the APIC have strict format-rules to comply to, and the internal APIC validation check for the provided value failed. In the above case, the ``description`` parameter (internally known as ``descr``) only accepts values conforming to `Regex: [a-zA-Z0-9\\!#$%()*,-./:;@ _{|}~?&+]+ <https://pubhub-prod.s3.amazonaws.com/media/apic-mim-ref/docs/MO-fvAp.html#descr>`_, in general it must not include quotes or square brackets.
- **APIC Error 801: property descr of uni/tn-TENANT/ap-AP failed validation for value 'A "legacy" network'**
.._aci_guide_known_issues:
Some values in the APIC have strict format-rules to comply to, and the internal APIC validation check for the provided value failed. In the above case, the ``description`` parameter (internally known as ``descr``) only accepts values conforming to `Regex: [a-zA-Z0-9\\!#$%()*,-./:;@ _{|}~?&+]+ <https://pubhub-prod.s3.amazonaws.com/media/apic-mim-ref/docs/MO-fvAp.html#descr>`_ so it must not include quotes.
.._aci_issues:
Known issues
Known issues
------------
------------
The :ref:`aci_rest <aci_rest>` module is a wrapper around the APIC REST API. As a result any issues related to the APIC will be reflected in the use of the :ref:`aci_rest <aci_rest>` module.
The :ref:`aci_rest <aci_rest>` module is a wrapper around the APIC REST API. As a result any issues related to the APIC will be reflected in the use of this module.
All below issues either have been reported to the vendor, or can simply be avoided.
- **Too many consecutive API calls may result in connection throttling**
All below issues either have been reported to the vendor, and most can simply be avoided.
Too many consecutive API calls may result in connection throttling
Starting with ACI v3.1 the APIC will actively throttle password-based authenticated connection rates over a specific treshold. This is as part of an anti-DDOS measure but can act up when using Ansible with ACI using password-based authentication. Currently, one solution is to increase this treshold within the nginx configuration, but using signature-based authentication is recommended.
Starting with ACI v3.1 the APIC will actively throttle password-based authenticated connection rates over a specific treshold. This is as part of an anti-DDOS measure but can act up when using Ansible with ACI using password-based authentication. Currently, one solution is to increase this treshold within the nginx configuration, but using signature-based authentication is recommended.
**NOTE:** It is advisable to use signature-based authentication with ACI as it not only prevents connection-throttling, but also improves general performance when using the ACI modules.
**NOTE:** It is advisable to use signature-based authentication with ACI as it not only prevents connection-throttling, but also improves general performance when using the ACI modules.
- **Specific requests may not reflect changes correctly**
Specific requests may not reflect changes correctly (`#35401 <https://github.com/ansible/ansible/issues/35041>`_)
There is a known issue where specific requests to the APIC do not properly reflect changed in the resulting output, even when we request those changes explicitly from the APIC. In one instance using the path ``api/node/mo/uni/infra.xml`` fails, where ``api/node/mo/uni/infra/.xml`` does work correctly.
There is a known issue where specific requests to the APIC do not properly reflect changed in the resulting output, even when we request those changes explicitly from the APIC. In one instance using the path ``api/node/mo/uni/infra.xml`` fails, where ``api/node/mo/uni/infra/.xml`` does work correctly.
More information from: `#35401 aci_rest: change not detected <https://github.com/ansible/ansible/issues/35041>`_
**NOTE:** A workaround is to register the task return values (e.g. ``register: this``) and influence when the task should report a change by adding: ``changed_when: this.imdata != []``.
**NOTE:** Fortunately the behaviour is consistent, so if you have a working example you can trust that it will keep on working.
- **Specific requests are known to not be idempotent**
Specific requests are known to not be idempotent (`#35050 <https://github.com/ansible/ansible/issues/35050>`_)
The behaviour of the APIC is inconsistent to the use of ``status="created"`` and ``status="deleted"``. The result is that when you use ``status="created"`` in your payload the resulting tasks are not idempotent and creation will fail when the object was already created. However this is not the case with ``status="deleted"`` where such call to an non-existing object does not cause any failure whatsoever.
The behaviour of the APIC is inconsistent to the use of ``status="created"`` and ``status="deleted"``. The result is that when you use ``status="created"`` in your payload the resulting tasks are not idempotent and creation will fail when the object was already created. However this is not the case with ``status="deleted"`` where such call to an non-existing object does not cause any failure whatsoever.
More information from: `#35050 aci_rest: Using status="created" behaves differently than status="deleted" <https://github.com/ansible/ansible/issues/35050>`_
**NOTE:** A workaround is to avoid using ``status="created"`` and instead use ``status="modified"`` when idempotency is essential to your workflow..
**NOTE:** A workaround is to avoid using ``status="created"`` and instead use ``status="modified"`` when idempotency is essential to your workflow..
- **Setting user password is not idempotent**
Setting user password is not idempotent (`#35544 <https://github.com/ansible/ansible/issues/35544>`_)
Due to an inconsistency in the APIC REST API, a task that sets the password of a locally-authenticated user is not idempotent. The APIC will complain with message ``Password history check: user dag should not use previous 5 passwords``.
Due to an inconsistency in the APIC REST API, a task that sets the password of a locally-authenticated user is not idempotent. The APIC will complain with message ``Password history check: user dag should not use previous 5 passwords``.
More information from: `#35544 aci_aaa_user: Setting user password is not idempotent <https://github.com/ansible/ansible/issues/35544>`_
**NOTE:** There is no workaround for this issue.
**NOTE:** There is no workaround for this issue.
.._aci_community:
.._aci_guide_community:
ACI Ansible community
ACI Ansible community
---------------------
---------------------
If you have specific issues with the ACI modules, or a feature request, or you like to contribute to the ACI project by proposing changes or documentation updates, look at the Ansible Community wiki ACI page at: https://github.com/ansible/community/wiki/Network:-ACI
If you have specific issues with the ACI modules, or a feature request, or you like to contribute to the ACI project by proposing changes or documentation updates, look at the Ansible Community wiki ACI page at: https://github.com/ansible/community/wiki/Network:-ACI
You will find our roadmap, an overview of open ACI issues and pull-requests and more information about who we are. If you have an interest in using ACI with Ansible, feel free to join ! We occasionally meet online to track progress and prepare for new Ansible releases.
You will find our roadmap, an overview of open ACI issues and pull-requests and more information about who we are. If you have an interest in using ACI with Ansible, feel free to join ! We occasionally meet online to track progress and prepare for new Ansible releases.
..seealso::
:ref:`network_guide`
A detailed guide on how to use Ansible for automating network infrastructure.
:ref:`List of ACI modules <aci_network_modules>`
A complete list of supported ACI modules.
`ACI community <https://github.com/ansible/community/wiki/Network:-ACI>`_
The Ansible ACI community wiki page, includes roadmap, ideas and development documentation.
`Network Working Group <https://github.com/ansible/community/tree/master/group-network>`_
The Ansible Network community page, includes contact information and meeting information.
@ -220,30 +220,19 @@ but it is easily handled with a minimum of syntax in an Ansible Playbook::
As a reminder, the various YAML files contain just keys and values::
As a reminder, the various YAML files contain just keys and values::
---
---
# for vars/CentOS.yml
# for vars/RedHat.yml
apache: httpd
apache: httpd
somethingelse: 42
somethingelse: 42
How does this work? If the operating system was 'CentOS', the first file Ansible would try to import
How does this work? For Red Hat operating systems ('CentOS', for example), the first file Ansible tries to import
would be 'vars/CentOS.yml', followed by '/vars/os_defaults.yml' if that file
is 'vars/RedHat.yml'. If that file does not exist, Ansible attempts to load 'vars/os_defaults.yml'. If no files in
did not exist. If no files in the list were found, an error would be raised.
the list were found, an error is raised.
On Debian, it would instead first look towards 'vars/Debian.yml' instead of 'vars/CentOS.yml', before
falling back on 'vars/os_defaults.yml'. Pretty simple.
To use this conditional import feature, you'll need facter or ohai installed prior to running the playbook, but
On Debian, Ansible first looks for 'vars/Debian.yml' instead of 'vars/RedHat.yml', before
you can of course push this out with Ansible if you like::
falling back on 'vars/os_defaults.yml'.
# for facter
Ansible's approach to configuration -- separating variables from tasks, keeping your playbooks
ansible -m yum -a "pkg=facter state=present"
from turning into arbitrary code with nested conditionals - results in more streamlined and auditable configuration rules because there are fewer decision points to track.
ansible -m yum -a "pkg=ruby-json state=present"
# for ohai
ansible -m yum -a "pkg=ohai state=present"
Ansible's approach to configuration -- separating variables from tasks, keeps your playbooks
from turning into arbitrary code with ugly nested ifs, conditionals, and so on - and results
in more streamlined & auditable configuration rules -- especially because there are a
@ -239,7 +239,7 @@ Here's an example set of two host prefixes (with some "control" values)::
First, let's make sure that we only work with correct host/prefix values, not
First, let's make sure that we only work with correct host/prefix values, not
just subnets or single IP addresses::
just subnets or single IP addresses::
# {{ test_list | ipaddr('host/prefix') }}
# {{ host_prefix | ipaddr('host/prefix') }}
['2001:db8:deaf:be11::ef3/64', '192.0.2.48/24']
['2001:db8:deaf:be11::ef3/64', '192.0.2.48/24']
In Debian-based systems, network configuration stored in ``/etc/network/interfaces`` file uses combination of IP address, network address, netmask and broadcast address to configure IPv4 network interface. We can get these values from a single 'host/prefix' combination:
In Debian-based systems, network configuration stored in ``/etc/network/interfaces`` file uses combination of IP address, network address, netmask and broadcast address to configure IPv4 network interface. We can get these values from a single 'host/prefix' combination:
# sadly we cannot blindly iterate through the child dicts,
# sadly we cannot blindly iterate through the child dicts,
@ -265,19 +277,6 @@ Common return values are documented :ref:`here <common_return_values>`, the foll
{% endif %}
{% endif %}
{% if notes -%}
Notes
-----
.. note::
{% for note in notes %}
- @{ note | convert_symbols_to_format }@
{% endfor %}
{% endif %}
{% if author is defined -%}
{% if author is defined -%}
@ -285,7 +284,7 @@ Author
~~~~~~
~~~~~~
{% for author_name in author %}
{% for author_name in author %}
* @{ author_name }@
* @{ author_name }@
{% endfor %}
{% endfor %}
@ -319,5 +318,4 @@ please refer to this `Knowledge Base article <https://access.redhat.com/articles
{% endif %}
{% endif %}
{% endif %}
{% endif %}
If you want to help with development, please read :doc:`../../community/index`,
If you notice any issues in this documentation you can `edit this document <https://github.com/ansible/ansible/edit/devel/lib/ansible/modules/@{ source }@?description=%3C!---%20Your%20description%20here%20--%3E%0A%0A+label:%20docsite_pr>`_ to improve it.
:doc:`../../dev_guide/testing` and {% if plugin_type == 'module' %}:doc:`../../dev_guide/developing_modules`{% else %}:doc:`../../dev_guide/developing_plugins`{% endif %}.
John R Barker
7 years ago
committed by