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

Note

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

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.