Skip to content

CVP_GUIDE.md

Latest commit

 

History

History
770 lines (602 loc) · 35.8 KB

CVP_GUIDE.md

File metadata and controls

770 lines (602 loc) · 35.8 KB
Raw

Cisco Validated Playbooks (CVP) - Complete Guide

Cisco Validated Ansible Collection

📖 Table of Contents

🎯 What is CVP?

Cisco Validated Playbooks (CVP) are production-ready automation solutions for Cisco Catalyst Center that accelerate your network automation journey. These playbooks have been validated by Cisco and include everything you need for successful deployments.

When to Use CVP

Scenario Recommended Approach
Learning Ansible basics Use simple playbooks/ examples
Reusable components Use roles/
Quick API tests Use modules directly
Production deployments Use CVP ⭐
Complex workflows Use CVP ⭐
Best practice examples Use CVP ⭐
Infrastructure as Code Use CVP ⭐

✨ Key Features

📦 Ready-to-Use Playbooks

Streamline Catalyst Center provisioning with ready-to-use Ansible playbooks. Automate configurations and simplify network management tasks.

✅ Input Validation Schemas

Yamale-based input validation schemas ensure user input accuracy for the playbooks by validating user input before execution. This significantly reduces the potential for human error and ensures consistent, reliable results.

📚 Comprehensive Guides

Comprehensive guides provide detailed instructions and practical examples for various Catalyst Center configuration use cases. Learn how to deploy, update, and maintain your network infrastructure with step-by-step guidance and best practices.

📝 Sample Inputs

Jumpstart your automation journey with sample input files that demonstrate proper formatting and supported values. Quickly create your own input configurations by adapting these examples.

🎨 Jinja-Based Templates

Enhance scalability and flexibility with Jinja-based templates support. These templates empower you to dynamically generate input configurations, adapting to various deployments with ease.

🏗️ Infrastructure as Code

Embrace infrastructure as code and manage your entire Catalyst Center configuration through Git. This provides:

  • Complete version control: Track every change and easily revert to previous states
  • Increased collaboration: Simplify teamwork with a centralized platform
  • Improved reliability: Reduce errors and ensure consistent configurations
  • Simplified deployments: Automate updates and rollbacks with confidence

📦 Installation

Install Collection (Includes CVPs)

# Install latest version
ansible-galaxy collection install cisco.catalystcenter

# Install specific version
ansible-galaxy collection install cisco.catalystcenter:2.7.0

# Upgrade to latest
ansible-galaxy collection install cisco.catalystcenter --upgrade

Verify Installation

# Check collection version
ansible-galaxy collection list cisco.catalystcenter

# List CVPs
ls ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cvp/

# Count CVPs
ls ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cvp/ | wc -l

🧾 Prerequisite: Inventory File

Every CVP playbook declares hosts: catalyst_center_hosts, so an inventory that defines this group is required. Running ansible-playbook without -i <inventory> will result in skipping: no hosts matched and no tasks will execute. Passing -e catalystcenter_host=... alone is not enough, because it only sets SDK connection variables, not the Ansible host pattern.

Minimal inventory (inventory/hosts.yml):

---
catalyst_center_hosts:
  hosts:
    catalyst_center220:
      ansible_connection: local
      catalystcenter_host: "{{ lookup('env', 'HOSTIP') }}"
      catalystcenter_username: "{{ lookup('env', 'CATALYST_CENTER_USERNAME') }}"
      catalystcenter_password: "{{ lookup('env', 'CATALYST_CENTER_PASSWORD') }}"
      catalystcenter_port: 443
      catalystcenter_version: 3.1.5
      catalystcenter_verify: false
      catalystcenter_debug: false

Export the matching environment variables:

export HOSTIP=<catalyst-center-ip-or-fqdn>
export CATALYST_CENTER_USERNAME=<username>
export CATALYST_CENTER_PASSWORD='<password>'

