Cisco SDWAN aaC


            ┌───────────────────────────────┐
            │          cisco.sdwan          │
            └───────▲───────────────▲───────┘
                    │               │
             ┌──────┘               └──────┐
             │                             │
 ┌───────────┴──────────────┐    ┌─────────┴──────────┐
 │  cisco.sdwan_deployment  │    │ cisco.catalystwan  │
 └──────────────────────────┘    └────────────────────┘

ansible-collection-sdwan combine SDWAN Deployment and Ansible Wrapper using catalystwan library collections inside one tool.

Let users to fully deploy, onboard and upgrade their SD-WAN topology.

Overview
Requirements
Installing this collection
Using this collection
Troubleshooting
Containerized variant WIP
Contributing
Useful links and Getting Started
License
Code of Conduct
Releasing, Versioning and Depracation

Overview

ansible-collection-sdwan integrates the roles and modules from both repositories to create an automation workflow for Cisco SD-WAN. By leveraging these Ansible resources, ansible-collection-sdwan empowers network administrators to:

Automate Deployment: Roll out and provision Cisco SD-WAN controllers and edge devices with minimal manual intervention using SDWAN Deployment roles.
Onboarding of Controllers and Edge Devices: Simplify the process of integrating controllers and edge devices into the Cisco SD-WAN fabric, using automated deployment with PnP (Plug-and-Play), using ansible-collection-catalystwan modules and roles.
Workflow for Upgrades: Structured workflow that automates the upgrade process for controllers and edge devices.

ansible-collection-sdwan illustrates the power of Ansible's modularity and the significant benefits of using roles, custom modules, and collections for automating network operations. It stands as an indispensable resource for organizations looking to implement Infrastructure as Code (IaC) within their network infrastructure and embrace a more agile and DevOps-oriented approach to network management.

Requirements

This project utilizes a tech stack that includes Python, Ansible (and Ansible Galaxy), AWS cloud (Boto/Boto3, authentication with AWS CLI) Azure cloud (ansible azure collection) and finally Cisco SD-WAN. Below you will find the necessary information to set up your environment.

Before you begin, ensure that you have administrative access to your machine to install the required software.

See section Useful links and Getting Started for more in-depth documentation.

Operating System Requirements

This project is cross-platform and can be set up on the following operating systems:

Linux (Ubuntu, CentOS, Debian, etc.)
macOS
Windows (Note: Some tools might require Windows Subsystem for Linux (WSL) for full functionality)

Python requirement

Supported version: Python >=3.10+

Due to ansible-core==2.16 requirement, this collection requires Python 3.10 or greater.

Cloud authentication requirement

Verify that you have access to create resources with your provider:

AWS

See AWS Ansible Authentication docs to learn more.
See AWS CLI configuration to learn more.

Azure

See Authenticating with Azure

PnP Portal requirement

Current version of the full workflow for bringup SD-WAN assumes that users are familiar with Cisco Plug and Play Portal and its requirements.

See example Cisco Plug and Play Support Guide for Cisco SD-WAN Products.

Installing this collection

Install by cloning this repostiory - recommended way

You can install collection by first cloning this repository:

git clone git@github.com:cisco-open/ansible-collection-sdwan.git

Then setting your python environment. Recommended way: use supported version of Python (>=3.10) and set up your environment with:

python3 -m venv <your-venv-name>
source <your-venv-name>/bin/activate
pip install -r requirements.txt --no-deps

And then install ansible requirements:

ansible-galaxy install -r requirements.yml

Install with Ansible Galaxy

Note that when installing this collection with ansible-galaxy command, it will be placed inside your system collections path. That migth introduce additional complexity for using configuration files etc.

You can install this collection with the Ansible Galaxy CLI (requires ansible package installed)

ansible-galaxy collection install cisco.sdwan

The python module dependencies are not installed by ansible-galaxy. They can be manually installed using pip. Recommended way: use supported version of Python (>=3.10) and set up your environment with:

python3 -m venv <your-venv-name>
source <your-venv-name>/bin/activate

And then install python requirements:

pip install -r requirements.txt --no-deps

Note: For python packages installation troubleshooting see python-packages-installation

Verify that your ansible version is using python modules from vevn by using test playbook:

For AWS:

ansible-playbook playbooks/aws/test_env.yml

For Azure:

ansible-playbook playbooks/azure/test_env.yml

If playbook finished without any failed tasks, environment is ready for next tasks.

