diff options
| -rw-r--r-- | .github/workflows/certification.yml | 53 | ||||
| -rw-r--r-- | .github/workflows/tests.yml | 5 | ||||
| -rw-r--r-- | README.md | 113 | ||||
| -rw-r--r-- | changelogs/fragments/t8989_aap_prereq.yml | 3 | ||||
| -rw-r--r-- | galaxy.yml | 2 | ||||
| -rw-r--r-- | meta/runtime.yml | 14 | ||||
| -rw-r--r-- | requirements.txt | 6 | ||||
| -rw-r--r-- | tox-ansible.ini | 1 |
8 files changed, 134 insertions, 63 deletions
diff --git a/.github/workflows/certification.yml b/.github/workflows/certification.yml new file mode 100644 index 0000000..2fb58dc --- /dev/null +++ b/.github/workflows/certification.yml @@ -0,0 +1,53 @@ +--- +# This workflow calls a pinned version of the +# reusable workflow. Copy this file into your +# repository to check against pinned versions +# of Automation Hub tests. +# The version is pinned to an exact release tag +# (e.g. @v1.2.0) for supply chain security. +# Use Dependabot to receive automatic PRs when +# new versions are released. +name: Run collection certification checks + +permissions: + contents: read + +on: + pull_request: + branches: [main] + workflow_dispatch: + schedule: + - cron: "0 6 * * *" + +concurrency: + # Keyed on the PR number, not head_ref: pull requests from different forks can use the + # same branch name, which would make their runs cancel each other. + group: cert-ver-${{ github.event.pull_request.number || github.run_id }} + cancel-in-progress: true + +# Files that are not related to the core functionality +# of your collection can cause Ansible Lint to fail. +# If this happens, add an .ansible-lint file that includes +# those files and directories to the root of your +# repository; for example: +# https://github.com/ansible-collections/partner-certification-checker/blob/main/.ansible-lint + +# If there are sanity test failures that cannot be fixed and are allowed to ignore +# https://docs.ansible.com/projects/lint/rules/sanity/, create a sanity ignore file +# https://docs.ansible.com/projects/ansible/devel/dev_guide/testing/sanity/ignores.html#ignore-file-location +# for each affected version of ansible-core (for example, `tests/sanity/ignore-2.18.txt`) and add corresponding entries. +jobs: + call: + uses: ansible-collections/partner-certification-checker/.github/workflows/certification-reusable.yml@v6.0.0 # zizmor: ignore[unpinned-uses] + # For details on tested ansible-core branches and Python versions, + # see: https://github.com/ansible-collections/partner-certification-checker#tested-ansible-core-branches-and-python-versions + with: + # ansible-core-version: '2.18.0' + # skip-sanity-versions: 'stable-2.16' + # collection-root: 'ansible_collections/junipernetworks/junos' + collection-deps: 'ansible.netcommon' + # automation-hub: true + # Uncomment the lines below if you have 'automation-hub: true' and need to install collections from Red Hat Ansible Automation Hub. + # This requires setting a repository secret called 'AH_TOKEN' which value contains a Red Hat Ansible Automation Hub token. + # secrets: + # AH_TOKEN: ${{ secrets.AH_TOKEN }} diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index dedbc9e..6086077 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -46,7 +46,8 @@ jobs: set([ '${{ needs.changelog.result }}', '${{ needs.sanity.result }}', - '${{ needs.unit-galaxy.result }}' - '${{ needs.ansible-lint.result }}' + '${{ needs.unit-galaxy.result }}', + '${{ needs.ansible-lint.result }}', + '${{ needs.build-import.result }}', '${{ needs.unit-source.result }}' ])" @@ -5,10 +5,12 @@ as an alternative to the SSH/CLI-based `vyos.vyos` collection. ## Requirements -- VyOS 1.3 or later -- Ansible >= 2.15.0 -- `ansible.netcommon` >= 2.5.1 -- `ansible.utils` +- ansible-core >=2.16.0, see [Ansible version compatibility](#ansible-version-compatibility). +- Python >=3.10 on the Ansible controller, as required by ansible-core 2.16. +- [ansible.netcommon](https://galaxy.ansible.com/ui/repo/published/ansible/netcommon/) >=2.5.1, installed automatically as a dependency of this collection. +- `ansible.utils`, installed automatically as a dependency of `ansible.netcommon`. +- VyOS 1.3 or later with the REST API enabled and reachable over HTTPS with the `ansible.netcommon.httpapi` connection. +- No additional Python packages are required by the collection's code. ## Configuring VyOS for REST API access @@ -56,64 +58,77 @@ all: ## Installation -```bash -ansible-galaxy collection install vyos.rest -``` +You can install the collection with the Ansible Galaxy CLI: + + ansible-galaxy collection install vyos.rest + +This collection is distributed through Ansible Galaxy and is not yet available from Red Hat Ansible Automation Hub. +Red Hat does not support installing collections from GitHub. +<!-- TODO: once the collection is published on Automation Hub, add its installation link and the "Configuring Ansible Automation Hub" reference --> + +To install a specific version, for example 1.0.0: + + ansible-galaxy collection install vyos.rest:==1.0.0 + +To upgrade to the latest version: -Or from source: + ansible-galaxy collection install vyos.rest --upgrade -```bash -git clone https://github.com/vyos/vyos.rest.git -ansible-galaxy collection install vyos.rest/ --force +You can also include it in a `requirements.yml` file and install it with `ansible-galaxy collection install -r requirements.yml`, using the format: + +```yaml +--- +collections: + - name: vyos.rest ``` <!--start collection content--> ### Httpapi plugins Name | Description --- | --- -[vyos.rest.vyos](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_httpapi.rst)|VyOS REST API +[vyos.rest.vyos](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_httpapi.rst)|HttpApi plugin for VyOS REST API ### Modules Name | Description --- | --- -[vyos.rest.vyos_banner](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_banner_module.rst)|Manage multiline banners on VyOS devices via REST API. -[vyos.rest.vyos_bgp_address_family](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_bgp_address_family_module.rst)|Manage BGP address-family configuration on VyOS devices using REST API -[vyos.rest.vyos_bgp_global](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_bgp_global_module.rst)|Manage BGP global configuration on VyOS devices using REST API -[vyos.rest.vyos_command](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_command_module.rst)|Run show commands on VyOS devices using REST API -[vyos.rest.vyos_config](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_config_module.rst)|Manage VyOS configuration using REST API -[vyos.rest.vyos_configure](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_configure_module.rst)|Send raw set/delete commands to a VyOS device via REST API. -[vyos.rest.vyos_facts](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_facts_module.rst)|Get facts about VyOS devices using REST API -[vyos.rest.vyos_firewall_global](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_firewall_global_module.rst)|Manage global firewall configuration on VyOS devices using REST API -[vyos.rest.vyos_firewall_interfaces](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_firewall_interfaces_module.rst)|Manage firewall hook filters on VyOS devices using REST API -[vyos.rest.vyos_firewall_rules](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_firewall_rules_module.rst)|Manage firewall rule sets on VyOS devices using REST API -[vyos.rest.vyos_ha](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_ha_module.rst)|Manage VRRP and load balancer configuration on VyOS via REST API -[vyos.rest.vyos_hostname](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_hostname_module.rst)|Manage the system hostname on a VyOS device via the REST API. -[vyos.rest.vyos_interfaces](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_interfaces_module.rst)|Manage interface configuration on VyOS devices via REST API. -[vyos.rest.vyos_l3_interfaces](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_l3_interfaces_module.rst)|Manage L3 interface configuration on VyOS devices via REST API. -[vyos.rest.vyos_lag_interfaces](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_lag_interfaces_module.rst)|Manage LAG interface configuration on VyOS devices via REST API. -[vyos.rest.vyos_lldp_global](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_lldp_global_module.rst)|Manage LLDP global configuration on VyOS via REST API. -[vyos.rest.vyos_lldp_interfaces](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_lldp_interfaces_module.rst)|Manage LLDP interface configuration on VyOS devices via REST API. -[vyos.rest.vyos_logging_global](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_logging_global_module.rst)|Manage syslog configuration on VyOS devices using REST API -[vyos.rest.vyos_nat](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_nat_module.rst)|Manage NAT configuration on VyOS devices using REST API -[vyos.rest.vyos_ntp_global](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_ntp_global_module.rst)|Manage NTP configuration on VyOS devices using REST API -[vyos.rest.vyos_ospf_interfaces](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_ospf_interfaces_module.rst)|Manage OSPF interface configuration on VyOS devices using REST API -[vyos.rest.vyos_ospfv2](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_ospfv2_module.rst)|Manage OSPFv2 configuration on VyOS devices using REST API -[vyos.rest.vyos_ospfv3](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_ospfv3_module.rst)|Manage OSPFv3 configuration on VyOS devices using REST API -[vyos.rest.vyos_prefix_lists](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_prefix_lists_module.rst)|Manage prefix-list configuration on VyOS devices using REST API -[vyos.rest.vyos_route_maps](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_route_maps_module.rst)|Manage route-map configuration on VyOS devices using REST API -[vyos.rest.vyos_snmp_server](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_snmp_server_module.rst)|Manage SNMP server configuration on VyOS devices using REST API -[vyos.rest.vyos_static_routes](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_static_routes_module.rst)|Manage static routes on VyOS devices via REST API. -[vyos.rest.vyos_system](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_system_module.rst)|Manage system settings on VyOS devices using REST API -[vyos.rest.vyos_user](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_user_module.rst)|Manage user accounts on VyOS devices using REST API -[vyos.rest.vyos_vlan](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_vlan_module.rst)|Manage VLAN (vif) configuration on VyOS devices using REST API -[vyos.rest.vyos_vrf](https://github.com/vyos/vyos.rest/blob/main/docs/vyos.rest.vyos_vrf_module.rst)|Manage VRF configuration on VyOS devices using REST API +[vyos.rest.vyos_banner](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_banner_module.rst)|Manage multiline banners on VyOS devices via REST API. +[vyos.rest.vyos_bgp_address_family](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_bgp_address_family_module.rst)|Manage BGP address-family configuration on VyOS devices using REST API +[vyos.rest.vyos_bgp_global](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_bgp_global_module.rst)|Manage BGP global configuration on VyOS devices using REST API +[vyos.rest.vyos_command](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_command_module.rst)|Run show commands on VyOS devices using REST API +[vyos.rest.vyos_config](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_config_module.rst)|Manage VyOS configuration using REST API +[vyos.rest.vyos_configure](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_configure_module.rst)|Send raw set/delete commands to a VyOS device via REST API. +[vyos.rest.vyos_facts](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_facts_module.rst)|Get facts about VyOS devices using REST API +[vyos.rest.vyos_firewall_global](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_firewall_global_module.rst)|Manage global firewall configuration on VyOS devices using REST API +[vyos.rest.vyos_firewall_interfaces](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_firewall_interfaces_module.rst)|Manage firewall hook filters on VyOS devices using REST API +[vyos.rest.vyos_firewall_rules](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_firewall_rules_module.rst)|Manage firewall rule sets on VyOS devices using REST API +[vyos.rest.vyos_ha](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_ha_module.rst)|Manage VRRP and load balancer configuration on VyOS via REST API +[vyos.rest.vyos_hostname](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_hostname_module.rst)|Manage the system hostname on a VyOS device via the REST API. +[vyos.rest.vyos_interfaces](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_interfaces_module.rst)|Manage interface configuration on VyOS devices via REST API. +[vyos.rest.vyos_l3_interfaces](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_l3_interfaces_module.rst)|Manage L3 interface configuration on VyOS devices via REST API. +[vyos.rest.vyos_lag_interfaces](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_lag_interfaces_module.rst)|Manage LAG interface configuration on VyOS devices via REST API. +[vyos.rest.vyos_lldp_global](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_lldp_global_module.rst)|Manage LLDP global configuration on VyOS via REST API. +[vyos.rest.vyos_lldp_interfaces](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_lldp_interfaces_module.rst)|Manage LLDP interface configuration on VyOS devices via REST API. +[vyos.rest.vyos_logging_global](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_logging_global_module.rst)|Manage syslog configuration on VyOS devices using REST API +[vyos.rest.vyos_nat](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_nat_module.rst)|Manage NAT configuration on VyOS devices using REST API +[vyos.rest.vyos_ntp_global](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_ntp_global_module.rst)|Manage NTP configuration on VyOS devices using REST API +[vyos.rest.vyos_ospf_interfaces](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_ospf_interfaces_module.rst)|Manage OSPF interface configuration on VyOS devices using REST API +[vyos.rest.vyos_ospfv2](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_ospfv2_module.rst)|Manage OSPFv2 configuration on VyOS devices using REST API +[vyos.rest.vyos_ospfv3](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_ospfv3_module.rst)|Manage OSPFv3 configuration on VyOS devices using REST API +[vyos.rest.vyos_prefix_lists](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_prefix_lists_module.rst)|Manage prefix-list configuration on VyOS devices using REST API +[vyos.rest.vyos_route_maps](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_route_maps_module.rst)|Manage route-map configuration on VyOS devices using REST API +[vyos.rest.vyos_snmp_server](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_snmp_server_module.rst)|Manage SNMP server configuration on VyOS devices using REST API +[vyos.rest.vyos_static_routes](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_static_routes_module.rst)|Manage static routes on VyOS devices via REST API. +[vyos.rest.vyos_system](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_system_module.rst)|Manage system settings on VyOS devices using REST API +[vyos.rest.vyos_user](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_user_module.rst)|Manage user accounts on VyOS devices using REST API +[vyos.rest.vyos_vlan](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_vlan_module.rst)|Manage VLAN (vif) configuration on VyOS devices using REST API +[vyos.rest.vyos_vrf](https://github.com/vyos/rest.vyos/blob/main/docs/vyos.rest.vyos_vrf_module.rst)|Manage VRF configuration on VyOS devices using REST API <!--end collection content--> <!--start requires_ansible--> ## Ansible version compatibility -This collection has been tested against the following Ansible versions: **>=2.15.0**. +This collection has been tested against the following Ansible versions: **>=2.16.0**. Plugins and modules within a collection may be tested with only specific Ansible versions. A collection may contain metadata that identifies these versions. @@ -134,3 +149,13 @@ automation. | Connection plugin | `ansible.netcommon.network_cli` | `ansible.netcommon.httpapi` | | VyOS requirement | Any | VyOS 1.3+ with REST API enabled | | Atomic commits | Per-command | Batch (single commit) | + +## Support + +The collection is maintained by the VyOS team. <!-- TODO: VyOS commercial support statement/link --> +Community help is available through [GitHub issues](https://github.com/vyos/rest.vyos/issues), the [VyOS forum](https://forum.vyos.io/) +and the [Ansible Forum](https://forum.ansible.com/). + +Once this collection is certified and available on Red Hat Ansible Automation Hub, Red Hat customers can open support cases +through Ansible Automation Platform (AAP) using the **Create issue** button on the collection page in Automation Hub. +<!-- TODO: when certified, replace the paragraph above with the standard support text from Red Hat's README template --> diff --git a/changelogs/fragments/t8989_aap_prereq.yml b/changelogs/fragments/t8989_aap_prereq.yml new file mode 100644 index 0000000..ef7a90d --- /dev/null +++ b/changelogs/fragments/t8989_aap_prereq.yml @@ -0,0 +1,3 @@ +--- +minor_changes: + - Added / Modified the items to meet AAP requirements. @@ -8,7 +8,7 @@ name: rest description: Ansible Network Collection for REST-enabled VYOS devices. namespace: vyos readme: README.md -repository: https://github.com/vyos/vyos.rest +repository: https://github.com/vyos/rest.vyos issues: https://vyos.dev tags: [vyos, networking] version: 1.0.0 diff --git a/meta/runtime.yml b/meta/runtime.yml index 04ed2da..1db0f16 100644 --- a/meta/runtime.yml +++ b/meta/runtime.yml @@ -1,17 +1,5 @@ --- -requires_ansible: ">=2.15.0" - -# action_groups allow users to set shared connection params once using -# module_defaults: -# -# - hosts: vyos_devices -# module_defaults: -# group/vyos.rest.api: -# api_key: "{{ vyos_api_key }}" -# verify_ssl: false -# -# This sets hostname/api_key/port/verify_ssl/timeout for ALL modules in -# the group without repeating them on every task. +requires_ansible: ">=2.16.0" action_groups: api: - vyos_banner diff --git a/requirements.txt b/requirements.txt index ee91c10..ea07c16 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,2 +1,4 @@ -paramiko -scp +# This collection needs no Python packages beyond ansible-core and the +# collections declared in galaxy.yml. paramiko and scp belong to the SSH-based +# vyos.vyos collection, not to this REST-based one. urllib3 is used when it is +# installed (to silence insecure-request warnings) but is optional. diff --git a/tox-ansible.ini b/tox-ansible.ini index 030a3b0..5d3c8dd 100644 --- a/tox-ansible.ini +++ b/tox-ansible.ini @@ -1,5 +1,4 @@ [ansible] skip = - py3.12 py3.13 py3.14 |