All ansible-playbook examples below assume this inventory exists at inventory/hosts.yml. Per-CVP README files (e.g. cvp/swim/README.md) use the same pattern.

🚀 Quick Start

5-Minute CVP Example

# 1. Install collection
ansible-galaxy collection install cisco.catalystcenter

# 2. Navigate to CVP directory
cd ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cvp/

# 3. Copy a CVP to your workspace
cp -r site_hierarchy ~/my-automation/

# 4. Navigate to CVP
cd ~/my-automation/site_hierarchy

# 5. Review README
cat README.md

# 6. Edit variables
vi vars/site_hierarchy_design_vars.yml

# 7. Run playbook (requires an inventory with the catalyst_center_hosts group;
#    see "Prerequisite: Inventory File" above)
ansible-playbook \
  -i inventory/hosts.yml \
  playbook/site_hierarchy_playbook.yml \
  -vvv

📁 CVP Structure

Every CVP follows this standard structure:

cvp/site_hierarchy/
├── README.md                          # Comprehensive guide
├── description.json                   # CVP metadata
├── playbook/                          # Ansible playbooks
│   ├── site_hierarchy_playbook.yml   # Main playbook
│   └── delete_site_hierarchy_playbook.yml  # Cleanup playbook (if applicable)
├── vars/                              # Variable examples
│   ├── site_hierarchy_design_vars.yml        # Main vars
│   ├── delete_site_hierarchy_design_vars.yml # Delete vars
│   └── jinja_template_site_hierarchy_design_vars.yml  # Template vars
├── schema/                            # Validation schemas
│   ├── sites_schema.yml              # Input schema
│   └── delete_sites_schema.yml       # Delete schema
├── images/                            # Screenshots
│   ├── site_image1.png
│   └── template_created_sites.png
├── jinja_template/                    # Jinja2 templates (optional)
│   └── sites_generation_template.j2
└── tmp/                               # Temporary files (gitignored)
    └── template_generated_file.yaml

💡 Usage Patterns

Pattern 1: Copy and Customize (Recommended for Production)

Best for: Production deployments, customization, version control

# Create project structure
mkdir -p ~/my-catalyst-automation
cd ~/my-catalyst-automation

# Copy CVPs you need
cp -r ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cvp/site_hierarchy .
cp -r ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cvp/device_discovery .
cp -r ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cvp/provision .

# Create project structure
mkdir -p group_vars/all
mkdir -p inventory

# Customize variables
vi site_hierarchy/vars/site_hierarchy_design_vars.yml
vi device_discovery/vars/device_discovery_vars.yml

# Version control
git init
git add .
git commit -m "Initial CVP setup"

# Run playbooks (inventory must define the catalyst_center_hosts group)
ansible-playbook -i inventory/hosts.yml \
  site_hierarchy/playbook/site_hierarchy_playbook.yml
ansible-playbook -i inventory/hosts.yml \
  device_discovery/playbook/device_discovery_playbook.yml

Pattern 2: Direct Reference (Quick Testing)

Best for: Testing, one-off runs, CI/CD

# Run CVP directly from collection (still requires an inventory file)
ansible-playbook \
  -i inventory/hosts.yml \
  ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml \
  -e VARS_FILE_PATH=$(pwd)/my-custom-vars.yml

Pattern 3: Hybrid Approach

Best for: Combining multiple CVPs

import_playbook is a top-level directive, not a task. Each entry below is a separate play that inherits the imported playbook's hosts: (here: catalyst_center_hosts), so the inventory must define that group. Per-CVP inputs are passed via the vars: block as VARS_FILE_PATH, resolved relative to the imported playbook's directory (see VARS_FILE_PATH note in any per-CVP README, e.g. cvp/swim/README.md).

# deploy-all.yml
---
- name: Deploy Site Hierarchy
  ansible.builtin.import_playbook: cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml
  vars:
    VARS_FILE_PATH: ../vars/site_hierarchy_design_vars.yml

