Ansible Collection - cisco.catalystcenter

Ansible Modules for CATALYST Center

The catalystenter-ansible project provides an Ansible collection for managing and automating your Cisco CATALYST Center environment. It consists of a set of modules and roles for performing tasks related to CATALYST Center.

This collection has been tested and supports Cisco CATALYST Center 2.3.7.6.

Other versions of this collection have support for previous Cisco CATALYST Center versions. The recommended versions are listed below on the Compatibility matrix.

Compatibility matrix

The following table shows the supported versions.

Cisco CATALYST Center version	Ansible "cisco.catalystcenter" version	Python "catalystcentersdk" version
2.3.7.6	1.0.0	2.3.7.6.2
2.3.7.9	2.1.4	2.3.7.9.5
3.1.3.0	^2.2.2	^3.1.3.0.0

If your Ansible collection is older please consider updating it first.

Notes:

1. The "Python 'catalystcentersdk' version" column has the minimum recommended version used when testing the Ansible collection. This means you could use later versions of the Python "catalystcentersdk" than those listed.
2. The "Cisco CATALYST Center version" column has the value of the version you should use for the Ansible collection.

Installing according to Compatibility Matrix

For example, for Cisco CATALYST Center 2.3.7.6, it is recommended to use Ansible "cisco.catalystcenter" v2.3.7.6 and Python "catalystcentersdk" v2.3.7.6.

To get the Python CATALYST Center SDK v2.3.7.9 in a fresh development environment:

sudo pip install catalystcentersdk==2.3.7.9

To get the Ansible collection v1.0.0 in a fresh development environment:

ansible-galaxy collection install cisco.catalystcenter:1.0.0

Requirements

• Ansible >= 2.15
• Python CATALYST Center SDK v1.0.0 or newer
• Python >= 3.9, as the CATALYST Center SDK doesn't support Python version 2.x

Install

Ansible must be installed (Install guide)

sudo pip install ansible

Python CATALYST Center SDK must be installed

sudo pip install catalystcentersdk

Install the collection (Galaxy link)

ansible-galaxy collection install cisco.catalystcenter

Using this collection

There are three ways to use it:

• Using environment variables
• Using vars_files

Using environment variables

First, export the environment variables where you specify your CATALYST Center credentials as ansible variables:

export CATALYSTCENTER_HOST=<A.B.C.D>
export CATALYSTCENTER_API_PORT=443 # optional, defaults to 443
export CATALYSTCENTER_USERNAME=<username>
export CATALYSTCENTER_PASSWORD=<password>
export CATALYSTCENTER_VERSION=3.1.3.0 # optional, see the Compatibility matrix
export CATALYSTCENTER_VERIFY=False # optional, defaults to True
export CATALYSTCENTER_DEBUG=False # optional, defaults to False

Create a hosts (example) file that uses [catalystcenter_servers] with your Cisco CATALYST Center Settings:

[catalystcenter_servers]
catalystcenter_server

Then, create a playbook myplaybook.yml (example) specifying the full namespace path to the module, plugin and/or role. The module will read connection details from the environment variables above:

- hosts: catalystcenter_servers
  gather_facts: false
  tasks:
  - name: Create tag with name "MyNewTag"
    cisco.catalystcenter.tag:
      state: present
      description: My Tag
      name: MyNewTag
    register: result

Execute the playbook:

ansible-playbook -i hosts myplaybook.yml

Using vars_files

First, define a credentials.yml (example) file where you specify your CATALYST Center credentials as Ansible variables:

---
catalystcenter_host: <A.B.C.D>
catalystcenter_api_port: 443  # optional, defaults to 443
catalystcenter_username: <username>
catalystcenter_password: <password>
catalystcenter_version: 3.1.3.0  # optional, see the Compatibility matrix
catalystcenter_verify: False  # optional, defaults to True
catalystcenter_debug: False  # optional, defaults to False

Create a hosts (example) file that uses [catalystcenter_servers] with your Cisco CATALYST Center Settings:

[catalystcenter_servers]
catalystcenter_server

Then, create a playbook myplaybook.yml (example) referencing the variables in your credentials.yml file and specifying the full namespace path to the module, plugin and/or role:

- hosts: catalystcenter_servers
  vars_files:
    - credentials.yml
  gather_facts: false
  tasks:
  - name: Create tag with name "MyNewTag"
    cisco.catalystcenter.tag:
      catalystcenter_host: "{{ catalystcenter_host }}"
      catalystcenter_username: "{{ catalystcenter_username }}"
      catalystcenter_password: "{{ catalystcenter_password }}"
      catalystcenter_verify: "{{ catalystcenter_verify }}"
      catalystcenter_api_port: "{{ catalystcenter_api_port }}"
      catalystcenter_version: "{{ catalystcenter_version }}"
      catalystcenter_debug: "{{ catalystcenter_debug }}"
      state: present
      description: My Tag
      name: MyNewTag
    register: result

Execute the playbook:

ansible-playbook -i hosts myplaybook.yml

In the playbooks directory you can find more examples and use cases.

Update

Getting the latest/nightly collection build

Clone the catalystcenter-ansible repository.

git clone https://github.com/cisco-en-programmability/catalystcenter-ansible.git

Go to the catalystcenter-ansible directory

cd catalystcenter-ansible

Pull the latest master from the repo

git pull origin master

Build and install a collection from source

ansible-galaxy collection build --force
ansible-galaxy collection install cisco-catalystcenter-* --force

See Also

• Ansible Using collections for more details.

Attention macOS users

If you're using macOS you may receive this error when running your playbook:

objc[34120]: +[__NSCFConstantString initialize] may have been in progress in another thread when fork() was called.
objc[34120]: +[__NSCFConstantString initialize] may have been in progress in another thread when fork() was called. We cannot safely call it or ignore it in the fork() child process. Crashing instead. Set a breakpoint on objc_initializeAfterForkError to debug.
ERROR! A worker was found in a dead state

If that's the case try setting this environment variable:

export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES

Contributing to this collection

Ongoing development efforts and contributions to this collection are tracked as issues in this repository.

We welcome community contributions to this collection. If you find problems, need an enhancement or need a new module, please open an issue or create a PR against the Cisco CATALYST Center Ansible collection repository.

Code of Conduct

This collection follows the Ansible project's Code of Conduct. Please read and familiarize yourself with this document.

Releasing, Versioning and Deprecation

This collection follows Semantic Versioning. More details on versioning can be found in the Ansible docs.

New minor and major releases as well as deprecations will follow new releases and deprecations of the Cisco CATALYST Center product, its REST API and the corresponding Python SDK, which this project relies on.