Merge pull request #21 from cisco-en-programmability/thomas_cvp

Enhancement: CVP_GUIDE.md, cvp/README.md and file ise_radius_integration_config_schema.yml and backup_and_restore_config_inputs.yaml

Author: DNACENSolutions

CVP_GUIDE.md

@@ -59,7 +59,7 @@ Jumpstart your automation journey with sample input files that demonstrate prope
 ### 🎨 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
+### 🏗️ 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
@@ -68,7 +68,7 @@ Embrace infrastructure as code and manage your entire Catalyst Center configurat
 
 ---
 
-## �📦 Installation
+## 📦 Installation
 
 ### Install Collection (Includes CVPs)
 
@@ -98,6 +98,45 @@ 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`):
+
+```yaml
+---
+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:
+
+```bash
+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](cvp/swim/README.md)) use the same pattern.
+
+---
+
 ## 🚀 Quick Start
 
 ### 5-Minute CVP Example
@@ -121,11 +160,11 @@ cat README.md
 # 6. Edit variables
 vi vars/site_hierarchy_design_vars.yml
 
-# 7. Run playbook
-ansible-playbook playbook/site_hierarchy_playbook.yml \
-  -e catalystcenter_host=10.1.1.1 \
-  -e catalystcenter_username=admin \
-  -e catalystcenter_password=secret \
+# 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
 ```
 
@@ -189,51 +228,58 @@ git init
 git add .
 git commit -m "Initial CVP setup"
 
-# Run playbooks
-ansible-playbook site_hierarchy/playbook/site_hierarchy_playbook.yml
-ansible-playbook device_discovery/playbook/device_discovery_playbook.yml
+# 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
 
 ```bash
-# Run CVP directly from collection
+# 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 @my-custom-vars.yml \
-  -e catalystcenter_host=10.1.1.1 \
-  -e catalystcenter_username=admin \
-  -e catalystcenter_password=secret
+  -e VARS_FILE_PATH=$(pwd)/my-custom-vars.yml
 ```
 
 ### Pattern 3: Hybrid Approach
 
 **Best for**: Combining multiple CVPs
 