- name: Configure Network Settings
  ansible.builtin.import_playbook: cvp/network_settings/playbook/network_settings_playbook.yml
  vars:
    VARS_FILE_PATH: ../vars/network_settings_vars.yml

- name: Discover Devices
  ansible.builtin.import_playbook: cvp/device_discovery/playbook/device_discovery_playbook.yml
  vars:
    VARS_FILE_PATH: ../vars/device_discovery_vars.yml
# Run master playbook (inventory must define the catalyst_center_hosts group)
ansible-playbook -i inventory/hosts.yml deploy-all.yml

🔄 CI/CD Integration

For Red Hat certified deployments, run these examples inside an Ansible Execution Environment or runner image that already includes ansible-core >= 2.16 with Python 3.12. The examples below only install the Cisco Catalyst Center Python SDK with pip.

GitHub Actions

# .github/workflows/catalyst-center-deploy.yml
name: Catalyst Center Deployment

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  deploy-infrastructure:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.12'
      
      - name: Install dependencies
        run: |
          pip install catalystcentersdk
          ansible-galaxy collection install cisco.catalystcenter
      
      - name: Copy CVPs
        run: |
          mkdir -p cvp
          cp -r ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cvp/site_hierarchy cvp/
          cp -r ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cvp/network_settings cvp/
      
      - name: Deploy Site Hierarchy
        env:
          HOSTIP: ${{ secrets.CATALYSTCENTER_HOST }}
          CATALYST_CENTER_USERNAME: ${{ secrets.CATALYSTCENTER_USERNAME }}
          CATALYST_CENTER_PASSWORD: ${{ secrets.CATALYSTCENTER_PASSWORD }}
        run: |
          ansible-playbook \
            -i inventory/hosts.yml \
            cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml \
            -e VARS_FILE_PATH=$(pwd)/vars/production-sites.yml
      
      - name: Deploy Network Settings
        env:
          HOSTIP: ${{ secrets.CATALYSTCENTER_HOST }}
          CATALYST_CENTER_USERNAME: ${{ secrets.CATALYSTCENTER_USERNAME }}
          CATALYST_CENTER_PASSWORD: ${{ secrets.CATALYSTCENTER_PASSWORD }}
        run: |
          ansible-playbook \
            -i inventory/hosts.yml \
            cvp/network_settings/playbook/network_settings_playbook.yml \
            -e VARS_FILE_PATH=$(pwd)/vars/production-network-settings.yml

GitLab CI

# .gitlab-ci.yml
stages:
  - prepare
  - validate
  - deploy

variables:
  ANSIBLE_FORCE_COLOR: "true"
  CVP_VERSION: "2.7.0"

.install_ansible: &install_ansible
  - pip install catalystcentersdk
  - ansible-galaxy collection install cisco.catalystcenter:${CVP_VERSION}

prepare:
  stage: prepare
  image: python:3.12
  script:
    - *install_ansible
    - mkdir -p cvp
    - cp -r ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cvp/site_hierarchy cvp/
  artifacts:
    paths:
      - cvp/
    expire_in: 1 hour

validate:
  stage: validate
  image: python:3.12
  dependencies:
    - prepare
  script:
    - *install_ansible
    - ansible-playbook -i inventory/hosts.yml cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml --syntax-check
    - ansible-lint cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml || true

deploy:
  stage: deploy
  image: python:3.12
  dependencies:
    - prepare
  script:
    - *install_ansible
    - export HOSTIP=$CATALYSTCENTER_HOST
    - export CATALYST_CENTER_USERNAME=$CATALYSTCENTER_USERNAME
    - export CATALYST_CENTER_PASSWORD=$CATALYSTCENTER_PASSWORD
    - ansible-playbook
        -i inventory/hosts.yml
        cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml
        -e VARS_FILE_PATH=$CI_PROJECT_DIR/vars/production.yml
  only:
    - main
  when: manual

Jenkins

