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¶
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.
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:
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)
Hint
If you notice any issues in this documentation, you can edit this document to improve it.
