Ansible Modules for Catalyst Center
The catalystenter-ansible project provides an Ansible collection for managing and automating your 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 Catalyst Center 2.3.7.6.
Other versions of this collection are compatible with earlier releases of Catalyst Center.
Compatibility matrix
Supported Versions
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.0 | ^3.1.3.0.0 |
If your Ansible collection is older please consider updating it first.
Notes:
- The "Python 'catalystcentersdk' version" column shows the minimum recommended version used when testing the Ansible collection.
- The "Catalyst Center version" column displays the
version
you should use for the Ansible collection.
Installing according to Compatibility Matrix
For example, for 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
Install Ansible. (Install guide)
sudo pip install ansible
Install Python Catalyst Center SDK.
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
First, export the environment variables where you specify your Catalyst Center credentials as ansible variables:
export CATALYST_HOST=<A.B.C.D>
export CATALYST_PORT=443 # optional, defaults to 443
export CATALYST_USERNAME=<username>
export CATALYST_PASSWORD=<password>
export CATALYST_VERSION=2.3.7.6 # optional, defaults to 2.3.7.6. See the Compatibility matrix
export CATALYST_VERIFY=False # optional, defaults to True
export CATALYST_DEBUG=False # optional, defaults to False
Create a hosts
(example) file that uses [catalystcenter_servers]
with your 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
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:
_host: <A.B.C.D>
_api_port: 443 # optional, defaults to 443
_username: <username>
_password: <password>
_version: 2.3.7.6 # optional, defaults to 2.3.7.6. See the Compatibility matrix
_verify: False # optional, defaults to True
_debug: False # optional, defaults to False
Create a hosts
(example) file that uses [catalystcenter_servers]
with your 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:
_host: "{{_host}}"
_username: "{{ _username }}"
_password: "{{ _password }}"
_verify: "{{ _verify }}"
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 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 Catalyst Center product, its REST API and the corresponding Python SDK, which this project relies on.