// Jenkinsfile
pipeline {
    agent any
    
    parameters {
        choice(name: 'CVP_NAME', choices: ['site_hierarchy', 'device_discovery', 'network_settings'], description: 'Select CVP to deploy')
        choice(name: 'ENVIRONMENT', choices: ['dev', 'staging', 'production'], description: 'Target environment')
    }
    
    environment {
        CATALYSTCENTER_HOST = credentials('catalyst-center-host')
        CATALYSTCENTER_USERNAME = credentials('catalyst-center-username')
        CATALYSTCENTER_PASSWORD = credentials('catalyst-center-password')
        CVP_PATH = "${WORKSPACE}/cvp"
    }
    
    stages {
        stage('Setup') {
            steps {
                sh '''
                    python3 -m venv venv
                    . venv/bin/activate
                    pip install catalystcentersdk
                    ansible-galaxy collection install cisco.catalystcenter
                '''
            }
        }
        
        stage('Copy CVP') {
            steps {
                sh '''
                    . venv/bin/activate
                    mkdir -p ${CVP_PATH}
                    cp -r ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cvp/${CVP_NAME} ${CVP_PATH}/
                '''
            }
        }
        
        stage('Validate') {
            steps {
                sh '''
                    . venv/bin/activate
                    ansible-playbook -i inventory/hosts.yml \
                        ${CVP_PATH}/${CVP_NAME}/playbook/*_playbook.yml --syntax-check
                '''
            }
        }
        
        stage('Deploy') {
            when {
                expression { params.ENVIRONMENT == 'production' }
            }
            steps {
                input message: 'Deploy to production?', ok: 'Deploy'
                sh '''
                    . venv/bin/activate
                    export HOSTIP=$CATALYSTCENTER_HOST
                    export CATALYST_CENTER_USERNAME=$CATALYSTCENTER_USERNAME
                    export CATALYST_CENTER_PASSWORD=$CATALYSTCENTER_PASSWORD
                    ansible-playbook \
                        -i inventory/hosts.yml \
                        ${CVP_PATH}/${CVP_NAME}/playbook/*_playbook.yml \
                        -e VARS_FILE_PATH=${WORKSPACE}/vars/${ENVIRONMENT}.yml \
                        -vv
                '''
            }
        }
    }
    
    post {
        always {
            cleanWs()
        }
    }
}

📚 CVP Catalog by Use Case

All CVPs are located in the cvp/ directory of the collection. Each CVP includes a comprehensive README with detailed instructions.

Day 0: Access and Integrations

Establish foundational access control and integrate with external systems.

CVP Description README
users_and_roles Role Based Access Control and Users Management 📖 Guide
ise_radius_integration ISE and AAA Servers Integration 📖 Guide
ansible_vault_update Update Ansible Vault encrypted credentials 📖 Guide

Day 1: Design and Discovery

Design your network hierarchy, configure settings, and discover devices.

CVP Description README
site_hierarchy Site Hierarchy and Floor Maps design 📖 Guide ⭐
device_credentials Device Credentials configurations and assignment 📖 Guide
network_settings Network Settings (Servers, Banners, TZ, SNMP, Logging, Telemetry) 📖 Guide
wireless_design Wireless Design Management 📖 Guide
network_profile_wireless Wireless Network Profile Management 📖 Guide
network_profile_switching Network Profile Switching Management 📖 Guide
device_discovery Devices Discovery 📖 Guide ⭐
inventory Device Inventory and device management 📖 Guide
plug_and_play Plug and Play Device Onboarding 📖 Guide
provision Device Provisioning and Re-Provisioning Management 📖 Guide
device_templates Design and Deploy Device Templates 📖 Guide
tags_manager Tags Management 📖 Guide
access_point_location Access Point location management on floor maps 📖 Guide

Day 2: Underlay and SD-Access

Configure underlay automation and SD-Access fabric.

