aci_rest – Direct access to the Cisco APIC REST API
aci_rest – Direct access to the Cisco APIC REST API
New in version 2.4.
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 | Choices/Defaults | Comments |
---|---|---|
certificate_name string |
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
| |
content raw |
When used instead of This may be convenient to template simple requests. For anything complex use the | |
host string / required |
IP Address or hostname of APIC resolvable by Ansible control host.
| |
method string |
|
The HTTP method of the request. Using Using Using
|
output_level string |
|
Influence the output of this ACI module.
|
password string / required |
The password to use for authentication. This option is mutual exclusive with | |
path string / required |
URI being used to execute API calls. Must end in
| |
port integer |
Port number to be used for REST connection. The default value depends on parameter | |
private_key string / required |
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
| |
src path |
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
| |
timeout integer |
Default: 30 |
The socket level timeout in seconds. |
use_proxy boolean |
|
If |
use_ssl boolean |
|
If |
username string |
Default: "admin" |
The username to use for authentication.
|
validate_certs boolean |
|
If This should only set to |
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
lxml
andxmljson
python libraries. For JSON payloads nothing special is needed.
See Also
See also
- aci_tenant – Manage tenants (fv:Tenant)
- The official documentation on the 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
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/
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
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
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
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
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
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
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
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:
Key | Returned | Description |
---|---|---|
error_code integer |
always |
The REST ACI return code, useful for troubleshooting on failure
Sample: 122 |
error_text string |
always |
The REST ACI descriptive text, useful for troubleshooting on failure
Sample: unknown managed object class foo |
imdata string |
always |
Converted output returned by the APIC REST (register this for post-processing)
Sample: [{'error': {'attributes': {'code': '122', 'text': 'unknown managed object class foo'}}}] |
payload string |
always |
The (templated) payload send to the APIC REST API (xml or json)
Sample:
|
raw string |
parse error |
The raw output returned by the APIC REST API (xml or json)
Sample:
|
response string |
always |
HTTP response string
Sample: HTTP Error 400: Bad Request |
status integer |
always |
HTTP status code
Sample: 400 |
totalCount string |
always |
Number of items in the imdata array
Sample: 0 |
url string |
success |
URL used for APIC REST call
Sample: https://1.2.3.4/api/mo/uni/tn-[Dag].json?rsp-subtree=modified |
Status
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by an Ansible Partner. [certified]
Authors
- Dag Wieers (@dagwieers)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/aci_rest_module.html