Fix/roles docs

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

@@ -1,4 +1,3 @@
-# .github/workflows/ansible-doc-validation.yml
 name: Ansible Doc Validation
 
 on:

.github/workflows/galaxy-importer.yml

@@ -1,5 +1,3 @@
-# .github/workflows/galaxy-importer.yml
-
 # Its role is to performe the same checks that would be performed when publishing to galaxy
 # Running them earlier helps to detect issues locally
 

.github/workflows/linters.yml

@@ -1,4 +1,3 @@
-# .github/workflows/ansible-lint.yml
 name: Static Code Analyzer
 
 on:

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

@@ -1,5 +1,3 @@
-# .github/workflows/galaxy-importer.yml
-
 name: Release to ansible-galaxy from tag
 
 on:

galaxy.yml

@@ -1,13 +1,13 @@
 namespace: cisco
 name: catalystwan
-version: 0.1.0
+version: 0.1.1
 readme: README.md
 authors:
   - Arkadiusz Cichon <[email protected]>
   - Kamil Górski <[email protected]>
 description: Ansible collection to interact with Cisco SD-WAN vManage via catalystwan
 
-repository: git@github.com:cisco-open/ansible-collection-catalystwan.git
+repository: https://github.com/cisco-open/ansible-collection-catalystwan
 documentation: https://github.com/cisco-open/ansible-collection-catalystwan/blob/main/README.md
 homepage: https://github.com/cisco-open/ansible-collection-catalystwan
 issues: https://github.com/cisco-open/ansible-collection-catalystwan/issues

meta/runtime.yml

@@ -1,5 +1,3 @@
 ---
 
-# Collections must specify a minimum required ansible version to upload
-# to galaxy
-requires_ansible: '>=2.13.13'
+requires_ansible: '>=2.16.6'

plugins/modules/administration_settings.py

@@ -21,7 +21,7 @@
     description: Configuration for controller certificate authorization.
     type: dict
     aliases: [cca, controller_certificate_authorization]
-    options:
+    suboptions:
       certificate_signing:
         description: Defines the certificate signing authority.
         type: str
@@ -60,7 +60,7 @@
     description: Smart Account credentials for authentication.
     type: dict
     aliases: [smart_account]
-    options:
+    suboptions:
       password:
         description: Password for Smart Account.
         type: str
@@ -74,7 +74,7 @@
     description: Configuration for vBond validator.
     type: dict
     aliases: [vbond]
-    options:
+    suboptions:
       domain_ip:
         description: Domain IP of the vBond validator.
         type: str
@@ -84,7 +84,7 @@
   software_install_timeout:
     description: Configuration for upgrades timeout.
     type: dict
-    options:
+    suboptions:
       download_timeout:
         description: Download Timeout in minutes, should be in range 60-360.
         type: int

roles/activate_edges/README.md

@@ -1 +1,59 @@
----
+# Ansible Role: activate_edges
+
+This Ansible role is designed to manage the activation process of Cisco Catalyst WAN Edge devices.
+NOTE: Role must be used on localhost - API requests to Manager are done from local machine.
+
+## Role Description
+
+The `activate_edges` role ensure that Edge devices are properly synchronized and activated in the network.
+It includes:
+
+- verifying variables
+- retrieving the list of Edge devices
+- syncing them with controllers
+- waiting until the devices are reachable and have completed the OTP (One-Time Password) phase
+- ensuring that certificates are installed, and the devices are reachable
+
+## Requirements
+
+- `cisco.catalystwan` collection installed.
+- Access details for the Cisco Manager instance must be provided.
+
+## Dependencies
+
+There are no external role dependencies. Only `cisco.catalystwan` collection is required.
+
+## Role Variables
+
+Variables expected by this role, example:
+
+```yaml
+vmanage_instances:
+  - mgmt_public_ip: '192.0.2.1'
+    admin_username: 'admin'
+    admin_password: 'password'
+```
+
+## Example Playbook
+
+Including an example of how to use your role (for instance, with variables passed in as parameters):
+
+```yaml
+- hosts: localhost
+  gather_facts: no
+  roles:
+    - role: cisco.catalystwan.activate_edges
+      vars:
+        vmanage_instances:
+          - mgmt_public_ip: '192.0.2.1'
+            admin_username: 'admin'
+            admin_password: 'password'
+```
+
+## License
+
+"GPL-3.0-only"
+
+## Author Information
+
+This role was created by Arkadiusz Cichon <[email protected]>

roles/administration_settings/README.md