CVP Description README
lan_automation Underlay Automation (LAN Automation) Management 📖 Guide
sda_fabric_sites_zones SDA Fabric Site and Fabric Zones 📖 Guide ⭐
sda_fabric_transits SDA Fabric Transits (IP transit and SDA Transit) Management 📖 Guide
sda_virtual_networks_l2l3_gateways Virtual Networks and L3 Anycast Gateways and L2 VLANs Management 📖 Guide
sda_fabric_device_roles SDA Fabric Device assignment to fabric sites and zones 📖 Guide
sda_hostonboarding SDA Fabric Devices and Host Onboarding 📖 Guide
sda_fabric_discover_and_onboard_fabric_devices Discover and onboard devices into the SDA fabric 📖 Guide
sda_fabric_extranet_policy SDA Extranet Policies Management 📖 Guide
sda_fabric_multicast SDA Fabric Multicast Management 📖 Guide
application_policy Application Policy Management 📖 Guide

Day N: Operations

Ongoing operations including software upgrades, compliance, backups, and assurance.

CVP Description README
swim Devices Software image management (SWIM) 📖 Guide
network_compliance Device compliance and remediation management 📖 Guide
events_and_notifications Notification Destination and Events Subscription 📖 Guide
device_replacement_rma Devices Replacement Management 📖 Guide
accesspoints_configuration_provisioning Access Point Provisioning and Configuration Management 📖 Guide
device_config_backup Managed network devices configurations backup management 📖 Guide
assurance_health_score_settings Assurance Health Score KPIs settings and thresholds management 📖 Guide
assurance_pathtrace Assurance Path Trace Management 📖 Guide
assurance_issues_management Assurance issues and events management 📖 Guide
assurance_intelligent_capture Assurance ICAP Management 📖 Guide
fabric_devices_info SDA Fabric Devices Information and Inventory Management 📖 Guide
network_devices_info Network Devices Information and Inventory Management 📖 Guide
backup_and_restore Configuration Backup and Restore Management 📖 Guide
reports Reports Management and Scheduling 📖 Guide

Migration Use Cases

Specialized workflows for migration scenarios.

CVP Description README
sda_port_assignment_migration SDA Port Assignment Migration 📖 Guide
sda_device_removal_and_unprovision SDA Device Removal and Unprovision 📖 Guide

Configuration Generators

Extract current configurations for documentation or migration purposes.

CVP Description README
accesspoint_config_generator Access Point Config Generator 📖 Guide
accesspoint_location_config_generator Access Point Location Config Generator 📖 Guide
application_policy_config_generator Application Policy Config Generator 📖 Guide
assurance_device_health_score_settings_config_generator Assurance Device Health Score Settings Config Generator 📖 Guide
assurance_issue_config_generator Assurance Issue Config Generator 📖 Guide
backup_and_restore_config_generator Backup and Restore Config Generator 📖 Guide
device_credential_config_generator Device Credential Config Generator 📖 Guide
discovery_config_generator Discovery Config Generator 📖 Guide
events_and_notifications_config_generator Events and Notifications Config Generator 📖 Guide
inventory_config_generator Inventory Config Generator 📖 Guide
ise_radius_integration_config_generator ISE Radius Integration Config Generator 📖 Guide
network_profile_switching_config_generator Network Profile Switching Config Generator 📖 Guide
network_profile_wireless_config_generator Network Profile Wireless Config Generator 📖 Guide
network_settings_config_generator Network Settings Config Generator 📖 Guide
pnp_config_generator PnP Config Generator 📖 Guide
provision_config_generator Provision Config Generator 📖 Guide
sda_extranet_policies_config_generator SDA Extranet Policies Config Generator 📖 Guide
sda_fabric_devices_config_generator SDA Fabric Devices Config Generator 📖 Guide
sda_fabric_multicast_config_generator SDA Fabric Multicast Config Generator 📖 Guide
sda_fabric_sites_zones_config_generator SDA Fabric Sites Zones Config Generator 📖 Guide
sda_fabric_transits_config_generator SDA Fabric Transits Config Generator 📖 Guide
sda_fabric_virtual_networks_config_generator SDA Fabric Virtual Networks Config Generator 📖 Guide
sda_host_port_onboarding_config_generator SDA Host Port Onboarding Config Generator 📖 Guide
site_config_generator Site Config Generator 📖 Guide
tags_config_generator Tags Config Generator 📖 Guide
template_config_generator Template Config Generator 📖 Guide
user_role_config_generator User Role Config Generator 📖 Guide
wired_campus_automation_config_generator Wired Campus Automation Config Generator 📖 Guide
wireless_design_config_generator Wireless Design Config Generator 📖 Guide

