Orchestrating Network Infrastructure: A Comprehensive Guide to the vyos.vyos Ansible Collection

The automation of network infrastructure has transitioned from a luxury to a fundamental requirement for modern enterprise environments. Within this ecosystem, VyOS stands as a powerful, open-source network operating system, and the vyos.vyos Ansible collection serves as the primary bridge between declarative configuration management and the VyOS command-line interface. This collection is designed to abstract the complexities of manual network configuration, allowing administrators to treat their network devices as code. By utilizing the Ansible framework, engineers can ensure consistency across multiple appliances, reduce the risk of human error during manual CLI entry, and implement version-controlled infrastructure changes. The collection provides a robust set of modules that range from basic command execution and fact gathering to complex resource management for BGP, OSPF, and VRFs, ensuring that the entire lifecycle of a VyOS appliance—from initial deployment to advanced routing policy updates—can be managed programmatically.

Evolution and Governance of the vyos.vyos Collection

The trajectory of the vyos.vyos collection has undergone a significant shift in governance and development velocity. For a period, the collection experienced a loss of momentum and remained stagnant, which created challenges for users attempting to automate newer versions of the VyOS operating system. This stagnation was resolved when the repositories were officially transferred to the VyOS organization on GitHub.

The transition to official organizational control marked a pivotal change in the maintenance strategy. A dedicated team of maintainers, including contributors such as Gaige Paulsen and Evgeny Molotkov, took over the development process. This move shifted the collection from a community-led effort with varying levels of consistency to an officially supported toolset. The result of this organizational shift was the release of version 6.0.0, which followed over two years of community refinements, bug fixes, and structural improvements.

The impact of this shift is most evident in the support for Long Term Support (LTS) releases. The updated collection provides comprehensive support for the 1.4 LTS release and the forthcoming VyOS 1.5. While the collection maintains support for the 1.3.x series, it is important to note that version 6.0.0 represents the final release to officially support VyOS 1.3.x, as that specific version has reached its end-of-life status. This lifecycle management ensures that users are incentivized to migrate to supported versions of the OS to maintain security and stability.

Technical Specifications and Version Compatibility

The compatibility matrix for the vyos.vyos collection is critical for ensuring that the Ansible control node and the target VyOS devices are synchronized. Discrepancies in versions can lead to syntax errors or failed module executions.

The collection is designed to work with Ansible versions >=2.15.0. The versioning schema follows PEP440, which is the standard for describing Python-based software versions, ensuring a predictable update path for DevOps engineers.

The following table delineates the historical and prospective release path of the collection:

It is essential for practitioners to understand that unreleased versions, such as 7.0.0, are not guaranteed to follow the described path and are subject to change based on community feedback and technical contributions. Furthermore, some individual modules may offer wider compatibility than the overall collection version suggests, depending on how the specific module interacts with the underlying VyOS API or CLI.

Installation and Integration Framework

Integrating the vyos.vyos collection into an automation workflow requires the use of the Ansible Galaxy CLI. This allows the control node to pull the latest audited modules from the Galaxy ecosystem.

The collection can be installed directly using the following command:

ansible-galaxy collection install vyos.vyos

For enterprise environments where reproducibility is paramount, the recommended approach is to use a requirements.yml file. This ensures that all team members and CI/CD pipelines use the exact same version of the collection.

The requirements.yml file should be structured as follows:

```yaml

collections:
- name: vyos.vyos
```

Once the requirements file is created, the installation is executed via:

ansible-galaxy collection install -r requirements.yml

Deep Dive into Module Capabilities

The vyos.vyos collection is composed of a variety of modules, each serving a specific purpose in the network administration lifecycle. These are divided into general utility modules and specialized resource modules.

General Management Modules

These modules provide the foundational tools for interacting with the VyOS CLI and managing basic device states.

• vyos.vyos.vyos: This is used to run commands specifically via the vyos cliconf interface on the VyOS platform.
• vyos.vyos.vyos_command: This module allows the execution of one or more arbitrary commands on the device, which is useful for diagnostic tasks or custom scripts.
• vyos.vyos.vyos_config: Used for managing the general configuration of a remote device.
• vyos.vyos.vyos_facts: This module is critical for the "Gathering Facts" stage of an Ansible playbook, allowing the user to retrieve system-level information about the VyOS device.
• vyos.vyos.vyos_banner: Provides the ability to manage multiline banners, which are often used for legal warnings or identification on login screens.
• vyos.vyos.vyos_user: Manages the local user database on the VyOS device, enabling the automated creation, modification, or removal of administrative accounts.
• vyos.vyos.vyos_system: Specifically designed to run set system commands, allowing for the configuration of global system parameters.

Network Resource Modules

Resource modules are designed to be idempotent, meaning they check the current state of the device and only apply changes if the actual state differs from the desired state. Many of these modules were built using the resource_module_builder, while newer ones utilize the cli_rm_builder. The latter uses a more advanced network parsing engine that standardizes how configuration data is read from and written to the device.