@@ -1 +1,74 @@
----
+# Ansible Role: administration_settings
+
+This Ansible role is designed to manage the initial configuration of Cisco Manager devices and administration settings.
+NOTE: Role must be used on localhost - API requests to Manager are done from local machine.
+
+## Role Description
+
+Key tasks:
+
+- inform the user to manually verify that their PnP Portal Controller Profile is up to date with the vBond and organization name, pausing execution until the user confirms
+- verifying variables
+- setting iinitial configuration via administration settings
+
+## Requirements
+
+- `cisco.catalystwan` collection installed.
+- Access details for the Cisco Manager instance must be provided.
+
+## Dependencies
+
+There are no external role dependencies. Only `cisco.catalystwan` collection is required.
+
+## Role Variables
+
+Variables expected by this role:
+
+- `vbond_transport_public_ip`: The public IP of the vBond transport.
+- `organization_name`: The name of the organization.
+- `validator_port`: The port used by the validator.
+- `pnp_username`: The username for the PnP service account.
+- `pnp_password`: The password for the PnP service account.
+- `vmanage_instances`: A list of vManage instances, each containing management IP, admin username, and admin password.
+
+Example of `vmanage_instances`:
+
+```yaml
+vmanage_instances:
+  - hostname: 'vmanage01'
+    system_ip: '192.0.2.10'
+    mgmt_public_ip: '198.51.100.10'
+    admin_username: 'admin'
+    admin_password: 'password'
+```
+
+## Example Playbook
+
+Including an example of how to use your role (with variables passed in as parameters):
+
+```yaml
+- hosts: localhost
+  gather_facts: no
+  roles:
+    - role: cisco.catalystwan.activate_edges
+      vars:
+        vbond_transport_public_ip: '203.0.113.100'
+        organization_name: 'MyOrganization'
+        validator_port: '12345'
+        pnp_username: 'pnp_user'
+        pnp_password: 'pnp_pass'
+        vmanage_instances:
+          - hostname: 'vmanage01'
+            system_ip: '192.0.2.10'
+            mgmt_public_ip: '198.51.100.10'
+            admin_username: 'admin'
+            admin_password: 'password'
+```
+
+## License
+
+"GPL-3.0-only"
+
+## Author Information
+
+This role was created by Arkadiusz Cichon <[email protected]>

roles/administration_settings/defaults/main.yml

@@ -0,0 +1,3 @@
+---
+
+validator_port: "12346"

roles/administration_settings/tasks/main.yml

@@ -24,12 +24,12 @@
   cisco.catalystwan.administration_settings:
     validator:
       domain_ip: "{{ vbond_transport_public_ip }}"
-      port: "12346"  # should be customizable
+      port: "{{ validator_port }}"
     organization: "{{ organization_name }}"
     certificates:
       retrieve_interval: "2"
     pnp_connect_sync: "on"
-    smart_account_credentials:  # GET the info about how Shivram's config failed because of the missing PnP controller profile
+    smart_account_credentials:
       username: "{{ pnp_username }}"
       password: "{{ pnp_password }}"
     manager_authentication:

roles/administration_settings/tasks/variables_assertion.yml

@@ -19,7 +19,7 @@
     - "{{ vmanage_instances }}"
     - "{{ vbond_instances }}"
     - "{{ organization_name }}"
-    - "{{ vbond_instances[0].transport_public_ip }}"
+    - "{{ (vbond_instances | first).transport_public_ip }}"
   loop_control:
     loop_var: required_var
 

roles/api_ready/README.md

@@ -1 +1,55 @@
----
+# Ansible Role: api_ready
+
+This Ansible role is designed to verify Manager API server readiness.
+NOTE: Role must be used on localhost - API requests to Manager are done from local machine.
+
+## Role Description
+
+Key tasks:
+
+- verifying variables
+- check that API server is ready
+
+## Requirements
+
+- `cisco.catalystwan` collection installed.
+- Access details for the Cisco Manager instance must be provided.
+
+## Dependencies
+
+There are no external role dependencies. Only `cisco.catalystwan` collection is required.
+
+## Role Variables
+
+Example of `vmanage_instances`:
+
+```yaml
+vmanage_instances:
+    - mgmt_public_ip: '198.51.100.10'
+      admin_username: 'admin'
+      admin_password: 'password'
+```
+
+## Example Playbook
+
+Including an example of how to use your role (with variables passed in as parameters):
+
+```yaml
+- hosts: localhost
+  gather_facts: no
+  roles:
+    - role: cisco.catalystwan.api_ready
+      vars:
+        vmanage_instances:
+          - mgmt_public_ip: '198.51.100.10'
+            admin_username: 'admin'
+            admin_password: 'password'
+```
+
+## License
+
+"GPL-3.0-only"
+
+## Author Information
+
+This role was created by Arkadiusz Cichon <[email protected]>

roles/health_checks/README.md

@@ -1 +1,62 @@
----
+# Ansible Role: health_checks
+
+This Ansible role performs health checks on Cisco vManage devices.
+
+## Role Description
+
+The `health_checks` role runs a series of health checks to ensure that the Cisco SD-WAN environment is operating as expected. It checks the state of various connections and sessions to validate their status:
+
+- control connections
+- orchestrator connections
+- BFD sessions
+- OMP sessions
+
+## Requirements
+
+- `cisco.catalystwan` collection installed.
+- Access details for the Cisco Manager instance must be provided.
+
+## Dependencies
+
+There are no external role dependencies. Only `cisco.catalystwan` collection is required.
+
+## Role Variables
+
+Variables expected by this role:
+
+- `vmanage_instances`: List of vManage instances containing management IP, admin username, and admin password.
+
+Example:
+
+```yaml
+vmanage_instances:
+  - mgmt_public_ip: '192.0.2.1'
+    admin_username: 'admin'
+    admin_password: 'password'
+```
+
+## Example Playbook
+
+Including an example of how to use your role (for instance, with variables passed in as parameters):
+
+```yaml
+- hosts: localhost
+  gather_facts: no
+  tasks:
+    - name: Run health_checks
+      import_role:
+        name: health_checks
+      vars:
+        vmanage_instances:
+          - mgmt_public_ip: '192.0.2.1'
+            admin_username: 'admin'
+            admin_password: 'password'
+```
+
+## License
+
+"GPL-3.0-only"
+
+## Author Information
+
+This role was created by Arkadiusz Cichon <[email protected]>