Chapter 14: Controller-Based Ansible Automation

The cisco.dnac collection is Cisco's official Ansible interface for Catalyst Center (formerly DNA Center). Every module communicates exclusively over HTTPS REST using the Cisco Catalyst Center Python SDK as its transport — no SSH or NETCONF is involved. This means tasks always target localhost and the control node must have the SDK installed.

ansible-galaxy collection install cisco.dnac
pip install dnacentersdk

A minimum Catalyst Center version of 2.3.5.3 is required for workflow manager modules; enhanced features require 2.3.7.9+.

Workflow Manager Modules

The collection's *_workflow_manager modules are idempotent lifecycle managers. They compare desired state against live configuration and make only necessary changes. Running the same playbook twice with state: merged is always safe.

Site Hierarchy: Area → Building → Floor

Before any device can be provisioned, the three-level site hierarchy must exist. The parent_name field uses a slash-delimited path from the Global root, which is also referenced by provision_workflow_manager.

- name: Build Area, Building, and Floor
  cisco.dnac.site_workflow_manager:
    dnac_host: "{{ vault_dnac_host }}"
    dnac_username: "{{ vault_dnac_username }}"
    dnac_password: "{{ vault_dnac_password }}"
    dnac_verify: false
    state: merged
    config:
      - site:
          area:
            name: "US-West"
            parent_name: "Global"
          building:
            name: "HQ-Building1"
            parent_name: "Global/US-West"
          floor:
            name: "Floor-1"
            parent_name: "Global/US-West/HQ-Building1"
            rf_model: "Cubes And Walled Offices"

PnP Provisioning Modes

Compliance Checking

The network_compliance_workflow_manager detects configuration drift across four compliance categories:

• INTENT — compares running config against Catalyst Center intent
• RUNNING_CONFIG — checks for unauthorized manual changes
• IMAGE — validates software version compliance
• PSIRT — flags known security vulnerabilities

Meraki is cloud-managed: Ansible never connects to individual devices. Every task is an HTTPS call to api.meraki.com from localhost. Authentication uses a Dashboard API key generated from Organization > Settings > Dashboard API access.

ansible-galaxy collection install cisco.meraki
# For full Dashboard API v1.33.0+ surface:
ansible-galaxy collection install meraki.dashboard

State Model

Core Modules

Performance: Use Numeric IDs

Always prefer numeric org_id and net_id over name-based parameters. Name-based resolution requires additional API round-trips, which compounds at scale.

Query-Then-Act Pattern with selectattr()

Meraki API responses return lists, not keyed dictionaries. Use Jinja2's selectattr() filter to extract items by attribute:

- name: Extract target network ID by name
  set_fact:
    target_net_id: >-
      {{ network_list.data
         | selectattr('name', 'equalto', 'Branch-Office-NYC')
         | map(attribute='id')
         | list
         | first }}

SSID Configuration

SSIDs are numbered 0–14 per Meraki MR network. Set auth_mode to psk for WPA-PSK or open for open networks; control isolation with ip_assignment_mode ("Bridge mode" or "NAT mode").

Cisco SD-WAN is managed through the vManage REST API. Because purpose-built modules may not cover every endpoint, the ansible.builtin.uri module is the primary tool — and mastering it teaches the underlying REST pattern that all controller automation relies on.

vManage API Categories

Session-Cookie Authentication (Two-Step)

vManage uses session-cookie authentication. Step 1 POSTs credentials to /j_security_check to obtain a session cookie. Step 2 includes that cookie in the Cookie header of all subsequent requests.

- name: Authenticate to vManage
  uri:
    url: "https://{{ vault_vmanage_host }}/j_security_check"
    method: POST
    body_format: form-urlencoded
    body:
      j_username: "{{ vault_vmanage_user }}"
      j_password: "{{ vault_vmanage_password }}"
    validate_certs: false
    status_code: 200
  register: auth_result

- name: Store session cookie
  set_fact:
    vmanage_session: "{{ auth_result.cookies_string }}"

CSRF Token for State-Changing Calls

All POST/PUT operations require a CSRF token retrieved from GET /dataservice/client/token. Include it as an X-XSRF-TOKEN request header.

Building Idempotency Manually

The uri module has no built-in idempotency. Use a check-before-act pattern: query existing resources, then use a when condition to act only if the resource is absent.

- name: Create VPN template only if absent
  uri:
    url: "https://{{ vault_vmanage_host }}/dataservice/template/feature"
    method: POST
    headers:
      Cookie: "{{ vmanage_session }}"
      X-XSRF-TOKEN: "{{ xsrf_token }}"
      Content-Type: "application/json"
    body_format: json
    body: "{{ lookup('file', 'templates/vpn_template.json') }}"
    validate_certs: false
  when: >-
    existing_templates.json.data
    | selectattr('templateName', 'equalto', 'VPN-0-Internet')
    | list | length == 0

Orchestrating three controllers from a single Ansible project requires deliberate architectural discipline. The core principle: treat each controller as a domain with clear boundaries enforced by Ansible's role and inventory structures.

Inventory: Group by Controller Domain

[catalyst_center]
dnac-primary.corp.com

[meraki_cloud]
localhost

[sdwan_vmanage]
vmanage.corp.com

[catalyst_center:vars]
ansible_connection=local

[meraki_cloud:vars]
ansible_connection=local

[sdwan_vmanage:vars]
ansible_connection=local

All three groups use ansible_connection=local — all communication is HTTPS REST from the control node, not SSH to remote hosts. Meraki uses localhost because there is no on-premises Meraki server.

ansible-vault Credential Management

Store all secrets in an AES-256 encrypted vault file. Never commit plain-text API keys or passwords to version control.

Master Orchestration with import_playbook

# site.yml — Master Multi-Controller Orchestration
- import_playbook: playbooks/catalyst_center/provision_sites.yml
- import_playbook: playbooks/meraki/deploy_networks.yml
- import_playbook: playbooks/sdwan/deploy_templates.yml
- import_playbook: playbooks/sdwan/health_check.yml

Use import_playbook (static, parse-time) for known sequences. Use include_tasks (dynamic, runtime) within roles when task selection depends on variables or conditions.

Error Handling with block/rescue/always

Multi-controller workflows can fail partway through. Use block/rescue/always — analogous to try/catch/finally — for graceful rollback and notifications regardless of outcome.

- block:
    - name: Provision device to Catalyst Center
      cisco.dnac.provision_workflow_manager:
        state: merged
        config:
          - management_ip_address: "{{ device_ip }}"
            site_name_hierarchy: "{{ site_path }}"
  rescue:
    - name: Remove device from inventory (rollback)
      cisco.dnac.inventory_workflow_manager:
        state: deleted
        config:
          - ip_address_list: ["{{ device_ip }}"]
  always:
    - name: Send Webex notification regardless of outcome
      uri:
        url: "{{ vault_webex_webhook }}"
        method: POST
        body_format: json
        body: {text: "Provisioning task completed for {{ device_ip }}"}

Execution Environments for AAP

For Red Hat Ansible Automation Platform at scale, build a custom Execution Environment container bundling all collections and SDK dependencies. AAP Workflow Templates then chain Catalyst Center → Meraki → SD-WAN jobs with conditional branching, RBAC, and event-driven automation.