Refresh Catalyst SD-WAN compatibility for current releases

.ansible-lint

@@ -14,6 +14,8 @@ exclude_paths:
   - .dev_dir/example_dev_vars.yml
   - .dev_dir/*
   - playbooks/tests/configuration_file_dev_vars.yml
+  # External SDK imports are explicitly baselined for ansible-test 2.21.
+  - tests/sanity/ignore-2.21.txt
   - .ansible
 # parseable: true
 # quiet: true

.dev_dir/software_upgrades_with_remote_server.yml

@@ -4,7 +4,7 @@
 ---
 
 # This playbook uses example role for remote upgrades.
-# It assumes that controllers are <20.13 version and Edge are <17.13 version.
+# Run the Manager release compatibility smoke test before destructive upgrade testing.
 # It configures Remote Server, uploads images, then perform installation, activation and default version set.
 # Doesn't include cEdge software upgrades - known bug with cEdge with Remote Images
 # Vars provided in this playbook are dev_vars

.flake8

@@ -1,2 +1,2 @@
 [flake8]
-ignore = E402
+ignore = E402,E704

.gitattributes

@@ -0,0 +1,5 @@
+* text=auto
+*.j2 text eol=lf
+*.py text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf

.github/workflows/ansible-doc-validation.yml

@@ -18,12 +18,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out the repository
-        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Python
-        uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f # v5.1.1
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: '3.10'
+          python-version: '3.13'
 
       - name: Get collection namespace and name from galaxy.yml
         id: collection-name
@@ -40,7 +40,7 @@ jobs:
           echo "COLLECTION_NAME=$NAME" >> $GITHUB_ENV
 
       - name: Install Ansible
-        run: pip install ansible==9.4.0
+        run: pip install ansible==14.3.1 catalystwan==0.41.5.dev2
 
       - name: Build and install the collection
         run: |

.github/workflows/compatibility.yml

@@ -0,0 +1,51 @@
+name: Compatibility
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions: read-all
+
+jobs:
+  sdk-and-ansible:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+        catalystwan-version: ["0.41.5.dev2", "0.41.6"]
+
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "${{ matrix.python-version }}"
+
+      - name: Install the current automation stack
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install \
+            "ansible==14.3.1" \
+            "catalystwan==${{ matrix.catalystwan-version }}" \
+            "pytest==9.1.1"
+
+      - name: Run SDK compatibility tests
+        run: python -m pytest -q tests/unit
+
+      - name: Build and install the collection
+        run: |
+          ansible-galaxy collection build . --force
+          ansible-galaxy collection install cisco-catalystwan-*.tar.gz --force
+
+      - name: Validate module documentation imports
+        run: |
+          for module in plugins/modules/*.py; do
+            module_name="${module##*/}"
+            ansible-doc --type module "cisco.catalystwan.${module_name%.py}" >/dev/null
+          done

.github/workflows/galaxy-importer.yml

@@ -21,12 +21,12 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Python
-        uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f # v5.1.1
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: '3.10'
+          python-version: '3.13'
 
       - name: Get collection namespace and name from galaxy.yml
         id: collection-name
@@ -47,7 +47,7 @@ jobs:
 
       - name: Install Ansible and importer
         run: |
-          pip install ansible==9.4.0
+          pip install ansible==14.3.1
           pip install ansible-importer
           pip install galaxy-importer
 

.github/workflows/linters.yml

@@ -5,7 +5,7 @@ on:
 
   push:
     branches:
-      - master
+      - main
 
 permissions: read-all
 
@@ -14,27 +14,27 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.10']
+        python-version: ['3.14']
     defaults:
       run:
         shell: sh
 
     steps:
       - name: Check out the repository
-        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Python
-        uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f # v5.1.1
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: '3.10'
+          python-version: '3.14'
 
       - uses: isort/isort-action@master
         with:
           requirementsFiles: "requirements.txt"
-          isortVersion: '5.12.0'
+          isortVersion: '8.0.1'
 
       - name: Install pycln
-        run: pip install pycln==2.4.0
+        run: pip install pycln==2.6.0
 
       - name: Run pycln
         run: pycln --all .
@@ -43,10 +43,10 @@ jobs:
         uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
 
       - name: Run ansible-lint
-        uses: ansible/ansible-lint@v25.8.1
+        uses: ansible/ansible-lint@665d9e07a1943254d2910faffc106adaf7ea7294 # v26.8.0
 
       - name: Install detect-secrets
-        run: pip install detect-secrets==1.4.0
+        run: pip install detect-secrets==1.5.0
 
       - name: Run detect-secrets
         run: detect-secrets scan

.github/workflows/release-from-tag.yml

@@ -14,12 +14,12 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Python
-        uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f # v5.1.1
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: '3.10'
+          python-version: '3.13'
 
       - name: Get collection version from galaxy.yml
         id: collection-version
@@ -57,7 +57,7 @@ jobs:
 
       - name: Install Ansible
         run: |
-          pip install ansible==9.4.0
+          pip install ansible==14.3.1
 
       - name: Build collection
         run: |

.github/workflows/sanity.yml

@@ -0,0 +1,38 @@
+name: Ansible sanity
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  schedule:
+    - cron: "23 9 * * 1"
+  workflow_dispatch:
+
+permissions: read-all
+
+jobs:
+  sanity:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Check out the collection
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          path: ansible_collections/cisco/catalystwan
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "${{ matrix.python-version }}"
+
+      - name: Install ansible-test
+        run: python -m pip install "ansible==14.3.1"
+
+      - name: Run collection sanity tests
+        working-directory: ansible_collections/cisco/catalystwan
+        run: ansible-test sanity --python "${{ matrix.python-version }}" --color yes

