vyos-ansible

Generic Ansible template for managing a VyOS VRRP cluster via GitLab CI.

Enforces baseline config (commit-archive, DHCP pools) on a schedule. Drift is corrected automatically — no manual commit required.

flowchart LR
    subgraph nodes["VyOS Cluster"]
        n1["node1 MASTER"]
        n2["node2 BACKUP"]
        n3["node3 BACKUP"]
    end

    subgraph gitlab["GitLab"]
        cfg["vyos-cfg\nconfig archive"]
        ci["GitLab CI\nscheduled pipeline"]
    end

    n1 & n2 & n3 -->|"commit-archive\ngit+https"| cfg
    ci -->|"SSH / Ansible\nenforce baseline"| n1 & n2 & n3

Loading

How it works

• Nodes → GitLab: every commit on a VyOS node pushes config.boot via the built-in commit-archive feature (git+https:// transport)
• GitLab → Nodes: scheduled CI pipeline runs Ansible to enforce baseline config. Drift is corrected automatically

Repository layout

vyos-ansible/
├── LICENSE
├── SECURITY.md
├── CONTRIBUTING.md
├── ansible.cfg
├── requirements.txt
├── inventory/
│   ├── hosts.yml
│   └── group_vars/
│       ├── all.yml          # shared defaults (commit_revisions)
│       └── vyos.yml         # cluster subnets, DNS, DHCP pools
│   └── host_vars/
│       ├── vyos-node1.yml   # per-node overrides (usually empty)
│       ├── vyos-node2.yml
│       └── vyos-node3.yml
├── playbooks/
│   ├── baseline.yml         # enforce config
│   ├── verify.yml           # assert post-apply health
│   └── tests/
│       └── assert_config.yml
└── docs/
    ├── architecture.md      # Mermaid diagrams — topology, CI flow, secrets
    ├── getting-started.md
    ├── ci-pipeline.md
    └── customising.md

Quick start

1. Clone this repo
2. Edit inventory/hosts.yml — replace placeholder IPs and ansible_user
3. Edit inventory/group_vars/vyos.yml — set subnets, DNS, DHCP pools, and commit_archive_url pointing to your config archive repo
4. Set CI variables (ANSIBLE_SSH_KEY, VYOS_GITLAB_TOKEN) — see below
5. Push — validate and dry_run stages run automatically
6. Add a CI schedule for nightly apply

Full walkthrough: docs/getting-started.md

CI secrets

Works with both GitLab CI (.gitlab-ci.yml) and GitHub Actions (.github/workflows/vyos.yml) — use whichever matches your platform.

Secret	Description
ANSIBLE_SSH_KEY	SSH private key for the VyOS admin user
VYOS_GITLAB_TOKEN	Token with write_repository on the config archive repo

CI stages

Stage	Trigger	Purpose
validate	every push / PR	ansible-lint + syntax check
dry_run	on success	--check --diff, artifact kept 14 days
apply	manual gate	human-approved apply (GitLab: play button; GitHub: environment reviewer)
verify	after apply	assert commit-archive, VRRP, DHCP health

See docs/ci-pipeline.md for full reference.

Documentation

Architecture & diagrams	System diagrams with Mermaid
Getting started	Clone-to-schedule walkthrough
CI pipeline	Stage reference, artifacts, schedules
Customising	Rename cluster, add pools, multi-site

Requirements

• VyOS 1.4+ (tested on 2026.02 rolling)
• GitLab with a registered runner
• Python 3.11+

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md for the vulnerability reporting policy and secrets-handling design notes.

License

MIT — TWN Systems