MakerFLOSS_Mikrotik/docs/superpowers/specs/2026-06-07-mikrotik-crs310-ansible-design.md

# MakerFLOSS_Mikrotik — CRS310 Ansible Management — Design

**Date:** 2026-06-07
**Status:** Approved (brainstorming complete; pending implementation plan)
**Author:** sjat + Claude

## Purpose

Manage the makerspace's MikroTik **CRS310-8G+2S+IN** 10-port switch
(8× 2.5GbE + 2× SFP+ 10G, RouterOS) as Infrastructure-as-Code with Ansible.
Goal: deterministic, idempotent, version-controlled switch configuration —
identity, management access, users/keys, VLAN switching, backups, and firmware —
so the switch can be rebuilt from the repo with no manual WinBox clicking.

## Scope

**In scope (this iteration):** a single CRS310 switch, configured over SSH.

Configuration domains, each gated by an enable-flag:
1. **Identity + management + services** — hostname/identity, management IP/VLAN,
   NTP/DNS, enable SSH, disable unused services (telnet, ftp, www, api; winbox decision in Open Items).
2. **Users + SSH keys** — named admin user, import operator SSH public key,
   harden/disable the default `admin`.
3. **VLANs + bridge + ports** — bridge with hardware-offload VLAN filtering,
   access/trunk port assignments, SFP+ as upstream trunk. Ships with a
   **placeholder** example topology; real VLAN IDs/port map filled into `host_vars` later.
4. **Backups + firmware** — scheduled `/export` + `/system backup`, fetched into the
   repo; RouterOS/RouterBOOT upgrade flow to a pinned target version.

**Out of scope (for now):** additional MikroTik devices, APs, routers; the REST API
transport; CI/molecule testing; monitoring integration. Structure should not *prevent*
these later, but we build only the single-switch path.

## Decisions (from brainstorming)

| Topic | Decision |
|---|---|
| Project / repo name | `MakerFLOSS_Mikrotik` (underscore; hyphen acceptable) |
| Repo host | New repo on `forgejo.makerfloss.eu`, remote `origin`, default branch `main` |
| Location | Sibling directory `~/Projects/MakerFLOSS_Mikrotik` |
| Transport | **SSH** via `network_cli` (`community.routeros`), **key auth** for day-2 |
| Role namespace | `makerfloss.*` → role `makerfloss.mikrotik_switch` |
| Vault | **Separate** identity `makerfloss` at `~/.ansible/vault-keys/makerfloss.txt` — NOT the home `prod` key |
| Config location | All real values in `host_vars/<switch>.yml`; connection vars in `group_vars/mikrotik.yml`; mechanism + placeholders in role `defaults/` |
| Base | Fresh repo in AnsibleBaobabV4 conventions; cherry-pick narrowin/ansible-mikrotik command sequences for backup/upgrade |
| Clean slate | Factory-reset switch to **no default configuration**; Ansible owns the entire config |
| Default admin | Create named admin user + import key; **disable** the default `admin` after key login is proven |

## What to bring over from AnsibleBaobabV4

Copy + trim (independent repos; do not symlink):

- `.envrc` + `.venv` direnv bootstrap — verbatim.
- `ansible.cfg` — adapted: `host_key_checking=False`, `vault_identity_list = makerfloss@~/.ansible/vault-keys/makerfloss.txt`, network-CLI-friendly defaults.
- `.ansible-lint` + yamllint config — verbatim.
- `requirements.txt` — trimmed to `ansible`, `ansible-lint`, `yamllint` (drop molecule/docker/snipe/kuma).
- `requirements.yml` — `community.routeros` (pulls in `ansible.netcommon`).
- Inventory cascade pattern: `inventories/prod/hosts.yml` with one host in group `mikrotik`.
- **Operator SSH public key** `~/.ssh/id_ed25519.pub` → imported onto the switch admin user.
- Forgejo push key `~/.ssh/id_ed25519_forgejo` already exists (used for `git push`).

## Architecture

### Repo layout

