cisco.aci.aci_rest – Direct access to the Cisco APIC REST API¶
Note
This plugin is part of the cisco.aci collection (version 1.1.1).
To install it use: ansible-galaxy collection install cisco.aci.
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¶
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 the ACI documentation.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 the ACI documentation.
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
The official documentation on the cisco.aci.aci_tenant module.
- 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: no
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: no
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: no
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: no
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: no
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: yes
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
Authors¶
Dag Wieers (@dagwieers)
Cindy Zhao (@cizhao)