vyos.rest

Ansible collection for managing VyOS network devices via the HTTPS REST API, as an alternative to the SSH/CLI-based vyos.vyos collection.

Requirements

• ansible-core >=2.16.0, see Ansible version compatibility.
• Python >=3.10 on the Ansible controller, as required by ansible-core 2.16.
• 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

Before using this collection, enable the REST API on each VyOS device:

set service https api keys id ansible key YOUR_SECRET_KEY
set service https api rest
commit
save

Note: Choose a strong random key. The key is sent with every API request and acts as the authentication credential.

Inventory configuration

Add the following variables to your inventory for each VyOS host:

[vyos]
vyos-router-01 ansible_host=192.168.1.1

[vyos:vars]
ansible_connection=ansible.netcommon.httpapi
ansible_network_os=vyos.rest.vyos
ansible_httpapi_use_ssl=true
ansible_httpapi_validate_certs=false
ansible_httpapi_api_key=YOUR_SECRET_KEY

Or in YAML format:

all:
  hosts:
    vyos-router-01:
      ansible_host: 192.168.1.1
      ansible_connection: ansible.netcommon.httpapi
      ansible_network_os: vyos.rest.vyos
      ansible_httpapi_use_ssl: true
      ansible_httpapi_validate_certs: false
      ansible_httpapi_api_key: YOUR_SECRET_KEY

Installation

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.

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:

ansible-galaxy collection install vyos.rest --upgrade

You can also include it in a requirements.yml file and install it with ansible-galaxy collection install -r requirements.yml, using the format:

---
collections:
  - name: vyos.rest

Httpapi plugins

Name	Description
vyos.rest.vyos	HttpApi plugin for VyOS REST API

Modules

Name	Description
vyos.rest.vyos_banner	Manage multiline banners on VyOS devices via REST API.
vyos.rest.vyos_bgp_address_family	Manage BGP address-family configuration on VyOS devices using REST API
vyos.rest.vyos_bgp_global	Manage BGP global configuration on VyOS devices using REST API
vyos.rest.vyos_command	Run show commands on VyOS devices using REST API
vyos.rest.vyos_config	Manage VyOS configuration using REST API
vyos.rest.vyos_configure	Send raw set/delete commands to a VyOS device via REST API.
vyos.rest.vyos_facts	Get facts about VyOS devices using REST API
vyos.rest.vyos_firewall_global	Manage global firewall configuration on VyOS devices using REST API
vyos.rest.vyos_firewall_interfaces	Manage firewall hook filters on VyOS devices using REST API
vyos.rest.vyos_firewall_rules	Manage firewall rule sets on VyOS devices using REST API
vyos.rest.vyos_ha	Manage VRRP and load balancer configuration on VyOS via REST API
vyos.rest.vyos_hostname	Manage the system hostname on a VyOS device via the REST API.
vyos.rest.vyos_interfaces	Manage interface configuration on VyOS devices via REST API.
vyos.rest.vyos_l3_interfaces	Manage L3 interface configuration on VyOS devices via REST API.
vyos.rest.vyos_lag_interfaces	Manage LAG interface configuration on VyOS devices via REST API.
vyos.rest.vyos_lldp_global	Manage LLDP global configuration on VyOS via REST API.
vyos.rest.vyos_lldp_interfaces	Manage LLDP interface configuration on VyOS devices via REST API.
vyos.rest.vyos_logging_global	Manage syslog configuration on VyOS devices using REST API
vyos.rest.vyos_nat	Manage NAT configuration on VyOS devices using REST API
vyos.rest.vyos_ntp_global	Manage NTP configuration on VyOS devices using REST API
vyos.rest.vyos_ospf_interfaces	Manage OSPF interface configuration on VyOS devices using REST API
vyos.rest.vyos_ospfv2	Manage OSPFv2 configuration on VyOS devices using REST API
vyos.rest.vyos_ospfv3	Manage OSPFv3 configuration on VyOS devices using REST API
vyos.rest.vyos_prefix_lists	Manage prefix-list configuration on VyOS devices using REST API
vyos.rest.vyos_route_maps	Manage route-map configuration on VyOS devices using REST API
vyos.rest.vyos_snmp_server	Manage SNMP server configuration on VyOS devices using REST API
vyos.rest.vyos_static_routes	Manage static routes on VyOS devices via REST API.
vyos.rest.vyos_system	Manage system settings on VyOS devices using REST API
vyos.rest.vyos_user	Manage user accounts on VyOS devices using REST API
vyos.rest.vyos_vlan	Manage VLAN (vif) configuration on VyOS devices using REST API
vyos.rest.vyos_vrf	Manage VRF configuration on VyOS devices using REST API

Ansible version compatibility

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. PEP440 is the schema used to describe the versions of Ansible.

Relation to vyos.vyos

This collection mirrors the module interface of the vyos.vyos collection but communicates over HTTPS REST instead of SSH/network_cli. It is suitable for environments where SSH access is restricted or where the REST API is preferred for automation.

Feature	vyos.vyos	vyos.rest
Transport	SSH / network_cli	HTTPS REST
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. Community help is available through GitHub issues, the VyOS forum and the Ansible Forum.

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.