Cisco MDS SAN Automation Framework

Author: Assaf Feuerstein

A comprehensive automation framework for managing Cisco MDS SAN (Storage Area Network) switches using Ansible, Python, and Jenkins CI/CD pipelines.

🎯 Overview

This project provides enterprise-grade automation for Cisco MDS Fibre Channel switches, enabling:

• Device Alias Management: Automated creation and removal of device aliases (human-readable names for WWPNs)
• Zone Configuration: Automated zone and zoneset management for controlling storage access
• Interface Management: Enable/disable FC interfaces during host provisioning and decommissioning
• Migration Tools: Convert Brocade SAN configurations to Cisco MDS format
• Maintenance Scripts: Automated CFS lock clearing and zone commit operations

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        CI/CD Pipeline                            │
│                    (Jenkins/GitHub Actions)                      │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Python Automation                           │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐    │
│   │ Device Alias│  │    Zone     │  │    Maintenance      │    │
│   │  Scripts    │  │   Scripts   │  │      Scripts        │    │
│   └─────────────┘  └─────────────┘  └─────────────────────┘    │
│                          │                                       │
│                          ▼                                       │
│              ┌─────────────────────┐                            │
│              │   NX-API Module     │                            │
│              │ (REST API Client)   │                            │
│              └─────────────────────┘                            │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Ansible Playbooks                             │
│   ┌─────────────────────┐  ┌─────────────────────────────┐     │
│   │ Device Alias Config │  │    Zone/Zoneset Config      │     │
│   └─────────────────────┘  └─────────────────────────────┘     │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Cisco MDS Fabric                             │
│   ┌───────────────┐                    ┌───────────────┐        │
│   │   Fabric A    │                    │   Fabric B    │        │
│   │  (Redundancy) │                    │  (Redundancy) │        │
│   │               │                    │               │        │
│   │ ┌───────────┐ │                    │ ┌───────────┐ │        │
│   │ │Core Switch│ │                    │ │Core Switch│ │        │
│   │ └───────────┘ │                    │ └───────────┘ │        │
│   │      │        │                    │      │        │        │
│   │ ┌────┴────┐   │                    │ ┌────┴────┐   │        │
│   │ │Edge NPV │   │                    │ │Edge NPV │   │        │
│   │ │Switches │   │                    │ │Switches │   │        │
│   │ └─────────┘   │                    │ └─────────┘   │        │
│   └───────────────┘                    └───────────────┘        │
└─────────────────────────────────────────────────────────────────┘

📁 Project Structure

CiscoMDS/
├── ansible/                      # Ansible playbooks and inventory
│   ├── group_vars/              # Ansible variables
│   │   ├── all.yml.example      # Global variables template
│   │   └── nxos.yml.example     # NX-OS connection settings
│   ├── templates/               # Jinja2 templates
│   ├── hosts.ini.example        # Inventory template
│   ├── device-alias-fabric-a.yml.example
│   ├── zone-fabric-a.yml.example
│   └── change_interface_state.yml
│
├── python/                      # Python automation scripts
│   ├── cisco/                   # NX-API client module
│   │   ├── __init__.py
│   │   └── nxapi.py            # REST API client
│   ├── add_device_alias.py     # Add device aliases
│   ├── add_zone.py             # Add zones
│   ├── remove_device_alias.py  # Remove device aliases
│   ├── remove_zone.py          # Remove zones
│   ├── cisco_mds_maintenance.py # Maintenance tasks
│   ├── brocade_migration.py    # Brocade to Cisco migration
│   ├── find_duplicates.py      # Find duplicate PWWNs
│   └── requirements.txt        # Python dependencies
│
├── pipeline/                    # Jenkins pipeline definitions
│   ├── Jenkinsfile.DeviceAlias
│   ├── Jenkinsfile.Zone
│   └── Jenkinsfile.InterfaceState
│
├── switch_configs/              # Switch configuration templates
│   ├── core_switch_initial.txt
│   ├── edge_switch_npv.txt
│   └── enable_nxapi.txt
│
├── scripts/                     # Shell utility scripts
│   ├── fix_device_alias.sh     # Rename device aliases
│   └── backup_config.sh        # Backup switch configs
│
├── configs/                     # Configuration backups (gitignored)
└── docs/                        # Additional documentation

🚀 Getting Started

Prerequisites

• Python 3.8+
• Ansible 2.10+ with cisco.nxos collection
• Cisco MDS switches with NX-API enabled
• (Optional) Jenkins for CI/CD pipelines

Installation

1. Clone the repository

   git clone https://github.com/assaffeuerstein/CiscoMDS.git
   cd CiscoMDS

2. Set up Python environment

   python3 -m venv .env
   source .env/bin/activate
   pip install -r python/requirements.txt

3. Install Ansible collections

   ansible-galaxy collection install cisco.nxos
   ansible-galaxy collection install ansible.netcommon