```
MakerFLOSS_Mikrotik/
├── .envrc / .ansible-lint / .yamllint / ansible.cfg
├── requirements.txt / requirements.yml
├── inventories/
│   └── prod/hosts.yml                 # group: mikrotik -> one switch host
├── group_vars/
│   └── mikrotik.yml                   # connection/platform vars (network_cli, network_os, user, key)
├── host_vars/
│   └── <switch>.yml                   # identity, mgmt IP/VLAN, VLAN+port map, firmware_target
├── roles/
│   └── makerfloss.mikrotik_switch/
│       ├── defaults/main.yml          # enable-flags, safe defaults, PLACEHOLDER vlan/port map
│       ├── tasks/main.yml             # imports domain task files, each gated by a flag
│       ├── tasks/identity.yml         # identity, mgmt IP, NTP/DNS, SSH on, unused services off
│       ├── tasks/users.yml            # named admin, import ssh pubkey, disable default admin
│       ├── tasks/vlans.yml            # bridge + hw VLAN filtering, access/trunk ports, SFP+ uplink
│       ├── tasks/backup.yml           # /export + /system backup save, fetch into repo
│       └── tasks/firmware.yml         # RouterOS + RouterBOOT upgrade to firmware_target
├── playbooks (or top-level):
│   ├── play_bootstrap.yml             # FIRST CONTACT: password auth -> create user, import key
│   ├── play_switch.yml                # day-2: key-only, applies all enabled domains
│   └── play_backup.yml               # on-demand/scheduled backup fetch
├── backups/<switch>/                  # fetched config exports + .backup files
└── docs/superpowers/specs/            # this design doc
```

### Connection model

`group_vars/mikrotik.yml`:
- `ansible_connection: ansible.netcommon.network_cli`
- `ansible_network_os: community.routeros.routeros`
- `ansible_user: <admin user>`
- `ansible_ssh_private_key_file: ~/.ssh/id_ed25519` (day-2, key auth)

`play_bootstrap.yml` overrides with password auth (`--ask-pass`) for first contact only.

### Idempotency strategy (key design challenge)

Over `network_cli`/SSH the primary module is `community.routeros.command` (RouterOS has
no rich declarative module set like `ios_*`). Idempotency is therefore the main risk and
must be deliberate:
- Prefer naturally-idempotent commands: `/.../ set` on known, named items.
- For `add`-style items, guard with RouterOS scripting: `:if ([find <selector>] = "") do={ add ... }`.
- Use `changed_when` based on command output where guards are impractical.
- Keep each domain's command set small and readable; one logical change per task.
- Cross-check against `community.routeros.facts` / `/export` output where useful.

This is explicitly called out so the implementation plan budgets for testing idempotency
(run twice, assert no changes on second run).

## Operational flows

### On-switch preparation (manual, before Ansible)

1. Confirm boot OS is **RouterOS** (not SwOS) — VLAN filtering + `community.routeros` require it.
2. Upgrade RouterOS **and** RouterBOOT firmware to a known-good stable; record as `firmware_target`.
3. **Factory-reset to no default configuration** so Ansible owns the whole config.
4. First-contact connectivity: laptop on a port, reach the device, confirm SSH reachable.
5. Decide addressing (into `host_vars`): mgmt IP/mask, mgmt VLAN, gateway, and which
   port/SFP+ is the upstream **trunk/uplink** to OPNsense.
6. Record identity facts: serial, MAC, model, RouterOS version.
7. Physical: SFP+ module/DAC for the 10G uplink, PSU, mounting.

### Bootstrap (run once)

`play_bootstrap.yml`, SSH **password** auth (default/initial creds):
- create named admin user; set its password from vault;
- import `~/.ssh/id_ed25519.pub`, bind to the user;
- enable SSH service;
- verify key login works, then disable the default `admin`.

### Day-2 (normal)

`play_switch.yml`, **key-only**, applies all enabled domains idempotently.
`play_backup.yml` exports config + binary backup into `backups/<switch>/`.

## Secrets

Vault identity `makerfloss` (`~/.ansible/vault-keys/makerfloss.txt`), referenced in
`ansible.cfg`. Initial contents: the switch admin password. SSH key auth means day-2
runs need no secret at runtime. (Vault-less start is possible but we create the identity
up front.)

## Success criteria

- `play_bootstrap.yml` takes a factory-reset switch to key-based SSH access.
- `play_switch.yml` applies identity + services + users + a placeholder VLAN/port
  topology, and is **idempotent** (second run reports no changes).
- `play_backup.yml` writes a usable `/export` and `.backup` into the repo.
- All real switch values live in `host_vars`; the role contains no makerspace specifics.
- `ansible-lint` and `yamllint` pass.

## Open items to confirm during planning

- Exact RouterOS `firmware_target` version to pin.
- Whether `winbox` service stays enabled (convenience) or is disabled (hardening).
- Named admin username (e.g. `sjat` vs a service account like `ansible`).
- Backup scheduling: Ansible-run on demand vs a RouterOS scheduler + fetch.

## Reference

- `narrowin/ansible-mikrotik` (GitHub) — playbook-centric; mine its backup/upgrade
  command sequences. Not used as a dependency.
- `community.routeros` Ansible collection.
- AnsibleBaobabV4 — conventions source (direnv, ansible.cfg, lint, inventory cascade,
  enable-flag role idiom).