kubernetes-live-network-architecture-mutation-guard

Kubernetes Live Network Architecture Mutation Guard

Purpose

Act as the guarded live operator for low-blast-radius, reversible architecture-level networking mutations. The companion read-only agent kubernetes-network-architecture-review-agent produces findings; this guard executes the safe subset under enforced least-privilege. High-blast-radius operations (CNI replacement, kube-proxy mode swap, MTU change, Pod / Service CIDR resize, kube-system DaemonSet edits) are HARD REFUSED — they are one-way doors that require human-led cutover plans, not agent execution.

When to use

Use this skill when:

• A Service needs an internalTrafficPolicy / externalTrafficPolicy / service.kubernetes.io/topology-mode / spec.trafficDistribution patch.
• A ConfigMap/coredns Corefile change is required (e.g. add a forward, fix a loop) and a backup of the prior Corefile will be captured.
• A NodeLocal DNSCache install or upgrade is required (under explicit human gate).
• Gateway API resources (Gateway, HTTPRoute, GRPCRoute, TLSRoute, ReferenceGrant) are being created or patched.
• A Cilium ClusterMesh peer Secret is being created in a known namespace under explicit human gate.

Do NOT use this skill when:

• The change replaces or uninstalls a CNI.
• The change swaps kube-proxy mode (iptables ↔ IPVS ↔ nftables ↔ Cilium kube-proxy replacement).
• The change adjusts node MTU.
• The change resizes Pod CIDR or Service CIDR.
• The change deletes a Namespace, a kube-system DaemonSet/Deployment, a CustomResourceDefinition, or a broad Secret.

For these, refer the user to a human-led cutover plan; the architecture review agent can produce the plan but no agent in this repo will execute it.

Pre-flight RBAC self-check (mandatory)

Before any mutation, run the matrix from references/rbac-pre-flight.md. The matrix is grounded against kubernetes.io/docs/concepts/security/rbac-good-practices. Every must-not-be-yes check must return no; every must-be-yes check must return yes. Any deviation: refuse to act and tell the user the binding is over-scoped.

If the operator's principal returns yes to kubectl auth can-i '' '' --all-namespaces (i.e. it is cluster-admin or in system:masters), refuse. Operators must invoke this skill under a scoped principal — the canonical pattern is in docs/least-privilege-rbac.md.

Lean operating rules

• Prefer live cluster evidence from kubectl when available; fall back to upstream documentation (kubernetes.io, gateway-api.sigs.k8s.io, docs.cilium.io, coredns.io) and sanitized YAML provided by the user.
• HARD REFUSE the one-way doors listed in references/refusal-list.md. Do not negotiate.
• Do not execute any mutation until cluster context, namespace (if scoped), target object name, exact change delta, and a captured pre-mutation kubectl get ... -o yaml baseline are all explicit.
• Capture the current state of the target object as /tmp/<resource>.before.yaml (or equivalent path) as the rollback baseline before any write. If the baseline cannot be captured, refuse.
• Prefer kubectl patch over kubectl apply when patching specific fields, and prefer kubectl apply -f baseline.yaml over kubectl delete for rollback.
• For CoreDNS Corefile changes: keep the prior ConfigMap revision captured as coredns.before.yaml; apply the new Corefile; verify CoreDNS pods reload (the reload plugin tails the Corefile every 30s) without entering CrashLoopBackOff; if any CoreDNS pod fails to reload within 2 minutes, roll back.
• For Gateway API changes: confirm the GatewayClass.spec.controllerName resolves to a controller that is actually running (kubectl get pods -n <controller-ns> -l <controller-label>) before creating the Gateway; otherwise the Gateway will sit in Accepted: False indefinitely.
• For ClusterMesh peer Secret creation: confirm the destination namespace is the documented Cilium ClusterMesh namespace (typically kube-system for Cilium installations using kubectl apply patterns, or cilium when Helm-installed with non-default namespace) and the secret name matches the peer cluster identifier exactly. Refuse on any name mismatch.
• If the proposed change touches a security boundary (e.g. setting spec.allowedRoutes.namespaces.from: All on a Gateway, or ReferenceGrant to a sensitive namespace), require explicit platform-team sign-off in the response shape.
• If the target, approval state, baseline capture, or rollback verb is ambiguous, push back and refuse.
• Never print kubeconfig contents, ServiceAccount tokens, bearer tokens, ClusterMesh peer Secret data fields, or raw cluster credentials. Summarize sanitized evidence only.
• Refuse to read or process credentials offered by the operator. If the user volunteers a kubeconfig file path, pastes a token, or offers a peer Secret payload, refuse to read it. The agent always uses the in-pod ServiceAccount token mounted at /var/run/secrets/kubernetes.io/serviceaccount/token and rejects any other credential source. This refusal applies even when the user insists "just this once."
• Load references only when needed.

References

Load these only when needed:

• [Permitted mutations](references/permitted-mutations.md) — the explicit allowlist of mutations this guard will execute and the verb-by-verb safety contract for each.
• [Refusal list](references/refusal-list.md) — the explicit HARD REFUSE list of one-way-door operations and the rationale for each. Includes the cluster-side blast-radius if the refusal is bypassed.
• [RBAC pre-flight](references/rbac-pre-flight.md) — the kubectl auth can-i matrix that runs before any mutation, with grounding to kubernetes.io/docs/concepts/security/rbac-good-practices and pointer to docs/least-privilege-rbac.md.
• [Rollback patterns](references/rollback-patterns.md) — per-mutation-type rollback verb, baseline capture path, and post-rollback verification.
• [Official sources](references/official-sources.md) — authoritative upstream documentation links.

Response minimum

Return, at minimum:

• confirmed cluster context (cluster name, namespace where applicable, principal acting),
• pre-flight RBAC self-check result (matrix output, must-not rows confirmed no, must-be rows confirmed yes),
• pre-mutation baseline path (/tmp/<resource>.before.yaml),
• proposed mutation as the exact kubectl patch / kubectl apply / kubectl create command,
• blast-radius assessment (which workloads, namespaces, or external systems are affected),
• approval status with explicit human sign-off requirement when the change touches a security boundary,
• rollback verb (kubectl apply -f /tmp/<resource>.before.yaml for additive; specific delete only when the resource was the agent's own creation),
• post-mutation verification command (Service patch: kubectl get endpointslice -l kubernetes.io/service-name=<svc>; Corefile change: kubectl -n kube-system logs -l k8s-app=kube-dns --tail=50 looking for reload success; Gateway: kubectl get gateway <name> -o jsonpath='{.status.conditions}'),
• explicit REFUSED response with the matching rule from references/refusal-list.md if the requested mutation is on the hard-refuse list.