Try SpotterDirect access to the Cisco APIC REST API
| "added in version" 2.4 of ansible.builtin"
Authors: Dag Wieers (@dagwieers)
preview | supported by certified
pipInstall with pip install ansible==2.9.0
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.
- 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
src:
aliases:
- config_file
description:
- 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 C(content) parameter together with the
C(template) lookup plugin, or use M(template).
type: path
host:
aliases:
- hostname
description:
- IP Address or hostname of APIC resolvable by Ansible control host.
required: true
type: str
path:
aliases:
- uri
description:
- URI being used to execute API calls.
- Must end in C(.xml) or C(.json).
required: true
type: str
port:
description:
- Port number to be used for REST connection.
- The default value depends on parameter C(use_ssl).
type: int
method:
aliases:
- action
choices:
- delete
- get
- post
default: get
description:
- The HTTP method of the request.
- Using C(delete) is typically used for deleting objects.
- Using C(get) is typically used for querying objects.
- Using C(post) is typically used for modifying objects.
type: str
content:
description:
- When used instead of C(src), sets the payload of the API request directly.
- This may be convenient to template simple requests.
- For anything complex use the C(template) lookup plugin (see examples) or the M(template)
module with parameter C(src).
type: raw
timeout:
default: 30
description:
- The socket level timeout in seconds.
type: int
use_ssl:
default: true
description:
- If C(no), an HTTP connection will be used instead of the default HTTPS connection.
type: bool
password:
description:
- The password to use for authentication.
- This option is mutual exclusive with C(private_key). If C(private_key) is provided
too, it will be used instead.
required: true
type: str
username:
aliases:
- user
default: admin
description:
- The username to use for authentication.
type: str
use_proxy:
default: true
description:
- If C(no), it will not use a proxy, even if one is defined in an environment variable
on the target hosts.
type: bool
private_key:
aliases:
- cert_key
description:
- Either a PEM-formatted private key file or the private key content used for signature-based
authentication.
- This value also influences the default C(certificate_name) that is used.
- This option is mutual exclusive with C(password). If C(password) is provided too,
it will be ignored.
required: true
type: str
output_level:
choices:
- debug
- info
- normal
default: normal
description:
- Influence the output of this ACI module.
- C(normal) means the standard output, incl. C(current) dict
- C(info) adds informational output, incl. C(previous), C(proposed) and C(sent) dicts
- C(debug) adds debugging output, incl. C(filter_string), C(method), C(response),
C(status) and C(url) information
type: str
validate_certs:
default: true
description:
- If C(no), SSL certificates will not be validated.
- This should only set to C(no) when used on personally controlled sites using self-signed
certificates.
type: bool
certificate_name:
aliases:
- cert_name
description:
- The X.509 certificate name attached to the APIC AAA user used for signature-based
authentication.
- If a C(private_key) filename was provided, this defaults to the C(private_key) basename,
without extension.
- If PEM-formatted content was provided for C(private_key), this defaults to the C(username)
value.
type: str
error_code:
description: The REST ACI return code, useful for troubleshooting on failure
returned: always
sample: 122
type: int
error_text:
description: The REST ACI descriptive text, useful for troubleshooting on failure
returned: always
sample: unknown managed object class foo
type: str
imdata:
description: Converted output returned by the APIC REST (register this for post-processing)
returned: always
sample:
- error:
attributes:
code: '122'
text: unknown managed object class foo
type: str
payload:
description: The (templated) payload send to the APIC REST API (xml or json)
returned: always
sample: <foo bar="boo"/>
type: str
raw:
description: The raw output returned by the APIC REST API (xml or json)
returned: parse error
sample: <?xml version="1.0" encoding="UTF-8"?><imdata totalCount="1"><error code="122"
text="unknown managed object class foo"/></imdata>
type: str
response:
description: HTTP response string
returned: always
sample: 'HTTP Error 400: Bad Request'
type: str
status:
description: HTTP status code
returned: always
sample: 400
type: int
totalCount:
description: Number of items in the imdata array
returned: always
sample: '0'
type: str
url:
description: URL used for APIC REST call
returned: success
sample: https://1.2.3.4/api/mo/uni/tn-[Dag].json?rsp-subtree=modified
type: str