67554c0b38
Implements Task 10 doc updates. README/CLAUDE/role-README now reflect that all task files + play_bootstrap/play_backup are implemented and idempotency-verified, that vlans is built+validated but its device run is deferred (placeholder topology, on-site recovery needed), and that the bootstrap/backup plays exist. Corrects the bootstrap invocation example (-e ansible_user=admin --ask-pass). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
54 lines
2.8 KiB
Markdown
54 lines
2.8 KiB
Markdown
# MakerFLOSS_Mikrotik
|
|
|
|
Ansible IaC for one **MikroTik CRS310-8G+2S+IN** switch (RouterOS 7) at the makerspace,
|
|
managed over SSH with `community.routeros`. Sibling project to AnsibleBaobabV4 (whose
|
|
conventions this repo copies); independent repo on `forgejo.makerfloss.eu`.
|
|
|
|
## Tech stack
|
|
|
|
- Ansible 10.x / ansible-core 2.17, `community.routeros` 3.x + `ansible.netcommon`
|
|
- Connection: `ansible.netcommon.network_cli`, `ansible_network_os: community.routeros.routeros`, SSH **key** auth
|
|
- Vault identity **`makerfloss`** (`~/.ansible/vault-keys/makerfloss.txt`)
|
|
- Lint: `ansible-lint` (profile: production), `yamllint`
|
|
|
|
## Structure
|
|
|
|
- `inventories/prod/hosts.yml` — group `mikrotik`, host `crs310-maker`
|
|
- `group_vars/mikrotik.yml` — connection vars + `switch_*_enabled` flags
|
|
- `group_vars/mikrotik.vault.yml` — encrypted password (excluded from linters)
|
|
- `host_vars/crs310-maker.yml` — device facts, real addressing, VLAN/port map
|
|
- `roles/makerfloss.mikrotik_switch/` — one role, per-domain task files gated by flags
|
|
- `play_switch.yml` (day-2), `play_bootstrap.yml` (first contact), `play_backup.yml`
|
|
- `docs/` — field guide, design spec, implementation plan
|
|
|
|
## Essential commands
|
|
|
|
```bash
|
|
yamllint . && ansible-lint && ansible-playbook play_switch.yml --syntax-check
|
|
ansible-playbook play_switch.yml # day-2 (key auth)
|
|
ansible-playbook play_switch.yml --tags vlans # one domain
|
|
ansible-vault view group_vars/mikrotik.vault.yml # read a secret
|
|
```
|
|
|
|
## Rules
|
|
|
|
- **Idempotency:** RouterOS tasks use `community.routeros.command` with `:if [find]`
|
|
guards. Run every device-touching play **twice**; the second run must report no changes.
|
|
- **Lockout safety:** keep an independent recovery channel (serial/WinBox-MAC) when
|
|
touching mgmt/services/VLANs; enable `vlan-filtering` **last**.
|
|
- **All real values go in `host_vars`;** the role holds only mechanism + placeholders.
|
|
- **Secrets** go to the `makerfloss` vault, never plaintext. Encrypt with
|
|
`ansible-vault encrypt --encrypt-vault-id makerfloss <file>`.
|
|
- **New work:** branch first, implement, verify (lint + syntax + run-twice), then merge.
|
|
|
|
## Status / next
|
|
|
|
Bootstrap is done (user `sjat` + key + identity `crs310-maker`, RouterOS 7.19.6 pinned;
|
|
default `admin` now disabled). All per-domain task files are **implemented**:
|
|
`identity`, `users`, `backup`, `firmware` (opt-in) and `play_bootstrap` / `play_backup`
|
|
are idempotency-verified against the device. `vlans` is implemented and Jinja-validated
|
|
but its **device run is deferred** — the `host_vars` topology is still a placeholder.
|
|
|
|
Next, on-site with a recovery channel: drop the real VLAN/port map into `host_vars`,
|
|
reconcile the legacy defconf IP (`192.168.88.1/24` lives directly on `bridge`), then run
|
|
`--tags vlans` and confirm mgmt reachability before/after `vlan-filtering=yes`.
|