---
name: devops-infra-core
description: "Shared reference for the devops-infra cluster: the read-only-by-default safety boundary every spoke turns on (diagnose → change-window → verify → rollback), the change-class taxonomy, shared conventions for evidence and isolation, and the tooling/version matrix. USE WHEN any infra task is about to mutate state — a device config, a firewall/VLAN rule, a container or cluster deploy — or when you need the conventions every devops-infra spoke shares."
cluster: devops-infra
version: 1.0.0
---

# DevOps & Infra Core

Shared model for the `devops-infra` cluster. The container, network, and homelab spokes span
very different tools, but they all turn on **one decision**: is this action *read-only*, or does
it *change state*? Keep that boundary consistent here so no spoke quietly normalizes a risky
change.

## 1. The decision the whole cluster turns on (the safety boundary)

Every spoke has two paths. The **default is read-only**; the change path is gated.

```
DIAGNOSE (read-only)  ──>  PLAN change + rollback  ──>  CHANGE WINDOW  ──>  VERIFY  ──>  rollback if regressed
   always safe              write down the undo        out-of-band access     prove it       cheap because planned
```

- **Read-only / diagnose** — show commands, counters, logs, `uc inspect`, a canary probe, a config *review*. Run freely, anytime, in production. This is where triage starts and usually ends.
- **Change / mutate** — a config line pushed, a firewall or ACL or VLAN rule, a `uc` deploy or scale, a container restart, a VPN route. Requires: a known rollback, a maintenance window, and secured console / out-of-band access **before** you touch anything.

**Rule:** never let a diagnosis turn into a change in the same breath. Collect evidence first;
state explicitly when you cross into a change.

## 2. Change-class taxonomy (how risky is this action?)

| Class | Examples | Gate |
|---|---|---|
| **Observe** | show/log/counter, `docker logs`, `canary-watch`, config review, `flox activate` | none — safe in prod |
| **Additive-isolation** | new VLAN, new firewall *deny*, Pi-hole blocklist, new capability scope | window + verify reachability after each step (isolation can over-block) |
| **Mutating** | push device config, `uc deploy`/scale, restart container, change DHCP/DNS | window + rollback + out-of-band access |
| **Widening** | open a port, loosen an ACL, full-tunnel a VPN, expose a service | window + rollback + **explicit** justification (reduces security posture) |

Route by class: `network-config-validation` and `cisco-ios-patterns` gate the *mutating*
device path; `homelab-vlan-segmentation`/`-pihole-dns`/`-wireguard-vpn` are *additive/widening*;
`canary-watch` is the *observe* step that proves a *mutating* deploy.

## 3. Shared conventions

- **Evidence before action.** Capture the before-state (counters, neighbor table, current config, a canary baseline) so you can prove the change helped and roll back to a known point. → `network-interface-health`, `network-bgp-diagnostics`, `netmiko-ssh-automation`, `canary-watch`.
- **Automation defaults to read-only.** Netmiko/SSH and any script collect by default; config push is a separate, peer-reviewed, rollback-backed path. → `netmiko-ssh-automation`.
- **Isolation is added, never silently removed.** VLAN/firewall changes increase separation; verify cross-segment reachability after each step. → `homelab-vlan-segmentation`.
- **Reproducibility over snowflakes.** Pin environments and infra declaratively (Flox `manifest.toml` committed to the repo; Compose files; `uc` service specs) so a teammate or agent reproduces them exactly. → `flox-environments`, `docker-patterns`, `uncloud`.
- **Verify the deploy, don't assume it.** A merge or release isn't done until a canary confirms the live endpoint. → `canary-watch`.

## 4. Tooling / version matrix

| Layer | Tool / target | Spoke |
|---|---|---|
| Containers (local) | Docker + Docker Compose | `docker-patterns` |
| Self-hosting cluster | `uc` CLI — Docker + WireGuard mesh + Caddy | `uncloud` |
| Post-deploy check | HTTP / SSE / asset / console / perf probes | `canary-watch` |
| Dev environments | Flox (Nix-based, `manifest.toml`, 150k+ pkgs, macOS + Linux) | `flox-environments` |
| Enterprise switches/routers | Cisco IOS / IOS-XE | `cisco-ios-patterns`, `network-config-validation` |
| Network automation | Python + Netmiko + TextFSM | `netmiko-ssh-automation` |
| Routing | BGP | `network-bgp-diagnostics` |
| Physical / link layer | router, switch, Linux interfaces | `network-interface-health` |
| Homelab gateway/switch/AP | UniFi · pfSense/OPNsense · MikroTik | `homelab-network-setup`, `homelab-vlan-segmentation` |
| Local DNS filtering | Pi-hole (+ DoH, DHCP) | `homelab-pihole-dns` |
| Remote access | WireGuard | `homelab-wireguard-vpn` |

## 5. Shared guardrails

- **Read-only by default.** Diagnose first; cross into a change only deliberately, and say so.
- **Plan the rollback before the change** — and secure console / out-of-band access first; a network change can cut the path you're connected over.
- **Change window for anything Mutating or Widening.** Verify after each step; don't batch unverified changes.
- **Isolation changes add, never remove** — confirm reachability between segments after each step.
- **State every access-widening change** (open port, loosened ACL, full-tunnel VPN, exposed service) explicitly — it lowers the security posture.
- **Pin and commit** environment/infra definitions so they're reproducible, not snowflakes.
- **A deploy isn't done until a canary confirms it** on the live endpoint.