1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
# Using vyos.blueprints
## What the roles need from you
A role touches your environment in three places only:
1. **Connection variables** for each router:
```yaml
ansible_network_os: vyos.vyos.vyos
ansible_connection: ansible.netcommon.network_cli
ansible_user: vyos
ansible_password: "{{ vault_vyos_password }}" # or ansible_ssh_private_key_file
```
2. **Role inputs** – the variables listed by `ansible-doc -t role vyos.blueprints.<role>`.
They are validated when the role starts, so typos and missing values fail
early with a clear message.
3. **Pair or group membership** – only for multi-node blueprints (see below).
Nothing else is assumed: not how the router was deployed, not where your
inventory comes from, not your directory layout.
## Where the variables come from
The same playbook works with any inventory source; only the place where you
keep the variables changes.
| Setup | Inventory | Role inputs |
|---|---|---|
| Single router / lab | static `inventory.yml` | `group_vars/` and `host_vars/` |
| Trying things out | containerlab (`topology.clab.yml` in each example; clab also writes an Ansible inventory into the lab directory) | example `group_vars/` |
| Netbox | `netbox.netbox.nb_inventory` | Netbox config contexts, or `group_vars/` keyed on Netbox-generated groups |
| AWX / AAP | any of the above as an inventory source | same; build an execution environment containing `vyos.blueprints` |
## Multi-node blueprints
Blueprints such as HA need to know which routers belong together.
* Put the members of one pair in their **own inventory group** and pass its
name, e.g. `ha_vrrp_pair_group: ha_pair`.
* Keep **shared** settings (VRRP groups, sync-group) in that group's
`group_vars`, and **per-node** settings (priority, the node's own
addresses) in `host_vars`.
* Peer addresses are derived from the other member's `host_vars`. If the peer
is not in your inventory, or you prefer to be explicit, set
`ha_vrrp_peer_addresses` instead – explicit values always win.
Run multi-node plays against all members together (`hosts: ha_pair`) so the
cross-node checks in `verify` can compare them.
## Preview without touching devices
```bash
ansible-playbook -i inventory.yml site.yml -e vyos_blueprints_render_only=true
```
Each role then uses the modules' `rendered` state and appends the commands it
would send to the `vyos_blueprints_rendered` fact, which you can print or save
for review. The rendering assumes VyOS 1.5 syntax; set
`VYOS_OFFLINE_OS_VERSION=1.4` in the environment to render for 1.4.
> Some vyos.vyos modules currently need a device connection even when
> rendering. Until that is fixed upstream, render-only mode needs vyos.vyos
> from git `main`.
## Checking a deployment
```yaml
- hosts: ha_pair
gather_facts: false
tasks:
- ansible.builtin.include_role:
name: vyos.blueprints.ha_vrrp
tasks_from: verify
```
## Layering
```
day-0 provisioning (not part of this collection: hypervisor, cloud, cloud-init)
│ reachable VyOS with SSH
▼
inventory + variables (yours: static, containerlab, Netbox, AWX)
│
▼
vyos.blueprints roles base → edge_nat / ha_vrrp / ...
│
▼
vyos.vyos resource modules → VyOS
│
▼
verify (operational checks per role)
```
|
