Skip to content

About

Official repository for Cisco's Ansible collection for ISE

Resources

Stars

55 stars

Watchers

9 watching

Forks

Repository files navigation

Ansible Collection - cisco.ise

Ansible Modules for Cisco ISE

The ise-ansible project provides an Ansible collection for managing and automating your Cisco Identity Services Engine (ISE) environment. It consists of a set of modules and roles for performing tasks related to Cisco ISE.

The 3.x releases of this collection are built for the Cisco ISE 3.5 API (ise_version: 3.5.0, the default).

These Ansible modules will work with any version of ISE that supports the underlying REST API resources you want to configure. Please see the ISE API Versioning reference for which REST Resources were first supported in which Cisco ISE Version.

Note: This collection requires ansible-core 2.16 or later.

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

Requirements

  • ansible-core >= 2.16
  • Python >= 3.12, required by the Cisco ISE SDK 2.4.x
  • Cisco ISE SDK v2.4.7 or newer
  • requests >= 2.25.1, for the personas modules and personas_deployment role.

Note: ansible-core is provided through Red Hat Ansible Automation Platform Execution Environments or can be installed via standard enterprise channels. Manual installation is not required for certified environments.

Install

Cisco ISE SDK must be installed

sudo pip install ciscoisesdk

Install the certified collection from Red Hat Ansible Automation Hub or the community version from Ansible Galaxy

ansible-galaxy collection install cisco.ise

ISE Setup

This collection assumes that the API Gateway, the ERS APIs and OpenAPIs are enabled.

Using the collection on previous Cisco ISE versions

The 3.x releases of the collection implement the Cisco ISE 3.5.0 API only. Most modules call operations that do not exist for other ise_version values.

For older Cisco ISE releases use the collection version listed in the compatibility matrix.

The recommended versions are listed below on the Compatibility matrix.

Compatibility matrix

The following table shows the supported versions.

Cisco ISE version Ansible "cisco.ise" version Python "ciscoisesdk" version
3.1.0 2.0.0 1.2.0
3.1_Patch_1 2.5.16 2.0.10
3.2_beta 2.8.0 2.1.1
3.3_patch_1 2.10.0 2.2.3
3.5.0 3.3.0 2.4.7

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

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

Installing according to Compatibility Matrix

For example, for Cisco ISE 3.1.0, it is recommended to use Ansible "cisco.ise" v2.0.0 and Python "ciscoisesdk" v2.4.0.

To get the Python Cisco ISE SDK v2.4.0 in a fresh development environment:

sudo pip install ciscoisesdk==2.4.0

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

ansible-galaxy collection install cisco.ise:2.0.0

Using this collection

There are three ways to use it:

Using environment variables

First, export the environment variables where you specify your Cisco ISE credentials as ansible variables:

export ISE_HOSTNAME=<A.B.C.D>
export ISE_USERNAME=<username>
export ISE_PASSWORD=<password>
export ISE_VERIFY=False # optional, defaults to True
export ISE_VERSION=3.5.0 # optional, defaults to 3.5.0
export ISE_WAIT_ON_RATE_LIMIT=True # optional, defaults to True
export ISE_USES_API_GATEWAY=True # optional, defaults to True
export ISE_DEBUG=False # optional, defaults to False
export ISE_SINGLE_REQUEST_TIMEOUT=60 # optional, defaults to 60

Create a hosts (example) file that uses [ise_servers] with your Cisco ISE Settings:

[ise_servers]
ise_server

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

- hosts: ise_servers
  gather_facts: no
  tasks:
  - name: Get network device by id
    cisco.ise.network_device_info:
      id: "0667bc80-78a9-11eb-b987-005056aba98b"

Execute the playbook:

ansible-playbook -i hosts myplaybook.yml

Using vars_files

First, define a credentials.yml (example) file where you specify your Cisco ISE credentials as ansible variables:

---
ise_hostname: <A.B.C.D>
ise_username: <username>
ise_password: <password>
ise_verify: False # optional, defaults to True
ise_version: 3.5.0 # optional, defaults to 3.5.0
ise_wait_on_rate_limit: True # optional, defaults to True
ise_debug: False # optional, defaults to False
ise_uses_api_gateway: True # optional, defaults to True
ise_uses_csrf_token: False # optional, defaults to False
ise_single_request_timeout: 60 # optional, defaults to 60

