cisco.aci.aci_rest module – Direct access to the Cisco APIC REST API
Note
This module is part of the cisco.aci collection (version 2.8.0).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install cisco.aci.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: cisco.aci.aci_rest.
Synopsis
Enables the management of the Cisco ACI fabric through direct access to the Cisco APIC REST API.
Thanks to the idempotent nature of the APIC, this module is idempotent and reports changes.
Requirements
The below requirements are needed on the host that executes this module.
lxml (when using XML payload)
xmljson >= 0.1.8 (when using XML payload)
python 2.7+ (when using xmljson)
Parameters
Parameter |
Comments |
|---|---|
The X.509 certificate name attached to the APIC AAA user used for signature-based authentication. If a If PEM-formatted content was provided for If the value is not specified in the task, the value of environment variable |
|
When used instead of This may be convenient to template simple requests. For anything complex use the |
|
IP Address or hostname of APIC resolvable by Ansible control host. If the value is not specified in the task, the value of environment variable |
|
The HTTP method of the request. Using Using Using Choices:
|
|
Influence the output of this ACI module.
If the value is not specified in the task, the value of environment variable Choices:
|
|
Path to a file that will be used to dump the ACI JSON configuration objects generated by the module. If the value is not specified in the task, the value of environment variable |
|
The password to use for authentication. This option is mutual exclusive with If the value is not specified in the task, the value of environment variables |
|
URI being used to execute API calls. Must end in |
|
Port number to be used for REST connection. The default value depends on parameter If the value is not specified in the task, the value of environment variable |
|
Either a PEM-formatted private key file or the private key content used for signature-based authentication. This value also influences the default This option is mutual exclusive with If the value is not specified in the task, the value of environment variable |
|
Preserve the response for the provided path. Choices:
|
|
Name of the absolute path of the filename that includes the body of the HTTP request being sent to the ACI fabric. If you require a templated payload, use the |
|
The socket level timeout in seconds. If the value is not specified in the task, the value of environment variable The default value is 30. |
|
If If the value is not specified in the task, the value of environment variable The default value is true. Choices:
|
|
If If the value is not specified in the task, the value of environment variable The default value is true when the connection is local. Choices:
|
|
The username to use for authentication. If the value is not specified in the task, the value of environment variables The default value is admin. |
|
If This should only set to If the value is not specified in the task, the value of environment variable The default value is true. Choices:
|
Notes
Note
Certain payloads are known not to be idempotent, so be careful when constructing payloads, e.g. using
status="created"will cause idempotency issues, usestatus="modified"instead. More information in :ref:`the ACI documentation <aci_guide_known_issues>`.Certain payloads (and used paths) are known to report no changes happened when changes did happen. This is a known APIC problem and has been reported to the vendor. A workaround for this issue exists. More information in :ref:`the ACI documentation <aci_guide_known_issues>`.
XML payloads require the
lxmlandxmljsonpython libraries. For JSON payloads nothing special is needed.If you do not have any attributes, it may be necessary to add the “attributes” key with an empty dictionnary “{}” for value as the APIC does expect the entry to precede any children.
See Also
See also
- cisco.aci.aci_tenant
Manage tenants (fv:Tenant).
- Cisco APIC REST API Configuration Guide
More information about the APIC REST API.
- Cisco ACI Guide
Detailed information on how to manage your ACI infrastructure using Ansible.
- Developing Cisco ACI modules
Detailed guide on how to write your own Cisco ACI modules to contribute.
Examples
- name: Add a tenant using certificate authentication
cisco.aci.aci_rest:
host: apic
username: admin
private_key: pki/admin.key
method: post
path: /api/mo/uni.xml
src: /home/cisco/ansible/aci/configs/aci_config.xml
delegate_to: localhost
- name: Add a tenant from a templated payload file from templates/
cisco.aci.aci_rest:
host: apic
username: admin
private_key: pki/admin.key
method: post
path: /api/mo/uni.xml
content: "{{ lookup('template', 'aci/tenant.xml.j2') }}"
delegate_to: localhost
- name: Add a tenant using inline YAML
cisco.aci.aci_rest:
host: apic
username: admin
private_key: pki/admin.key
validate_certs: false
path: /api/mo/uni.json
method: post
content:
fvTenant:
attributes:
name: Sales
descr: Sales department
delegate_to: localhost
- name: Add a tenant using a JSON string
cisco.aci.aci_rest:
host: apic
username: admin
private_key: pki/admin.key
validate_certs: false
path: /api/mo/uni.json
method: post
content:
{
"fvTenant": {
"attributes": {
"name": "Sales",
"descr": "Sales department"
}
}
}
delegate_to: localhost
- name: Add a tenant using an XML string
cisco.aci.aci_rest:
host: apic
username: admin
private_key: pki/{{ aci_username }}.key
validate_certs: false
path: /api/mo/uni.xml
method: post
content: '<fvTenant name="Sales" descr="Sales departement"/>'
delegate_to: localhost
- name: Get tenants using password authentication
cisco.aci.aci_rest:
host: apic
username: admin
password: SomeSecretPassword
method: get
path: /api/node/class/fvTenant.json
delegate_to: localhost
register: query_result
- name: Configure contracts
cisco.aci.aci_rest:
host: apic
username: admin
private_key: pki/admin.key
method: post
path: /api/mo/uni.xml
src: /home/cisco/ansible/aci/configs/contract_config.xml
delegate_to: localhost
- name: Register leaves and spines
cisco.aci.aci_rest:
host: apic
username: admin
private_key: pki/admin.key
validate_certs: false
method: post
path: /api/mo/uni/controller/nodeidentpol.xml
content:
<fabricNodeIdentPol>
<fabricNodeIdentP name="{{ item.name }}" nodeId="{{ item.nodeid }}" status="{{ item.status }}" serial="{{ item.serial }}"/>
</fabricNodeIdentPol>
with_items:
- '{{ apic_leavesspines }}'
delegate_to: localhost
- name: Wait for all controllers to become ready
cisco.aci.aci_rest:
host: apic
username: admin
private_key: pki/admin.key
validate_certs: false
path: /api/node/class/topSystem.json?query-target-filter=eq(topSystem.role,"controller")
register: apics
until: "'totalCount' in apics and apics.totalCount|int >= groups['apic']|count"
retries: 120
delay: 30
delegate_to: localhost
run_once: true
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
The REST ACI return code, useful for troubleshooting on failure Returned: always Sample: |
|
The REST ACI descriptive text, useful for troubleshooting on failure Returned: always Sample: |
|
Converted output returned by the APIC REST (register this for post-processing) Returned: always Sample: |
|
The (templated) payload send to the APIC REST API (xml or json) Returned: always Sample: |
|
The raw output returned by the APIC REST API (xml or json) Returned: parse error Sample: |
|
HTTP response string Returned: always Sample: |
|
HTTP status code Returned: always Sample: |
|
Number of items in the imdata array Returned: always Sample: |
|
URL used for APIC REST call Returned: success Sample: |