The intersection of open-source network operating systems and declarative infrastructure-as-code tools has created a robust framework for modern network automation. The Ansible VyOS collection stands as a critical bridge between the operational flexibility of Debian-based networking and the configuration management rigor of Ansible. This ecosystem empowers administrators to standardize deployments across bare metal servers, virtual machines, and cloud instances. The collection provides a comprehensive suite of modules designed specifically for the commit-based configuration model inherent to VyOS. This model, which mirrors JunOS workflows, requires changes to be staged before they are applied. The Ansible collection abstracts this complexity, allowing for atomic configuration updates, fact gathering, and remote command execution. The maturation of this toolset is marked by the release of version 6.0.0, which signifies a pivotal moment in the project's lifecycle following a period of stagnation. This release represents a formal transfer of development responsibilities to the VyOS organization, ensuring sustained support for current Long-Term Support (LTS) releases and rolling updates. For network engineers, the integration offers a path to eliminate manual configuration errors, enforce policy compliance, and accelerate deployment cycles in both production and laboratory environments.

The Genesis of the 6.0.0 Release and Organizational Transition

The release of the VyOS Ansible Collection 6.0.0 marks a significant milestone in the tool's development history. For a considerable period, the collection experienced a loss of momentum, resulting in a stagnation of features and compatibility updates. This period of inactivity necessitated a structural shift. The repositories were transferred to the official VyOS organization on GitHub. This transfer facilitated the formation of a dedicated maintenance team responsible for revitalizing the project. The revitalization effort was driven by key contributors who assumed stewardship of the codebase. Gaige Paulsen and Evgeny Molotkov joined the effort, undertaking the substantial work required to update the collection. Their contributions ensured that the new release aligns with the operational requirements of modern network infrastructure.

The 6.0.0 release introduces proper support for the current VyOS 1.4 LTS release and the upcoming VyOS 1.5 rolling updates. This versioning strategy reflects the rapid evolution of the underlying operating system. However, the release also serves as a final notification regarding legacy support. VyOS 1.3.x has reached its end of life within the current year. The 6.0.0 collection will be the last release to officially support the 1.3.x series. This creates a hard deadline for administrators still operating on legacy versions, compelling a migration to 1.4 or 1.5 to maintain automation compatibility. The transition underscores the necessity of keeping network operating systems current to leverage automation benefits.

Technical Prerequisites and Collection Installation

Implementing the VyOS Ansible collection requires specific preparatory steps to ensure successful communication with network appliances. The installation process utilizes the Ansible Galaxy package manager to retrieve the collection and its dependencies. The ansible-galaxy command serves as the primary mechanism for acquiring the necessary codebases. The collection relies heavily on the ansible.netcommon library, which provides the foundational networking primitives required for SSH-based management.

The installation procedure involves executing specific terminal commands to populate the local Ansible environment with the required resources. The administrator must first install the VyOS-specific collection. This action downloads the modules, connection plugins, and configuration handlers tailored for the VyOS platform. Subsequently, the ansible.netcommon collection must be installed to enable the network_cli connection type. This connection type is essential for establishing secure shell sessions with VyOS devices. The collection supports network_cli connections, allowing Ansible to interact with the device's command-line interface over SSH.

bash ansible-galaxy collection install vyos.vyos ansible-galaxy collection install ansible.netcommon

These commands ensure that the automation framework possesses the necessary components to parse VyOS configurations and execute remote commands. The successful installation of these collections is a prerequisite for any subsequent automation tasks, including BGP configuration, banner management, and fact gathering.

Inventory Architecture and Connection Protocols

Effective automation requires a structured inventory to define the target network infrastructure. The inventory file maps hostnames to IP addresses and assigns devices to logical groups. This grouping facilitates targeted playbook execution across specific segments of the network. The inventory structure typically separates routers from firewalls, allowing for role-based configuration management. The inventory defines connection parameters, including the network operating system identifier, connection method, and authentication credentials.

The configuration variables within the inventory dictate how Ansible interacts with the VyOS devices. The variable ansible_network_os=vyos.vyos.vyos identifies the operating system type, triggering the appropriate module loading. The variable ansible_connection=ansible.netcommon.network_cli enforces the SSH-based connection protocol. Authentication is handled via the ansible_user variable, which specifies the SSH username. Passwords are managed securely using Ansible Vault references, ensuring sensitive credentials are not exposed in plaintext within the inventory file. VyOS devices utilize SSH for management and do not require an enable password, simplifying the authentication flow compared to traditional enterprise routers.