Create a hosts (example) file that uses [ise_servers] with your Cisco ISE Settings:

[ise_servers]
ise_server

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

- hosts: ise_servers
  vars_files:
    - credentials.yml
  gather_facts: no
  tasks:
  - name: Get network device by id
    cisco.ise.network_device_info:
      ise_hostname: "{{ise_hostname}}"
      ise_username: "{{ise_username}}"
      ise_password: "{{ise_password}}"
      ise_verify: "{{ise_verify}}"
      ise_debug: "{{ise_debug}}"
      ise_uses_api_gateway: "{{ise_uses_api_gateway}}"
      ise_uses_csrf_token: "{{ise_uses_csrf_token}}"
      id: "0667bc80-78a9-11eb-b987-005056aba98b"

Execute the playbook:

ansible-playbook -i hosts myplaybook.yml

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

Note: The examples found on the playbooks directory use the group_vars variables. Remember to make the appropiate changes when running the examples.

Using group_vars directory

First, define your group_vars for credentials ise_servers (example) file where you specify your Cisco ISE credentials as ansible variables:

---
ise_hostname: <A.B.C.D>
ise_username: <username>
ise_password: <password>
ise_verify: False # optional, defaults to True
ise_version: 3.5.0 # optional, defaults to 3.5.0
ise_wait_on_rate_limit: True # optional, defaults to True
ise_debug: False # optional, defaults to False
ise_uses_api_gateway: True # optional, defaults to True
ise_uses_csrf_token: False # optional, defaults to False
ise_single_request_timeout: 60 # optional, defaults to 60

Create a hosts (example) file that uses [ise_servers] with your Cisco ISE Settings:

[ise_servers]
ise_server

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

- hosts: ise_servers
  gather_facts: no
  tasks:
  - name: Get network device by id
    cisco.ise.network_device_info:
      ise_hostname: "{{ise_hostname}}"
      ise_username: "{{ise_username}}"
      ise_password: "{{ise_password}}"
      ise_verify: "{{ise_verify}}"
      ise_debug: "{{ise_debug}}"
      ise_uses_api_gateway: "{{ise_uses_api_gateway}}"
      ise_uses_csrf_token: "{{ise_uses_csrf_token}}"
      id: "0667bc80-78a9-11eb-b987-005056aba98b"

Execute the playbook:

ansible-playbook -i hosts myplaybook.yml

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

Note: The examples found on the playbooks directory use the group_vars variables. Consider using ansible-vault to encrypt the file that has the ise_username and ise_password.

Certificate-based authentication (mTLS)

As an alternative to ise_username/ise_password, Cisco ISE 3.3+ supports certificate-based (mTLS) API authentication. Provide the path to a client certificate (and optionally a separate private key) instead of a username/password:

ise_hostname: <A.B.C.D>
ise_client_cert: /path/to/client.pem   # or ISE_CLIENT_CERT env var
ise_client_key: /path/to/client.key    # optional; omit if key is bundled in the cert
ise_verify: True

When ise_client_cert is set, ise_username and ise_password are not required. This requires ciscoisesdk >= 2.4.2 and certificate-based API access enabled on the ISE deployment.

Update

Getting the latest/nightly collection build

Clone the ansible-ise repository.

git clone https://github.com/CiscoISE/ansible-ise.git

Go to the ansible-ise directory

cd ansible-ise

Pull the latest main from the repo

git pull origin main

Build and install a collection from source

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

See Also:

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 these environment variables:

export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES
export no_proxy=*

Release notes

See the changelog for the changes in each release.

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 ISE 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 ISE product, its REST API and the corresponding Python SDK, which this project relies on.

License

GNU General Public License v3.0 or later. See LICENSE for the full text.

About

Official repository for Cisco's Ansible collection for ISE

Resources

Stars

55 stars

Watchers

9 watching

Forks

Releases

Packages

Used by

Contributors

Languages