Ansible Collection - cisco.catalystwan

Initial repository for Ansible Collection using catalystwan library.

*NOTE: this repository is still in pre-release dev version

Table of Contents

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

---

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. Current installation available via local Ansible Galaxy collection.

Once finished, repository will be migrated to Cisco Open, and modules will be available via Ansible Galaxy.

---

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.3"

Installing this collection

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

---
collections:
- name: git@github.com: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.

---

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.