blob: 2d803b5f615f6c82c486ceeee98264968291bcfd (
plain)
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
|
# Contributing a blueprint role
A role should implement one page of the VyOS
[Configuration Blueprints](https://docs.vyos.io/en/1.5/configexamples/index.html),
or a building block several pages share.
## Checklist
1. **Inputs** – `meta/argument_specs.yml` with a `main` entry (and `verify`).
Prefix every variable with the role name (`<role>_...`). Keep the blueprint's
vocabulary so the docs page and the role read alike.
2. **Defaults** – mirror the argument-spec defaults in `defaults/main.yml`
(ansible-core validates against the spec but does not apply its defaults).
3. **Tasks** – use vyos.vyos resource modules with
`state: "{{ '<rendered>' if vyos_blueprints_render_only else 'merged' }}"`
(see `vars/main.yml` in existing roles), register each result, and finish
with the "Collect rendered commands" task. Build module `config` from small
templates in `templates/` rather than long inline Jinja.
Use `vyos.vyos.vyos_config` only where no resource module exists, and say
so in the argument spec.
4. **Verify** – `tasks/verify.yml` with operational checks (`show ...`) that
prove the blueprint works, not just that commands were accepted.
5. **Render test** – `tests/render/cases/<role>/<case>/` with `vars.yml`
(and `inventory.yml` for multi-node). Generate the golden file with
`UPDATE_GOLDEN=true tests/render/run.sh <role>/<case>` and check it
against the docs page by hand before committing.
6. **Molecule scenario** – `extensions/molecule/<role>/` with a containerlab
topology, inventory, converge and verify. Copy an existing scenario.
7. **Example** – add or extend a directory under `examples/` if the role is a
user-facing blueprint.
8. **README table** – one line in the top-level README.
## Test tiers
| Tier | Command | Needs |
|---|---|---|
| 0 – lint | `ansible-lint` | nothing |
| 1 – render | `tests/render/run.sh` | nothing (no device) |
| 2 – molecule | `cd extensions && molecule test -s <role>` | docker, containerlab, a VyOS image |
Run tiers 0 and 1 before opening a PR; CI runs all three.
### Local setup
```bash
mkdir -p ~/src/ansible_collections/vyos
git clone https://github.com/vyos/vyos.blueprints ~/src/ansible_collections/vyos/blueprints
cd ~/src/ansible_collections/vyos/blueprints
pip install ansible-core ansible-lint ansible-pylibssh molecule
ansible-galaxy collection install -r tests/requirements.yml -p ~/src
export ANSIBLE_COLLECTIONS_PATH=~/src
scripts/build-vyos-image.sh /path/to/vyos-1.5-*.iso # once, for tier 2
```
Set `CLAB_BECOME=false` if you run containerlab without sudo.
### Container limitations
Containerized VyOS shares the host kernel. Blueprints that depend on kernel
modules or capabilities the CI host lacks (PPPoE/L2TP, some QoS, possibly
DMVPN) may need a VM-based scenario instead; note this in the scenario's
`molecule.yml`.
|
