cisco.aci.aci_rest – Direct access to the Cisco APIC REST API
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
Parameter | Choices/Defaults | Comments |
---|---|---|
annotation string |
User-defined string for annotating an object. If the value is not specified in the task, the value of environment variable | |
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 If the value is not specified in the task, the value of environment variable
| |
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. If the value is not specified in the task, the value of environment variable
| |
method string |
|
The HTTP method of the request. Using Using Using
|
output_level string |
|
Influence the output of this ACI module.
If the value is not specified in the task, the value of environment variable |
output_path string |
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 | |
owner_key string |
User-defined string for the ownerKey attribute of an ACI object. This attribute represents a key for enabling clients to own their data for entity correlation. If the value is not specified in the task, the value of environment variable | |
owner_tag string |
User-defined string for the ownerTag attribute of an ACI object. This attribute represents a tag for enabling clients to add their own data. For example, to indicate who created this object. If the value is not specified in the task, the value of environment variable | |
password string |
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 | |
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 If the value is not specified in the task, the value of environment variable | |
private_key string |
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
| |
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. If the value is not specified in the task, the value of environment variable |
use_proxy boolean |
|
If If the value is not specified in the task, the value of environment variable |
use_ssl boolean |
|
If If the value is not specified in the task, the value of environment variable |
username string |
Default: "admin" |
The username to use for authentication. If the value is not specified in the task, the value of environment variables
|
validate_certs boolean |
|
If This should only set to If the value is not specified in the task, the value of environment variable |
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. - 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:
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 |
Authors
- Dag Wieers (@dagwieers)
- Cindy Zhao (@cizhao)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/cisco/aci/aci_rest_module.html