cisco.catalystcenter.catalystcenter inventory -- Cisco Catalyst Center dynamic inventory plugin

Note

This inventory plugin is part of the cisco.catalystcenter collection (version 2.10.2).

To install it, use: ansible-galaxy collection install cisco.catalystcenter. You need further requirements to be able to use this inventory plugin, see Requirements for details.

To use it in a playbook, specify: cisco.catalystcenter.catalystcenter.

New in cisco.catalystcenter 2.10.0

Synopsis

  • Queries Cisco Catalyst Center for network devices and builds an Ansible inventory.

  • Creates groups based on site hierarchy, device role, device family, and tags.

  • Supports pagination for large-scale deployments (500+ devices).

  • Uses the catalystcentersdk Python SDK for API communication.

Requirements

The below requirements are needed on the local controller node that executes this inventory.

  • catalystcentersdk >= 2.3.7

Parameters

Parameter

Comments

api_page_size

integer

Number of devices to retrieve per API call.

Catalyst Center has a maximum of 500 records per call.

Default: :ansible-option-default:`500`

api_version

string

Catalyst Center API version string.

Default: :ansible-option-default:`"3.1.6.0"`

Configuration:

cache

boolean

Toggle to enable/disable the caching of the inventory's source data, requires a cache plugin setup to work.

Choices:

Configuration:

cache_connection

string

Cache connection data or path, read cache plugin documentation for specifics.

Configuration:

cache_plugin

string

Cache plugin to use for the inventory's source data.

Default: :ansible-option-default:`"memory"`

Configuration:

cache_prefix

string

Prefix to use for cache plugin files/tables

Default: :ansible-option-default:`"ansible\_inventory\_"`

Configuration:

cache_timeout

integer

Cache duration in seconds

Default: :ansible-option-default:`3600`

Configuration:

compose

dictionary

Create vars from jinja2 expressions.

Default: :ansible-option-default:`{}`

debug

boolean

Enable SDK debug logging.

Choices:

Configuration:

device_filters

dictionary

Additional keyword arguments passed to the Catalyst Center get_device_list API call.

Use this to pre-filter devices by family, role, management IP, etc.

Keys offset and limit are reserved for pagination and will be stripped if provided.

Default: :ansible-option-default:`{}`

group_by_family

boolean

Create Ansible groups by device family (e.g., family_Switches_and_Hubs).

Choices:

group_by_role

boolean

Create Ansible groups by device role (e.g., role_ACCESS, role_CORE).

Choices:

group_by_site

boolean

Create Ansible groups from the Catalyst Center site hierarchy.

Choices:

group_by_tag

boolean

Create Ansible groups from Catalyst Center device tags.

Disabled by default because it requires additional API calls.

Choices:

groups

dictionary

Add hosts to group based on Jinja2 conditionals.

Default: :ansible-option-default:`{}`

host

string / required

Hostname or IP address of the Catalyst Center appliance.

Configuration:

hostname_source

string

Device attribute to use as the Ansible inventory hostname.

Choices:

include_aps

boolean

Include Unified Access Points in the inventory.

Disabled by default because APs are not typically managed via CLI.

Choices:

keyed_groups

list / elements=string

Add hosts to group based on the values of a variable.

Default: :ansible-option-default:`[]`

password

string / required

Password for Catalyst Center authentication.

Configuration:

plugin

string / required

Token that ensures this is a source file for the plugin.

Choices:

port

integer

TCP port for the Catalyst Center API.

Default: :ansible-option-default:`443`

Configuration:

set_network_os

boolean

Automatically set ansible_network_os and ansible_connection based on the device software type.

Choices:

strict

boolean

If yes make invalid entries a fatal error, otherwise skip and continue.

Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default.

Choices:

tag_prefix

string

Prefix for tag-based group names.

Default: :ansible-option-default:`"tag\_"`

use_mgmt_ip

boolean

Set ansible_host to the device management IP address.

Choices:

username

string

Username for Catalyst Center authentication.

Default: :ansible-option-default:`"admin"`

Configuration:

validate_certs

boolean

Whether to validate SSL certificates.

Choices:

Configuration:

Examples

---
# Minimal configuration (use ansible-vault for the password in production)
- plugin: cisco.catalystcenter.catalystcenter
  host: catalyst.example.com
  username: admin
  password: "{{ vault_cc_password }}"
  validate_certs: false

# With environment variables (CATALYSTCENTER_HOST, CATALYSTCENTER_USERNAME, etc.)
- plugin: cisco.catalystcenter.catalystcenter
  validate_certs: false

# Full-featured configuration
- plugin: cisco.catalystcenter.catalystcenter
  host: catalyst.example.com
  username: admin
  password: "{{ vault_cc_password }}"
  validate_certs: false
  api_version: "3.1.6.0"

  # Grouping options
  group_by_site: true
  group_by_role: true
  group_by_family: true
  group_by_tag: true
  tag_prefix: "cctag_"

  # Include access points
  include_aps: true

  # Pre-filter devices by family
  device_filters:
    family: "Switches and Hubs"

  # Constructable features
  keyed_groups:
    - key: cc_software_type
      prefix: os
      separator: "_"
    - key: cc_series
      prefix: hw
      separator: "_"
  compose:
    ansible_host: cc_management_ip
    site_role: cc_role | lower
  groups:
    reachable: cc_reachability_status == "Reachable"
    unreachable: cc_reachability_status == "Unreachable"

  # Caching (reduces API calls)
  cache: true
  cache_plugin: ansible.builtin.jsonfile
  cache_timeout: 3600
  cache_connection: /tmp/catalystcenter_inventory_cache

Authors

  • Steve Fulmer (@stevefulme1)

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.