If requirements have been installed and tasks returned information about missing packages, please see Troubleshooting

Using this collection

Ansible Vault prerequisite

In this section, suggested usage of Ansible Vault with Vault password stored in files is presented. While not mandatory, it is recommended to utilize Ansible Vault for securing sensitive data such as credentials and secret keys. Ansible Vault provides encryption capabilities that help in maintaining the security of your secrets within your playbooks. However, the management of secrets is ultimately at your discretion, and you may employ any other method that aligns with your security policies and operational practices. Feel free to use any other manager to encrypt pnp_username and pnp_password variables.

Using Ansible Vault to securely provide PnP Portal credentials

First, create file with ansible-valut password that will be used to secure your vault. Example file: vault-password.txt, created with content:

mysafepassword

Then, supply values for pnp credentials in pnp_credentials.yml file. For azure you can use playbooks/azure/pnp_credentials.yml and for aws playbooks/aws/pnp_credentials.yml.

Encrypt the pnp credentials file with your valut password by running:

ansible-vault encrypt --vault-password-file=vault-password.txt playbooks/azure/pnp_credentials.yml

From now, playbooks/azure/pnp_credentials.yml or playbooks/aws/pnp_credentials.yml file will be encrypted.

In order to run playbook that requires pnp_credentials, users have to specify path for ansible vault password file. Example:

ansible-playbook playbooks/azure/non-existing-exmple.yml --vault-password-file=vault-password.txt

Configuration file

Full deployment and onboarding comes with predefined configuration file, that will bringup 3 controllers and all edge devices configured in PnP portal. It's user responsibility to ensure that PnP Portal configuration is correct and fautless.

Configuration file is located in:

for Azure: playbooks/azure/sdwan_config.yml
for AWS: playbooks/aws/sdwan_config.yml.

Please complete all fields marked as null.

Please see Prerequisites for Deploying Cisco SD-WAN Controllers in AWS and Deploy Cisco SD-WAN Controllers in AWS: Tasks in order to learn more about prerequisites and AMI Images on AWS.

Additional step: verify that your configuration file include all required variables, by running this pre-check playbook:

AWS:

ansible-playbook playbooks/aws/test_variables.yml --vault-password-file=vault-password.txt

Azure:

ansible-playbook playbooks/aws/test_variables.yml --vault-password-file=vault-password.txt

Final run

Finally, run full playbook, depending on your cloud provider:

ansible-playbook playbooks/azure/full_deploy_and_configure.yml --vault-password-file=vault-password.txt

ansible-playbook playbooks/aws/full_deploy_and_configure.yml --vault-password-file=vault-password.txt

Troubleshooting

Follow these steps to troubleshoot common issues:

1. Verify Your Ansible Version and Virtual Environment

Activate your virtual environment and run the command:

(example-venv) ➜  cisco.sdwan git:(master) ✗ ansible --version

Check that the 'ansible python module location' points to your virtual environment, for instance: /Users/myuser/Work/cisco.sdwan/example-venv.

2. Correct Ansible Version Pointing to the Wrong Virtual Environment

If Ansible is pointing to the wrong virtual environment, modify the sdwan_config.yml configuration file. Add this line:

ansible_python_interpreter: "/<path-to-your-venv>/bin/python"

Replace <path-to-your-venv> with the correct path.

3. Update Ansible Collections

To update your Ansible collections, run the following command:

ansible-galaxy collection install -r requirements.yml --upgrade

4. Double-Check Ansible Collection Installation Location

Ansible defaults to installing the collection in ~/.ansible/collections. This can cause problems if you're using the wrong collection version. Ensure your collection version is correct if you run into issues.

5. Python packages installation

Python packages requirements are formed to include all dependencies. Therefore if you face issues with installation, note that there is known confict:

    The user requested packaging
    catalystwan 0.31.2 depends on packaging<24.0 and >=23.0
    azure-cli-core 2.34.0 depends on packaging<22.0 and >=20.9

solved by using: pip install -r requirements.txt --no-deps command.

Containerized variant WIP

Section Under Construction!

Useful links and Getting Started

Python

Virtual Environment (venv)

To manage dependencies, it is recommended to use Python's built-in venv module to create a virtual environment.

Creating Virtual Environments

Ansible

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

Ansible Vault

Protecting sensitive data with Ansible vault

AWS CLI

AWS Authentication

Azure Authentication

Authenticating with Azure

Cisco SD-WAN

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.