```ini

inventory/vyos-devices.ini

VyOS device inventory

[vyosrouters]
vyos-edge-01 ansiblehost=10.0.0.1
vyos-edge-02 ansiblehost=10.0.0.2
[vyosfirewalls]
vyos-fw-01 ansiblehost=10.0.0.10
vyos-fw-02 ansiblehost=10.0.0.11
[vyos:children]
vyosrouters
vyosfirewalls
[vyos:vars]
ansiblenetworkos=vyos.vyos.vyos
ansibleconnection=ansible.netcommon.networkcli
ansibleuser=vyos
ansiblepassword={{ vaultvyospassword }}
```

This inventory structure demonstrates how logical grouping enables scalable automation. By defining children groups and variables, administrators can apply configurations to entire network segments simultaneously. The use of vault variables ensures that security best practices are maintained during automated deployments.

Comprehensive Module Analysis

The VyOS Ansible collection provides a diverse array of modules designed to manage specific aspects of the network operating system. Each module addresses a distinct operational requirement, ranging from basic command execution to complex protocol configuration. The collection includes modules for managing banners, configuring BGP address families, handling global BGP settings, executing raw commands, managing the device configuration, and gathering system facts.

The modules are organized under the vyos.vyos namespace, ensuring clear identification and preventing conflicts with other collections. The vyos.vyos.vyos module utilizes the vyos cliconf plugin to execute commands on the VyOS platform. This plugin is the core mechanism for interacting with the device's configuration interface. The vyos_banner module allows administrators to manage multiline banners displayed during login, which is critical for security warnings and access control messaging. The BGP-related modules, vyos_bgp_address_family and vyos_bgp_global, provide resource-specific management for Border Gateway Protocol configurations. These modules enable declarative management of routing protocols, allowing for the creation and modification of BGP settings without manual CLI interaction.

The vyos_command module facilitates the execution of one or more commands on VyOS devices. This is particularly useful for operational tasks, diagnostics, and one-off queries. The vyos_config module handles the management of the VyOS configuration on the remote device. This module is central to the automation workflow, as it manages the commit-based configuration process. The vyos_facts module retrieves system and configuration facts, providing visibility into the device's state, including hostname, version, model, and interface details.

Configuration Workflow and Data Persistence

The configuration model of VyOS is fundamentally different from traditional Cisco IOS workflows. Like JunOS, VyOS employs a commit-based system where changes are staged before they are applied to the running configuration. The vyos_config module automates this workflow by handling the commit process automatically after each task. This ensures that the automation framework respects the atomicity of configuration changes. For optimal performance and consistency, related configuration changes should be grouped within a single task to ensure they are committed together. This approach prevents partial application of configurations, which could lead to network instability.

Data persistence is a critical consideration in the commit-based model. Changes that are committed to the running configuration are not automatically saved to the startup configuration. To prevent data loss during a reboot, administrators must explicitly invoke the save operation. The save: yes parameter within the vyos_config module ensures that the staged changes are written to the non-volatile storage. Without this explicit save operation, all configuration modifications are discarded upon a system restart. This requirement imposes a strict discipline on automation scripts to guarantee durability.

```yaml

Example of save operation within vyos_config

vyos.vyos.vyos_config:
save: yes
```

The commit and save workflow requires careful handling in automation playbooks. Grouping related changes into a single task leverages the atomicity of the system, ensuring that the network state remains consistent. This behavior is a defining characteristic of the VyOS operating system and is fully supported by the Ansible collection.

Advanced System Access and Troubleshooting

VyOS operates on a Debian Linux base, providing access to the underlying operating system for advanced diagnostic purposes. While the primary configuration is managed through the VyOS CLI, the Debian subsystem can be accessed via the sudo su command executed from the VyOS shell. This capability allows administrators to perform low-level troubleshooting, inspect file systems, or manage processes that fall outside the scope of the network configuration interface. However, direct access to the Linux system should not be utilized for standard configuration changes. The VyOS configuration must be managed through the dedicated CLI or Ansible modules to maintain the integrity of the commit-based workflow. Utilizing the Linux shell for configuration modifications bypasses the staging mechanism and can lead to inconsistent states.

