Ansible Collection - cisco.catalystwan

Overview

Reusable Ansible modules and roles that will help to automate Cisco SD-WAN management (post bringup operations, day0, day1).

All modules are based on catalystwan.

Collection available on Ansible Galaxy: cisco.catalystwan

Table of Contents

• Roadmap
• Requirements
• Installing this collection
• Using this collection
• Contributing
• Useful links and Getting Started
• License

---

Roadmap

Support for the following workflows in vManage client and as Ansible modules:

• Detect API server readiness:

  • in vManage-client?
  • in cisco.catalystwan module

• Device onboarding (virtual and physical devices):

  • in vManage-client?
  • in cisco.catalystwan module

• Device health checks:

  • control/orchestrator connections check, and devices system health check
    • in vManage-client?
    • in cisco.catalystwan module
  • BFD and OMP checks (BFD needs at least 2 edge devices to talk to each other)
    • in vManage-client?
    • in cisco.catalystwan module

• Day 0 template attachment

  • in vManage-client?
  • in cisco.catalystwan module

• Onboarding via PNP (Smart account sync & certificates sync)

  • in vManage-client?
  • in cisco.catalystwan module

• Software upgrades

  • in vManage-client?
  • in cisco.catalystwan module

• Day 1 configuration(Edit)

  • in vManage-client?
  • in cisco.catalystwan module

---

Requirements

Currently development of the tool was set with:

• Python = 3.10.0
• Ansible = 2.16.6
• catalystwan = "^0.33.6post0"

Installing this collection

In order to use collection, add these lines to requirements.yml file in your ansible directory:

---
collections:
- name: [email protected]:cisco-open/ansible-collection-catalystwan.git
  type: git
  version: main

And run command:

ansible-galaxy collection install -r requirements.yml

Python dependencies

The python module dependencies are not installed by ansible-galaxy. They can be manually installed using pip:

pip install -r requirements.txt

Important ansible.cfg

It is important that your playbook execution will recognize this option from ansible.cfg:

[defaults]
stdout_callback = debug

as it is highly recommended when debugging your module code.

If you want to test the modules already in your playbook, use stdout_callback = yaml.

Credentials

Use manager_authentication module argument, to provide authentication credentials to your Manager:

- name: Get list of Edge devices
  cisco.catalystwan.devices_info:
    device_category: vedges
    manager_authentication:
      url: "x.x.x.x"
      username: "xxx"
      password: "xxx"
  register: edge_devices

See Providing credentials to catalystwan Ansible modules for more information.

---

Using this collection

To run the modules againts specific machines, you have to include your playbook to act on localhost:

- name: Example playbook
  hosts: localhost

And then you can use the module:

  tasks:
    - name: Get all active sessions
      cisco.catalystwan.active_sessions_info:
        manager_authentication:
          url: "x.x.x.x"
          username: "xxx"
          password: "xxx"
      register: active_sessions

Logging

All of the modules will produce 2 log files: ansible_catalystwan_module.log and ansible_catalystwan.log. Currently base dir destination of these log files will be current working directory of playbooks.

Quick usage with example playbooks from .dev_dir

All of the modules are currently developed and tested with help of .dev_dir playbooks. These playbooks offer initial config, onboarding and health checks. If you want to run example playbook, supply your variables in .dev_dir/dev_vars.yml and execute playbooks from .dev_dir/ directory.

Feature Templates

Feature Templates operations (add and delete) are supported via cisco.catalystwan.feature_templates module.

Available models are dependent on Catalystwan SDK, and they can be seen here.

For more information about adding new models see Feature Templates generation.

---

Useful links and Getting Started

Python

• Download Python
• Getting Started with Python

Ansible

• Install Ansible

• Getting Started with Ansible

• Developing Modules General

• Developing Modules Best Practices

• Ansible module architecture

Ansible Galaxy

Ansible Galaxy provides pre-packaged units of work known as roles, and it can be used to share and use content with Ansible.

• Using Ansible Galaxy

Cisco SD-WAN

• Cisco SD-WAN Overview
• Cisco SD-WAN Documentation

---

License

See LICENSE file.

Contributing

See Contributing file.

Code of Conduct

See Code of Conduct file.

Releasing, Versioning and Deprecation

This collection follows Semantic Versioning. More details on versioning can be found in Understanding collection versioning.

New minor and major releases as well as deprecations will follow new releases and deprecations of the Cisco Catalystwan SDK, a Python SDK, which this project relies on.