.pre-commit-config.yaml

@@ -1,47 +1,47 @@
 files: '.py'
 exclude: '.git'
-default_stages: [commit]
+default_stages: [pre-commit]
 
 repos:
-  - repo: https://github.com/timothycrosley/isort
-    rev: 5.12.0
+  - repo: https://github.com/PyCQA/isort
+    rev: 8.0.1
     hooks:
       - id: isort
         args: ["-l", "120", "--profile", "black"]
 
   - repo: https://github.com/hadialqattan/pycln
-    rev: v2.5.0
+    rev: v2.6.0
     hooks:
       - id: pycln
         args: ["--all"]
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v6.0.0
     hooks:
       - id: check-yaml
       - id: end-of-file-fixer
       - id: trailing-whitespace
 
   - repo: https://github.com/psf/black
-    rev: 23.3.0
+    rev: 26.5.1
     hooks:
       - id: black
         args: ["-l", "120"]
 
   - repo: https://github.com/pycqa/flake8
-    rev: 6.1.0
+    rev: 7.3.0
     hooks:
       - id: flake8
         args: ["--max-line-length", "120"]
         fail_fast: true
 
   - repo: https://github.com/ansible-community/ansible-lint.git
-    rev: v25.8.1
+    rev: v26.8.0
     hooks:
       - id: ansible-lint
         files: \.(yaml|yml)$
 
   - repo: https://github.com/Yelp/detect-secrets
-    rev: v1.4.0
+    rev: v1.5.0
     hooks:
       - id: detect-secrets

README.md

@@ -63,9 +63,14 @@ Support for the following workflows in vManage client and as Ansible modules:
 
 Currently development of the tool was set with:
 
-- Python = 3.10.0
-- Ansible = 2.16.6
-- catalystwan = "^0.33.6post0"
+- Python = 3.12-3.14
+- Ansible = 14.3.1 (ansible-core 2.21.3)
+- catalystwan = 0.41.5.dev2 for the complete high-level API used by the collection
+
+The compatibility CI also imports and validates module documentation with the
+latest stable `catalystwan` SDK (0.41.6). That stable SDK removed several
+high-level APIs; affected modules return a focused dependency error instead of
+making a partial or unsafe change. See [the compatibility policy](docs/COMPATIBILITY.md).
 
 ## Installing this collection
 

ansible.cfg

@@ -1,7 +1,8 @@
 [defaults]
 roles_path = ./roles
 #vault_password_file = /path/to/vault/password/file
-stdout_callback = yaml
+stdout_callback = default
+callback_result_format = yaml
 bin_ansible_callbacks = True
 callbacks_enabled = profile_tasks
 remote_tmp = /tmp/.ansible_remote/tmp

docs/COMPATIBILITY.md

@@ -0,0 +1,42 @@
+# Compatibility policy
+
+## Current targets
+
+| Layer | Tested target | Validation |
+| --- | --- | --- |
+| Python | 3.12, 3.13, 3.14 | CI matrix |
+| Ansible | 14.3.1 / ansible-core 2.21.3 | Unit, collection build, and `ansible-doc` checks |
+| catalystwan SDK | 0.41.5.dev2 | Full module import and SDK contract checks |
+| catalystwan SDK | 0.41.6 | Full module import and documentation checks; removed SDK APIs fail with actionable messages |
+| Cisco Catalyst SD-WAN Manager | 26.1 | SDK version parsing plus opt-in live smoke playbook |
+
+The collection retains `requires_ansible: >=2.16.6` for existing users, while
+the newest automation stack is tested on every change.
+
+## Live Manager validation
+
+Static SDK checks cannot prove that a Manager endpoint behaves identically in a
+new software release. Before declaring a new Manager train fully validated, run:
+
+```bash
+ansible-playbook playbooks/tests/test_manager_release_compatibility.yml \
+  -e @manager_credentials.yml \
+  -e target_manager_release=26.1
+```
+
+`manager_credentials.yml` must define `manager_authentication` with `url`,
+`username`, `password`, and the HTTPS API `port` when it is not 443. The
+playbook reads the installed release and checks API readiness without changing
+Manager state. If the shell also uses `VMANAGE_PORT` for SSH, pass the HTTPS
+port explicitly in `manager_authentication` so the SDK does not inherit the SSH
+port.
+
+## SDK compatibility note
+
+The stable catalystwan 0.41.x package removed high-level implementations used
+by `cluster_management`, `config_groups`, `device_templates_recovery`, and the
+Enterprise Root CA option of `administration_settings`. The collection remains
+fully functional with the latest published legacy API artifact,
+`catalystwan==0.41.5.dev2`, while also keeping all modules importable with
+0.41.6. Operations whose upstream API is absent stop before making a request and
+explain which SDK artifact is required.

galaxy.yml

@@ -1,6 +1,6 @@
 namespace: cisco
 name: catalystwan
-version: 0.3.3
+version: 0.3.4
 readme: README.md
 authors:
   - Arkadiusz Cichon <acichon@cisco.com>
@@ -22,4 +22,11 @@ tags:
   - networking
 
 dependencies: {}
-build_ignore: []
+build_ignore:
+  - .git
+  - .github
+  - .pytest_cache
+  - .venv
+  - "**/__pycache__"
+  - "**/*.pyc"
+  - "*.tar.gz"