Version differences play a significant role in automation strategies. The VyOS project maintains several branches, including legacy 1.2.x, current 1.3.x, and the rolling updates. Configuration syntax and available features can vary significantly between these versions. Automation playbooks must be tested against the specific VyOS version deployed in the environment. The collection provides metadata to identify compatible Ansible versions using the PEP440 schema. This schema ensures that version constraints are explicitly defined, preventing runtime errors due to incompatibilities.

bash sudo su

The ability to drop to the Debian shell is a fallback mechanism for troubleshooting rather than a primary configuration method. Administrators should rely on the Ansible modules for standard operations to ensure that the commit and save workflows are preserved.

Version Compatibility and Strategic Roadmap

The relationship between the Ansible collection version and the VyOS operating system version is governed by a strict compatibility matrix. The collection has been tested against VyOS 1.3.8, 1.4.1, and the rolling 1.5 release. Compatibility with older versions is maintained where possible, but not guaranteed. The collection requires Ansible version 2.15.0 or higher. The versioning follows the PEP440 standard, which provides a robust framework for describing version constraints and dependencies.

The historical progression of the collection highlights the evolution of support tiers. Version 4.1.0 was the final release for the 4.x series, supporting Ansible 2.15 and VyOS 1.1.2. Version 5.0.0 represented the first release under the VyOS organization as a separate collection, supporting Ansible 2.16 and VyOS 1.1.2. The current 6.0.0 release supports Ansible 2.18 and targets VyOS 1.3.8 and higher. Looking forward, version 7.0.0 is a prospective release intended to support VyOS 1.4.x and deprecate modules incompatible with the legacy 1.3.x series. This roadmap indicates a clear trajectory toward modernizing the toolset to align with the latest operating system capabilities.

The version matrix serves as a critical reference for infrastructure planning. Administrators must align their Ansible environment with the appropriate collection version to ensure compatibility with their VyOS deployments. The deprecation of 1.3.x support in future releases mandates proactive migration planning.

Diverse Automation Paradigms and Community Insights

The automation of VyOS devices extends beyond the Ansible collection, encompassing a broader ecosystem of infrastructure-as-code tools. Community discussions highlight alternative approaches such as Terraform, CloudFormation, and Cloud-init. These tools offer different paradigms for provisioning and configuring network infrastructure. Terraform is frequently utilized for cloud deployments, leveraging CloudFormation for AWS environments. Cloud-init provides a mechanism for initial configuration during the boot process, which can be combined with cron jobs to maintain configuration consistency over time.

Some administrators have experimented with bash scripts as an alternative to the Ansible collection, particularly when facing compatibility issues with specific VyOS versions. These scripts can be integrated with Cloud-init to automate the initial setup. The SDDC.Lab project represents a community-driven initiative to standardize VyOS deployments in software-defined data centers. This project shares automation patterns that can serve as inspiration for broader use cases. The forum discussions reveal that while Ansible is a preferred tool for many, challenges with syntax compatibility between collection versions and VyOS releases can drive some users toward script-based solutions or other IaC tools.

The flexibility of the VyOS platform allows for diverse automation strategies. Whether utilizing the Ansible collection, Terraform, or direct scripting, the goal remains consistent: to achieve reproducible, scalable, and error-free network configuration management. The open-source nature of both VyOS and Ansible fosters a collaborative environment where best practices and custom implementations are shared among the community.

Conclusion

The Ansible VyOS collection represents a mature solution for automating network infrastructure management. The release of version 6.0.0 marks a decisive step in the project's revival, following a period of stagnation. The transfer of repositories to the VyOS organization, coupled with the dedication of maintainers Gaige Paulsen and Evgeny Molotkov, ensures that the toolset evolves in lockstep with the operating system. The collection provides comprehensive modules for configuration management, fact gathering, and protocol configuration. The commit-based workflow of VyOS is fully supported, requiring explicit save operations to ensure data persistence. Version compatibility is strictly managed through the PEP440 schema, with a clear roadmap extending into version 7.0.0. While Ansible remains a primary automation tool, the community explores alternative paradigms such as Terraform and Cloud-init, reflecting the diverse needs of modern network engineering. The integration of these tools enables organizations to build robust, scalable, and secure network environments, leveraging the power of open-source technology to drive operational efficiency.

Sources

1. GitHub - vyos/vyos.vyos
2. VyOS Ansible Collection 6.0.0 Release
3. How to Use Ansible with VyOS Devices
4. VyOS Automation Forum Discussion