Note: ⭐ indicates the most commonly used CVPs for getting started.

✅ Best Practices

1. Version Control Your Customizations

# Initialize git in your project
git init

# Add CVPs
git add cvp/

# Track your customizations
git commit -m "Add customized CVPs"

2. Use Ansible Vault for Secrets

The inventory at Prerequisite: Inventory File reads credentials from environment variables. For long-term storage, keep the same variable names (catalystcenter_host, catalystcenter_username, catalystcenter_password) but source them from an Ansible Vault file in group_vars/, so they are picked up automatically by the catalyst_center_hosts group without -e overrides.

# 1. Create vault file for the catalyst_center_hosts group
mkdir -p group_vars/catalyst_center_hosts
ansible-vault create group_vars/catalyst_center_hosts/vault.yml
# group_vars/catalyst_center_hosts/vault.yml (encrypted)
catalystcenter_host: "10.1.1.1"
catalystcenter_username: "admin"
catalystcenter_password: "secret"
# 2. Run the playbook — vault vars override the env-based defaults
ansible-playbook -i inventory/hosts.yml \
  cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml \
  --ask-vault-pass

3. Validate Inputs with Schemas

# Install yamale
pip install yamale

# Validate your vars file
yamale -s cvp/site_hierarchy/schema/sites_schema.yml \
       cvp/site_hierarchy/vars/site_hierarchy_design_vars.yml

4. Test in Non-Production First

# Use check mode
ansible-playbook -i inventory/hosts.yml \
  cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml --check

# Use diff mode
ansible-playbook -i inventory/hosts.yml \
  cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml --diff

# Limit to specific hosts
ansible-playbook -i inventory/hosts.yml \
  cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml --limit dev-catalyst-center

5. Keep CVPs Updated

# Update collection
ansible-galaxy collection install cisco.catalystcenter --upgrade

# Compare with your customized version
diff -r my-project/site_hierarchy \
  ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cvp/site_hierarchy/

🔧 Troubleshooting

CVP Not Found

# Verify collection is installed
ansible-galaxy collection list cisco.catalystcenter

# Check CVP exists
ls ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cvp/site_hierarchy

# Reinstall if needed
ansible-galaxy collection install cisco.catalystcenter --force

Permission Issues

# Check file permissions
ls -la ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cvp/

# Fix permissions if needed
chmod -R u+rw ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cvp/

Playbook Errors

# Run with verbose output
ansible-playbook -i inventory/hosts.yml \
  cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml -vvv

# Check syntax
ansible-playbook -i inventory/hosts.yml \
  cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml --syntax-check

# Validate variables
cat cvp/site_hierarchy/vars/site_hierarchy_design_vars.yml

skipping: no hosts matched

This error means the inventory does not define the catalyst_center_hosts group that every CVP playbook targets. Create the inventory shown in Prerequisite: Inventory File and pass it with -i. Setting -e catalystcenter_host=... alone will not fix this.

📞 Support

🎓 Learning Resources

  1. Start Here: cvp/site_hierarchy/ - Simplest CVP
  2. Next: cvp/device_discovery/ - Device management
  3. Advanced: cvp/sda_fabric_sites_zones/ - SDA fabric

Happy Automating with Cisco Validated Playbooks! 🚀