4. Configure inventory

   cp ansible/hosts.ini.example ansible/hosts.ini
   # Edit hosts.ini with your switch IPs

5. Configure credentials

   cp ansible/group_vars/nxos.yml.example ansible/group_vars/nxos.yml
   # Edit nxos.yml and use ansible-vault for encryption
   ansible-vault encrypt ansible/group_vars/nxos.yml

Enable NX-API on Switches

configure terminal
feature nxapi
no nxapi http port 8080
nxapi https port 8443
exit
copy running-config startup-config

📖 Usage

Python Scripts

Maintenance Tasks

# Check and fix CFS locks and pending zone changes
python3 python/cisco_mds_maintenance.py \
    --ip 192.168.1.10 \
    --username admin \
    --password secret \
    --vsan 2

# Dry run (check only)
python3 python/cisco_mds_maintenance.py \
    --ip 192.168.1.10 \
    --username admin \
    --password secret \
    --dry-run

Device Alias Management

# Add a device alias
python3 python/add_device_alias.py \
    --device-alias esxi_prod_host_01 \
    --pwwns 10:00:00:00:00:00:00:01 \
    --sw-username admin \
    --sw-password secret

# Remove a device alias
python3 python/remove_device_alias.py \
    --fabric 1 \
    --device-alias esxi_prod_host_01

Zone Management

# Add a zone
python3 python/add_zone.py \
    --zone storage_array_01_esxi_prod_host_01 \
    --members storage_array_01,esxi_prod_host_01

# Remove a zone
python3 python/remove_zone.py \
    --fabric 1 \
    --zone storage_array_01_esxi_prod_host_01

Brocade Migration

# Convert Brocade config to Cisco Ansible playbook
python3 python/brocade_migration.py \
    --source 192.168.2.1 \
    --context 1 \
    --vsan 2 \
    --zoneset ZS_Fabric_A \
    --fabric 1 \
    --username admin \
    --password secret \
    --aliases --zones

Ansible Playbooks

# Apply device alias configuration
ansible-playbook -i ansible/hosts.ini \
    ansible/device-alias-fabric-a.yml \
    --vault-password-file vault_pass.txt

# Apply zone configuration
ansible-playbook -i ansible/hosts.ini \
    ansible/zone-fabric-a.yml \
    --vault-password-file vault_pass.txt

# Change interface state
ansible-playbook -i ansible/switches.ini \
    ansible/change_interface_state.yml \
    -e "interface_on_first_switch=fc1/5" \
    -e "interface_on_second_switch=fc1/5" \
    -e "enabled=true"

Jenkins Pipelines

The project includes three Jenkins pipelines:

1. Device Alias Pipeline (Jenkinsfile.DeviceAlias)

   • Parameters: operation, hostname, wwn1, wwn2, dc
   • Automates adding/removing device aliases

2. Zone Pipeline (Jenkinsfile.Zone)

   • Parameters: operation, hostname, storage_array, dc
   • Automates adding/removing zones

3. Interface State Pipeline (Jenkinsfile.InterfaceState)

   • Parameters: action, serial, switch IPs, interfaces
   • Enables/disables FC interfaces

🔧 Configuration

Ansible Vault

Store sensitive credentials using Ansible Vault:

# Create encrypted credentials file
ansible-vault create ansible/group_vars/nxos.yml

# Encrypt a single string
ansible-vault encrypt_string 'mypassword' --name 'ansible_password'

# Edit encrypted file
ansible-vault edit ansible/group_vars/nxos.yml

Environment Variables

The scripts support these environment variables:

Variable	Description
CISCO_USER	Default username for switch authentication
CISCO_PASSWORD	Default password for switch authentication
ANSIBLE_VAULT_PASSWORD_FILE	Path to vault password file

🏷️ Naming Conventions

Device Aliases

• Use underscores, not hyphens: esxi_prod_host_01
• Include environment: esxi_prod_, k8s_stage_
• Storage arrays: storage_array_01_ct0_fc0

Zones

• Format: <storage_array>_<hostname>
• Example: storage_array_01_esxi_prod_host_01

Zonesets

• Fabric A: ZS_Fabric_A
• Fabric B: ZS_Fabric_B

🔒 Security Considerations

1. Credential Management

   • Use Ansible Vault for all credentials
   • Never commit passwords or vault files to Git
   • Use Jenkins credentials store for CI/CD

2. Network Security

   • NX-API uses HTTPS by default (port 8443)
   • Disable HTTP access on switches
   • Use dedicated management network

3. Access Control

   • Limit switch access to automation service accounts
   • Use RBAC on Jenkins for pipeline execution
   • Audit all configuration changes via Git

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Cisco for the NX-API and Ansible modules
• The Ansible community for the network automation tools
• All contributors to this project

📬 Contact

Author: Assaf Feuerstein

For questions or support, please open an issue on GitHub.

---

Note: This is a template project. Configure the example files with your environment-specific settings before use.