-```bash
-# Create master playbook
-cat > deploy-all.yml <<EOF
+`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](cvp/swim/README.md)).
+
+```yaml
+# deploy-all.yml
 ---
-- name: Complete Catalyst Center Deployment
-  hosts: localhost
-  gather_facts: false
-  
-  tasks:
-    # Import CVP playbooks
-    - name: Deploy Site Hierarchy
-      ansible.builtin.import_playbook: ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml
-    
-    - name: Configure Network Settings
-      ansible.builtin.import_playbook: ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cvp/network_settings/playbook/network_settings_playbook.yml
-    
-    - name: Discover Devices
-      ansible.builtin.import_playbook: ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cvp/device_discovery/playbook/device_discovery_playbook.yml
-EOF
+- 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
-ansible-playbook deploy-all.yml
+```bash
+# Run master playbook (inventory must define the catalyst_center_hosts group)
+ansible-playbook -i inventory/hosts.yml deploy-all.yml
 ```
 
 ---
@@ -277,27 +323,25 @@ jobs:
       
       - name: Deploy Site Hierarchy
         env:
-          CATALYSTCENTER_HOST: ${{ secrets.CATALYSTCENTER_HOST }}
-          CATALYSTCENTER_USERNAME: ${{ secrets.CATALYSTCENTER_USERNAME }}
-          CATALYSTCENTER_PASSWORD: ${{ secrets.CATALYSTCENTER_PASSWORD }}
+          HOSTIP: ${{ secrets.CATALYSTCENTER_HOST }}
+          CATALYST_CENTER_USERNAME: ${{ secrets.CATALYSTCENTER_USERNAME }}
+          CATALYST_CENTER_PASSWORD: ${{ secrets.CATALYSTCENTER_PASSWORD }}
         run: |
-          ansible-playbook cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml \
-            -e catalystcenter_host=$CATALYSTCENTER_HOST \
-            -e catalystcenter_username=$CATALYSTCENTER_USERNAME \
-            -e catalystcenter_password=$CATALYSTCENTER_PASSWORD \
-            -e @vars/production-sites.yml
+          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:
-          CATALYSTCENTER_HOST: ${{ secrets.CATALYSTCENTER_HOST }}
-          CATALYSTCENTER_USERNAME: ${{ secrets.CATALYSTCENTER_USERNAME }}
-          CATALYSTCENTER_PASSWORD: ${{ secrets.CATALYSTCENTER_PASSWORD }}
+          HOSTIP: ${{ secrets.CATALYSTCENTER_HOST }}
+          CATALYST_CENTER_USERNAME: ${{ secrets.CATALYSTCENTER_USERNAME }}
+          CATALYST_CENTER_PASSWORD: ${{ secrets.CATALYSTCENTER_PASSWORD }}
         run: |
-          ansible-playbook cvp/network_settings/playbook/network_settings_playbook.yml \
-            -e catalystcenter_host=$CATALYSTCENTER_HOST \
-            -e catalystcenter_username=$CATALYSTCENTER_USERNAME \
-            -e catalystcenter_password=$CATALYSTCENTER_PASSWORD \
-            -e @vars/production-network-settings.yml
+          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
@@ -336,7 +380,7 @@ validate:
     - prepare
   script:
     - *install_ansible
-    - ansible-playbook cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml --syntax-check
+    - 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:
@@ -346,11 +390,13 @@ deploy:
     - prepare
   script:
     - *install_ansible
-    - ansible-playbook cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml
-        -e catalystcenter_host=$CATALYSTCENTER_HOST
-        -e catalystcenter_username=$CATALYSTCENTER_USERNAME
-        -e catalystcenter_password=$CATALYSTCENTER_PASSWORD
-        -e @vars/production.yml
+    - 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
@@ -401,7 +447,8 @@ pipeline {
             steps {
                 sh '''
                     . venv/bin/activate
-                    ansible-playbook ${CVP_PATH}/${CVP_NAME}/playbook/*_playbook.yml --syntax-check
+                    ansible-playbook -i inventory/hosts.yml \
+                        ${CVP_PATH}/${CVP_NAME}/playbook/*_playbook.yml --syntax-check
                 '''
             }
         }
@@ -414,11 +461,13 @@ pipeline {
                 input message: 'Deploy to production?', ok: 'Deploy'
                 sh '''
                     . venv/bin/activate
-                    ansible-playbook ${CVP_PATH}/${CVP_NAME}/playbook/*_playbook.yml \
-                        -e catalystcenter_host=$CATALYSTCENTER_HOST \
-                        -e catalystcenter_username=$CATALYSTCENTER_USERNAME \
-                        -e catalystcenter_password=$CATALYSTCENTER_PASSWORD \
-                        -e @vars/${ENVIRONMENT}.yml \
+                    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
                 '''
             }
@@ -447,6 +496,7 @@ Establish foundational access control and integrate with external systems.
 |-----|-------------|--------|
 | **users_and_roles** | Role Based Access Control and Users Management | [📖 Guide](cvp/users_and_roles/README.md) |
 | **ise_radius_integration** | ISE and AAA Servers Integration | [📖 Guide](cvp/ise_radius_integration/README.md) |
+| **ansible_vault_update** | Update Ansible Vault encrypted credentials | [📖 Guide](cvp/ansible_vault_update/README.md) |
 
 ---
 
@@ -468,6 +518,7 @@ Design your network hierarchy, configure settings, and discover devices.
 | **provision** | Device Provisioning and Re-Provisioning Management | [📖 Guide](cvp/provision/README.md) |
 | **device_templates** | Design and Deploy Device Templates | [📖 Guide](cvp/device_templates/README.md) |
 | **tags_manager** | Tags Management | [📖 Guide](cvp/tags_manager/README.md) |
+| **access_point_location** | Access Point location management on floor maps | [📖 Guide](cvp/access_point_location/README.md) |
 
 ---
 
@@ -483,6 +534,7 @@ Configure underlay automation and SD-Access fabric.
 | **sda_virtual_networks_l2l3_gateways** | Virtual Networks and L3 Anycast Gateways and L2 VLANs Management | [📖 Guide](cvp/sda_virtual_networks_l2l3_gateways/README.md) |
 | **sda_fabric_device_roles** | SDA Fabric Device assignment to fabric sites and zones | [📖 Guide](cvp/sda_fabric_device_roles/README.md) |
 | **sda_hostonboarding** | SDA Fabric Devices and Host Onboarding | [📖 Guide](cvp/sda_hostonboarding/README.md) |
+| **sda_fabric_discover_and_onboard_fabric_devices** | Discover and onboard devices into the SDA fabric | [📖 Guide](cvp/sda_fabric_discover_and_onboard_fabric_devices/README.md) |
 | **sda_fabric_extranet_policy** | SDA Extranet Policies Management | [📖 Guide](cvp/sda_fabric_extranet_policy/README.md) |
 | **sda_fabric_multicast** | SDA Fabric Multicast Management | [📖 Guide](cvp/sda_fabric_multicast/README.md) |
 | **application_policy** | Application Policy Management | [📖 Guide](cvp/application_policy/README.md) |
@@ -580,18 +632,30 @@ git commit -m "Add customized CVPs"
 
 ### 2. Use Ansible Vault for Secrets
 
+The inventory at [Prerequisite: Inventory File](#-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.
+
 ```bash
-# Create vault file
-ansible-vault create group_vars/all/vault.yml
+# 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
+```
 
-# Add credentials
-vault_catalystcenter_host: "10.1.1.1"
-vault_catalystcenter_username: "admin"
-vault_catalystcenter_password: "secret"
+```yaml
+# group_vars/catalyst_center_hosts/vault.yml (encrypted)
+catalystcenter_host: "10.1.1.1"
+catalystcenter_username: "admin"
+catalystcenter_password: "secret"
+```
 
-# Reference in playbook
-ansible-playbook cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml \
-  -e catalystcenter_host="{{ vault_catalystcenter_host }}" \
+```bash
+# 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
 ```
 
@@ -610,13 +674,16 @@ yamale -s cvp/site_hierarchy/schema/sites_schema.yml \
 
 ```bash
 # Use check mode
-ansible-playbook cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml --check
+ansible-playbook -i inventory/hosts.yml \
+  cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml --check
 
 # Use diff mode
-ansible-playbook cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml --diff
+ansible-playbook -i inventory/hosts.yml \
+  cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml --diff
 
 # Limit to specific hosts
-ansible-playbook cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml --limit dev-catalyst-center
+ansible-playbook -i inventory/hosts.yml \
+  cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml --limit dev-catalyst-center
 ```
 
 ### 5. Keep CVPs Updated
@@ -661,15 +728,24 @@ chmod -R u+rw ~/.ansible/collections/ansible_collections/cisco/catalystcenter/cv
 
 ```bash
 # Run with verbose output
-ansible-playbook cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml -vvv
+ansible-playbook -i inventory/hosts.yml \
+  cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml -vvv
 
 # Check syntax
-ansible-playbook cvp/site_hierarchy/playbook/site_hierarchy_playbook.yml --syntax-check
+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](#-prerequisite-inventory-file) and pass it
+with `-i`. Setting `-e catalystcenter_host=...` alone will not fix this.
+
 ---
 
 ## 📞 Support