┌───────────────────────────────┐
│ 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
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. See example playbook for upgrades
- Workflows for backup and restore:
- Backup Device configuration (includes Device Templates, Policies, Feature Templates). See backup device configuration
- Restore Device configuration (includes Device Templates, Policies, Feature Templates). See restore device configuration
- Backup running config (cli templates). See backup running config
- Restore running config (cli templates). See restore running config
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.
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.
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)
Supported version: Python >=3.10+
- Due to ansible-core==2.16 requirement, this collection requires Python 3.10 or greater.
Verify that you have access to create resources with your provider:
-
See AWS Ansible Authentication docs to learn more.
-
See AWS CLI configuration to learn more.
Current version of the full workflow for bringup SD-WAN assumes that users are familiar with Cisco Plug and Play Portal and its requirements.
You can install collection by first cloning this repository:
git clone [email protected]:cisco-open/ansible-collection-sdwan.gitThen 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-depsAnd then install ansible requirements:
ansible-galaxy install -r requirements.ymlNote 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.sdwanThe 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/activateAnd then install python requirements:
pip install -r requirements.txt --no-depsNote: 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.ymlFor Azure:
ansible-playbook playbooks/azure/test_env.ymlIf 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
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.
First, create file with ansible-valut password that will be used to secure your vault.
Example file: vault-password.txt, created with content:
mysafepasswordThen, 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.ymlFrom 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.txtFull 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.txtAzure:
ansible-playbook playbooks/aws/test_variables.yml --vault-password-file=vault-password.txtFinally, run full playbook, depending on your cloud provider:
ansible-playbook playbooks/azure/full_deploy_and_configure.yml --vault-password-file=vault-password.txtansible-playbook playbooks/aws/full_deploy_and_configure.yml --vault-password-file=vault-password.txtFollow these steps to troubleshoot common issues:
Activate your virtual environment and run the command:
(example-venv) ➜ cisco.sdwan git:(master) ✗ ansible --versionCheck that the 'ansible python module location' points to your virtual environment, for instance: /Users/myuser/Work/cisco.sdwan/example-venv.
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.
To update your Ansible collections, run the following command:
ansible-galaxy collection install -r requirements.yml --upgradeAnsible 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.
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.
Section Under Construction!
To manage dependencies, it is recommended to use Python's built-in venv module to create a virtual environment.
Ansible Galaxy provides pre-packaged units of work known as roles, and it can be used to share and use content with Ansible.
See LICENSE file.
See Contributing file.
See Code of Conduct file.
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.