• vyos.vyos.vyosstaticroutes: Manages the static routing table of the device.
• vyos.vyos.vyosbgpglobal: Handles the global configuration settings for the Border Gateway Protocol.
• vyos.vyos.vyosbgpaddress_family: Manages specific BGP address families, allowing for granular control over IPv4 and IPv6 routing.
• vyos.vyos.vyos_ospfv2: Dedicated to the configuration of OSPF version 2 (IPv4).
• vyos.vyos.vyos_ospfv3: Dedicated to the configuration of OSPF version 3 (IPv6).
• vyos.vyos.vyosprefixlists: Manages prefix lists used to filter routing updates.
• vyos.vyos.vyosroutemaps: Handles the creation and modification of route maps for complex policy-based routing.
• vyos.vyos.vyos_vrf: Provides management for Virtual Routing and Forwarding (VRF) instances, allowing for the creation of multiple isolated routing tables.
• vyos.vyos.vyos_vlan: Used to define and manage Virtual Local Area Networks on the device.
• vyos.vyos.vyossnmpserver: Manages the SNMP server configuration for remote monitoring and management.

Connectivity and Testing Modules

• vyos.vyos.vyos_ping: This module allows the Ansible controller to initiate a ping test from the VyOS device to a target destination, which is essential for validating connectivity after a configuration change.

Implementation Logic and FQCN Usage

To avoid naming conflicts with other collections, Ansible utilizes the Fully Qualified Collection Namespace (FQCN). Every module in this collection must be called by its full name, such as vyos.vyos.vyos_static_routes.

The collection supports network_cli connections, which optimize the way Ansible interacts with network devices by maintaining a persistent connection, thereby reducing the overhead of SSH handshakes for every single task.

An example of a task using the FQCN to replace static route configurations is as follows:

```yaml

• name: Replace device configurations of listed static routes with provided configurations
  register: result
  vyos.vyos.vyosstaticroutes:
  config:
  - addressfamilies:
  - afi: ipv4
  routes:
  - dest: 192.0.2.32/28
  blackholeconfig:
  distance: 2
  nexthops:
  - forwardrouteraddress: 192.0.2.7
  - forwardrouteraddress: 192.0.2.8
  - forwardrouter_address: 192.0.2.9
  state: replaced
  ```

In this scenario, the state: replaced parameter is critical. It tells Ansible to ensure that only the specified routes exist on the device, removing any existing static routes that are not defined in the playbook. This provides a "source of truth" model for network configuration.

Advanced Automation Strategies and Community Perspectives

Beyond the standard use of the vyos.vyos collection, the community of network engineers has explored various hybrid automation strategies. Some users have reported difficulties with syntax compatibility between version 1.4 and 1.5, leading them to experiment with alternative methods.

One approach involves the use of templating, where configurations are generated as flat files and pushed to the device. While this is often viewed as clunky, it provides a level of transparency and control that some prefer over the abstraction of Ansible modules. Other users have integrated bash scripts combined with cloud-init for initial provisioning.

In cloud-native environments, the use of Terraform and CloudFormation is common for deploying the underlying VyOS instance, after which Ansible is used for "Day 2" configuration. The integration of cloud-init is highly recommended for the initial bootstrap process, allowing the device to be reachable via SSH and having the necessary users and keys configured before the Ansible collection takes over the management.

Troubleshooting and Operational Notes

When deploying the vyos.vyos collection, users should be aware of specific behavioral nuances regarding interface output. For example, when running show interfaces on eth0, the output is expected to show duplex auto and speed auto. However, other interfaces may not display these default values if they have been repeatedly deleted and recreated, as VyOS hides default values in the CLI output. This can lead to confusion during "fact gathering" or when verifying states via the vyos_command module.

Furthermore, users utilizing Ansible 2.9 may encounter an issue where deprecation warnings are not displayed when running playbooks with this collection. This is a known limitation and does not affect the functional execution of the modules.

The collection is licensed under the GNU General Public License v3.0 or later, ensuring that the software remains open and transparent. Contributions to the collection are encouraged through the VyOS community, and all contributors are expected to adhere to the Ansible project's Code of Conduct.

Conclusion

The vyos.vyos Ansible collection is a sophisticated toolkit that transforms the way VyOS appliances are managed. By moving from manual CLI configuration to a declarative, code-driven approach, organizations can achieve a level of scalability and reliability that was previously unattainable. The transition of the collection to official VyOS organizational control has ensured that the tool evolves in lockstep with the OS, specifically with the 1.4 LTS and the upcoming 1.5 releases.

The depth of the collection—from the implementation of cli_rm_builder for standardized parsing to the exhaustive list of resource modules for BGP and OSPF—provides a complete framework for network automation. While alternative methods like cloud-init or custom bash scripting exist, the use of the official Ansible collection, leveraged via FQCN and network_cli connections, represents the gold standard for VyOS orchestration. The ability to define the network state in YAML and apply it idempotently across a fleet of devices drastically reduces the operational risk and increases the agility of the network infrastructure.

Sources

1. VyOS Ansible Collection GitHub
2. VyOS Blog - Collection 6.0.0 Release
3. VyOS Forum - Automation Discussions