@raishin/vanguard-frontier-agentic 1.3.0 → 1.5.0

package/skills/kubernetes/kubernetes-live-network-architecture-mutation-guard/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: kubernetes-live-network-architecture-mutation-guard
+description: Guard live kubectl apply, patch, or create operations on Kubernetes networking *architecture* surface — Service spec (`internalTrafficPolicy`, `externalTrafficPolicy`, `topology-mode`, `trafficDistribution`), CoreDNS Corefile, NodeLocal DNSCache install, Gateway API resources (Gateway / HTTPRoute / GRPCRoute / TLSRoute / ReferenceGrant), and ClusterMesh peer Secrets. HARD REFUSE one-way doors (CNI replacement, kube-proxy mode swap, MTU change, Pod / Service CIDR resize, namespace deletion). Pre-flight `kubectl auth can-i` matrix against a least-privilege ServiceAccount before any write. Use only when an intentional architecture-level networking mutation is requested against a confirmed cluster target with a documented rollback path.
+allowed-tools: Bash Read Edit Grep Glob WebFetch
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-05-08"
+  category: networking
+---
+
+# 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.

package/skills/kubernetes/kubernetes-live-network-architecture-mutation-guard/metadata.json

@@ -0,0 +1,33 @@
+{
+  "id": "kubernetes-live-network-architecture-mutation-guard",
+  "name": "Kubernetes Live Network Architecture Mutation Guard",
+  "type": "skill",
+  "provider": "kubernetes",
+  "harnesses": [
+    "codex",
+    "claude-code",
+    "cursor",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Guard live kubectl apply/patch/create operations on networking architecture surface — Service spec (internalTrafficPolicy, externalTrafficPolicy, topology-mode, trafficDistribution), CoreDNS Corefile, NodeLocal DNSCache install, Gateway API resources, and ClusterMesh peer Secrets. HARD REFUSE one-way doors (CNI replacement, kube-proxy mode swap, MTU change, Pod / Service CIDR resize, namespace deletion). Pre-flight kubectl auth can-i matrix against a least-privilege ServiceAccount before any write.",
+  "source_type": "original",
+  "official_docs": [
+    "https://kubernetes.io/docs/concepts/security/rbac-good-practices/",
+    "https://kubernetes.io/docs/reference/access-authn-authz/rbac/",
+    "https://kubernetes.io/docs/reference/kubectl/generated/kubectl_auth/kubectl_auth_can-i/",
+    "https://kubernetes.io/docs/concepts/services-networking/service-traffic-policy/",
+    "https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/",
+    "https://kubernetes.io/docs/tasks/administer-cluster/nodelocaldns/",
+    "https://gateway-api.sigs.k8s.io/api-types/gateway/",
+    "https://gateway-api.sigs.k8s.io/api-types/httproute/",
+    "https://coredns.io/plugins/reload/",
+    "https://docs.cilium.io/en/stable/network/clustermesh/clustermesh/"
+  ],
+  "security_notes": "This skill is bound to a ServiceAccount with deliberately omitted verbs: no `delete` cluster-wide, no operations on `namespaces` / `customresourcedefinitions` / `kube-system` DaemonSets and Deployments / broad `secrets`. Pre-flight `kubectl auth can-i` matrix MUST run before any mutation; refuses if any must-not check returns `yes` (binding over-scoped) or if operator is in `system:masters` (RBAC bypass). HARD REFUSE list covers one-way doors that are out-of-scope for any agent: CNI replacement, kube-proxy mode swap, MTU change, Pod / Service CIDR resize. CoreDNS Corefile changes require backup capture and post-mutation reload verification within 2 minutes. Gateway resources require GatewayClass controller liveness check before creation. ClusterMesh peer Secret data fields must never be printed or logged.",
+  "last_verified": "2026-05-08",
+  "path": "skills/kubernetes/kubernetes-live-network-architecture-mutation-guard",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/kubernetes/kubernetes-live-network-architecture-mutation-guard/references/least-privilege-rbac.yaml

@@ -0,0 +1,210 @@
+# =====================================================================
+# Least-privilege RBAC for kubernetes-live-network-architecture-mutation-guard-agent
+#
+# Apply BEFORE running the agent.
+# Authoring contract: docs/least-privilege-rbac.md
+# Pre-flight matrix:  references/rbac-pre-flight.md
+# Refusal list:       references/refusal-list.md (cluster-side enforcement of these omissions)
+#
+# Audit:
+#   SA="system:serviceaccount:vanguard-system:vanguard-network-arch-guard"
+#   kubectl auth can-i delete namespaces --as=$SA       # must return: no
+#   kubectl auth can-i patch services -A --as=$SA       # must return: yes
+#
+# Per upstream kubernetes.io/docs/concepts/security/rbac-good-practices:
+#   "Avoid wildcard permissions, especially to all resources, as this grants
+#    access to current and future object types."
+# =====================================================================
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: vanguard-system
+  labels:
+    pod-security.kubernetes.io/enforce: restricted
+    pod-security.kubernetes.io/enforce-version: latest
+    app.kubernetes.io/managed-by: vanguard-frontier
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: vanguard-network-arch-guard
+  namespace: vanguard-system
+  annotations:
+    vanguard.frontier/agent: "kubernetes-live-network-architecture-mutation-guard-agent"
+    vanguard.frontier/scope: "least-privilege-network-architecture"
+    vanguard.frontier/contract: "docs/least-privilege-rbac.md"
+automountServiceAccountToken: true
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: vanguard-network-arch-guard
+rules:
+  # ---- READ across networking architecture surface ----
+  - apiGroups: [""]
+    resources: ["services", "endpoints", "nodes"]
+    verbs: ["get", "list", "watch"]
+  - apiGroups: ["discovery.k8s.io"]
+    resources: ["endpointslices"]
+    verbs: ["get", "list", "watch"]
+  - apiGroups: ["gateway.networking.k8s.io"]
+    resources:
+      - "gatewayclasses"
+      - "gateways"
+      - "httproutes"
+      - "grpcroutes"
+      - "tlsroutes"
+      - "tcproutes"
+      - "udproutes"
+      - "referencegrants"
+    verbs: ["get", "list", "watch"]
+  # ---- WRITE on Service spec (low blast radius, reversible) ----
+  - apiGroups: [""]
+    resources: ["services"]
+    verbs: ["patch"]
+    # NOTE: "delete" verb DELIBERATELY OMITTED. Rollback uses `kubectl apply -f baseline.yaml`.
+    # NOTE: "update" verb omitted in favor of "patch" for narrower change semantics.
+  # NOTE: CoreDNS ConfigMap read/write is intentionally ABSENT from this ClusterRole.
+  # resourceNames on a ClusterRole restricts only the object name, not the namespace;
+  # a ClusterRole rule would let the SA patch any ConfigMap named "coredns" in ANY
+  # namespace. A namespaced Role/RoleBinding in kube-system (below) provides the
+  # correct least-privilege scope. See docs/least-privilege-rbac.md §Threat model.
+  # ---- WRITE on Gateway API resources (user-owned, not control plane) ----
+  - apiGroups: ["gateway.networking.k8s.io"]
+    resources:
+      - "gateways"
+      - "httproutes"
+      - "grpcroutes"
+      - "tlsroutes"
+      - "tcproutes"
+      - "udproutes"
+      - "referencegrants"
+    verbs: ["create", "patch"]
+    # NOTE: "delete" verb DELIBERATELY OMITTED on Gateway API resources.
+    # Rollback to absent state is performed by a human-confirmed operation, not by this agent.
+    # NOTE: "gatewayclasses" is read-only; GatewayClass is installed by the controller's Helm chart.
+# =====================================================================
+# DELIBERATELY ABSENT — DO NOT add unless you accept the listed risk.
+# This list is exhaustive against the destructive operations enumerated
+# in references/refusal-list.md. The binding is deny-by-default: anything
+# not granted above is denied at the API server. New attack vectors that
+# emerge in future Kubernetes releases are denied automatically.
+#
+# === Namespaces & finalizers ===
+#   apiGroups: [""], resources: ["namespaces"]                              -> delete kube-system / cilium / istio-system
+#   patch with metadata.finalizers paths on any resource                    -> bypass namespace / PV / CRD finalizer protection
+#
+# === Workload writes in control-plane namespaces ===
+#   apiGroups: [""], resources: ["pods"]                                    -> exec / delete on control-plane pods
+#   apiGroups: [""], resources: ["pods/exec"]                               -> shell into cilium-agent / kube-proxy / coredns
+#   apiGroups: [""], resources: ["pods/portforward"]                        -> NetworkPolicy bypass to any reachable Service
+#   apiGroups: [""], resources: ["pods/proxy"]                              -> proxy traffic via apiserver to pod
+#   apiGroups: [""], resources: ["pods/binding"]                            -> manual Pod-to-Node binding, scheduler bypass
+#   apiGroups: [""], resources: ["pods/eviction"]                           -> bypass PodDisruptionBudgets in some configs
+#   apiGroups: ["apps"], resources: ["daemonsets"], verbs: write            -> remove cilium / kube-proxy / node-local-dns
+#   apiGroups: ["apps"], resources: ["deployments"], verbs: write           -> remove ingress controllers / mesh control planes
+#   apiGroups: ["apps"], resources: ["statefulsets"], verbs: write          -> remove etcd-replica / clustered controllers
+#
+# === Node lifecycle ===
+#   apiGroups: [""], resources: ["nodes"], verbs: ["patch", "update", "delete"]    -> drain / cordon / delete nodes
+#   apiGroups: [""], resources: ["nodes/proxy"]                             -> direct kubelet API, bypasses some RBAC
+#   apiGroups: ["coordination.k8s.io"], resources: ["leases"]               -> Lease in kube-node-lease, fake node liveness
+#
+# === Secrets & credentials ===
+#   apiGroups: [""], resources: ["secrets"]                                 -> cluster-wide credential exposure
+#   apiGroups: [""], resources: ["serviceaccounts/token"]                   -> mint tokens for arbitrary SAs (TokenRequest)
+#   apiGroups: ["certificates.k8s.io"], any verb                            -> approve CSRs, especially with system:masters group
+#   apiGroups: ["authentication.k8s.io"], any verb                          -> tokenreviews, impersonation primitives
+#
+# === Cluster-extension surface (admission, aggregation, scheduling) ===
+#   apiGroups: ["admissionregistration.k8s.io"]                             -> mutating/validating webhook configs (admission bypass)
+#   apiGroups: ["apiregistration.k8s.io"]                                   -> APIService aggregation hijack
+#   apiGroups: ["apiextensions.k8s.io"]                                     -> CRD install / uninstall
+#   apiGroups: ["scheduling.k8s.io"]                                        -> PriorityClass system-cluster-critical / system-node-critical
+#   apiGroups: ["policy"], resources: ["poddisruptionbudgets"], verbs: write -> remove eviction protection
+#
+# === Networking control plane ===
+#   apiGroups: [""], resources: ["endpoints"], verbs: write                 -> race with EndpointSlice controller, redirect Service traffic
+#   apiGroups: ["discovery.k8s.io"], resources: ["endpointslices"], verbs: write  -> same race
+#   apiGroups: ["networking.k8s.io"], resources: ["ingressclasses"], verbs: write -> break Ingress controller binding
+#   apiGroups: ["networking.k8s.io"], resources: ["networkpolicies"]        -> delegated to cilium-network-policy-review
+#   apiGroups: ["cilium.io"], resources: ["ciliumnetworkpolicies", "ciliumclusterwidenetworkpolicies"]  -> delegated
+#   apiGroups: ["security.istio.io"], resources: ["authorizationpolicies", "peerauthentications"]      -> delegated
+#
+# === Storage ===
+#   apiGroups: ["storage.k8s.io"], resources: ["storageclasses"], verbs: write    -> remove default StorageClass, break PVC provisioning
+#   apiGroups: [""], resources: ["persistentvolumes"], verbs: write               -> orphan cloud volumes
+#
+# === RBAC self-modification ===
+#   apiGroups: ["rbac.authorization.k8s.io"]                                -> binding self-modification, privilege escalation
+#
+# === Wildcards (always anti-pattern) ===
+#   any "*" verb or "*" resource                                            -> per upstream RBAC good practices, grants future objects
+#
+# === Cross-cutting verbs ===
+#   any "delete" verb on cluster-scoped or namespaced resources             -> rollback is `apply -f baseline.yaml`, never delete
+#
+# Add ClusterMesh peer Secret write access (resourceName-locked, narrow
+# namespace) only when the operator explicitly opts in for ClusterMesh
+# peering and accepts the additional review checklist in
+# references/permitted-mutations.md. The narrow scope must be expressed
+# both in the Role (resourceNames: [<peer-cluster-id>]) and in admission
+# policy (Kyverno rule limiting Secret data field shape).
+# =====================================================================
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: vanguard-network-arch-guard
+subjects:
+  - kind: ServiceAccount
+    name: vanguard-network-arch-guard
+    namespace: vanguard-system
+roleRef:
+  kind: ClusterRole
+  name: vanguard-network-arch-guard
+  apiGroup: rbac.authorization.k8s.io
+---
+# =====================================================================
+# Namespaced Role + RoleBinding for CoreDNS ConfigMap access.
+# A ClusterRole with resourceNames restricts only the object name, not
+# the namespace, so the SA would be able to patch any ConfigMap named
+# "coredns" cluster-wide. This Role is bound only in kube-system,
+# providing the correct least-privilege scope.
+# =====================================================================
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: vanguard-network-arch-guard-coredns
+  namespace: kube-system
+  annotations:
+    vanguard.frontier/agent: "kubernetes-live-network-architecture-mutation-guard-agent"
+    vanguard.frontier/contract: "docs/least-privilege-rbac.md"
+rules:
+  # Broad read in kube-system — needed to inspect ConfigMap state before patching.
+  - apiGroups: [""]
+    resources: ["configmaps"]
+    verbs: ["get", "list", "watch"]
+  # Patch locked to the single ConfigMap that holds the CoreDNS Corefile.
+  # NOTE: "delete" verb DELIBERATELY OMITTED. Rollback uses `kubectl apply -f baseline.yaml`.
+  - apiGroups: [""]
+    resources: ["configmaps"]
+    resourceNames: ["coredns"]
+    verbs: ["patch"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: vanguard-network-arch-guard-coredns
+  namespace: kube-system
+  annotations:
+    vanguard.frontier/agent: "kubernetes-live-network-architecture-mutation-guard-agent"
+    vanguard.frontier/contract: "docs/least-privilege-rbac.md"
+subjects:
+  - kind: ServiceAccount
+    name: vanguard-network-arch-guard
+    namespace: vanguard-system
+roleRef:
+  kind: Role
+  name: vanguard-network-arch-guard-coredns
+  apiGroup: rbac.authorization.k8s.io

package/skills/kubernetes/kubernetes-live-network-architecture-mutation-guard/references/official-sources.md

@@ -0,0 +1,41 @@
+# Official sources
+
+Authoritative upstream documentation for the surfaces this guard mutates.
+
+## RBAC and authorization
+
+- [RBAC Good Practices](https://kubernetes.io/docs/concepts/security/rbac-good-practices/) — the foundational guidance this guard implements: minimal privilege, no wildcards, no `cluster-admin` for routine work, no `system:masters` group membership.
+- [Using RBAC Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) — the API reference for `Role` / `ClusterRole` / `RoleBinding` / `ClusterRoleBinding`.
+- [`kubectl auth can-i`](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_auth/kubectl_auth_can-i/) — the pre-flight matrix syntax.
+- [User Impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation) — the recommended pattern: low-privileged operator with `impersonate` rights on the agent's ServiceAccount.
+
+## Service traffic policy and topology-aware routing
+
+- [Service Internal Traffic Policy](https://kubernetes.io/docs/concepts/services-networking/service-traffic-policy/) — `internalTrafficPolicy` and `externalTrafficPolicy` semantics.
+- [Topology Aware Routing](https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/) — `service.kubernetes.io/topology-mode: Auto` annotation and `spec.trafficDistribution` field.
+
+## CoreDNS
+
+- [CoreDNS `kubernetes` plugin](https://coredns.io/plugins/kubernetes/) — the in-cluster DNS plugin reference.
+- [CoreDNS `reload` plugin](https://coredns.io/plugins/reload/) — Corefile change detection (default 30s poll).
+- [CoreDNS `loop` plugin](https://coredns.io/plugins/loop/) — recursion-loop detection (silent failure mode if absent).
+- [CoreDNS `health` plugin](https://coredns.io/plugins/health/) — liveness probe target.
+
+## NodeLocal DNSCache
+
+- [Using NodeLocal DNSCache in Kubernetes Clusters](https://kubernetes.io/docs/tasks/administer-cluster/nodelocaldns/) — install manifest, the `__PILLAR__` token substitutions, and the kube-proxy / Cilium kube-proxy replacement preconditions.
+
+## Gateway API
+
+- [Gateway API](https://gateway-api.sigs.k8s.io/) — the SIG site (authoritative).
+- [`Gateway` resource](https://gateway-api.sigs.k8s.io/api-types/gateway/) — the listener model and `allowedRoutes` semantics.
+- [`HTTPRoute`](https://gateway-api.sigs.k8s.io/api-types/httproute/) — HTTP route reference.
+- [`GRPCRoute`](https://gateway-api.sigs.k8s.io/api-types/grpcroute/) — gRPC route reference. **GA / Standard channel since Gateway API v1.1.0.**
+- [`ReferenceGrant`](https://gateway-api.sigs.k8s.io/api-types/referencegrant/) — cross-namespace reference authorization.
+- [Gateway API Versioning](https://gateway-api.sigs.k8s.io/concepts/versioning/) — Standard vs Experimental channel semantics.
+
+## Cilium ClusterMesh
+
+- [Setting up Cluster Mesh](https://docs.cilium.io/en/stable/network/clustermesh/clustermesh/) — peer Secret structure, namespace, and CA trust setup.
+- [ClusterMesh Troubleshooting](https://docs.cilium.io/en/stable/operations/troubleshooting/) — `cilium clustermesh status`, `cilium-dbg troubleshoot clustermesh`, and the KVStoreMesh `kvstoremesh-dbg troubleshoot` command.
+- [KVStoreMesh command reference](https://docs.cilium.io/en/stable/cmdref/clustermesh-apiserver_kvstoremesh/) — `--clustermesh-cache-ttl` (default `0s` means "never revoked"), `--global-ready-timeout` (default 10m).

package/skills/kubernetes/kubernetes-live-network-architecture-mutation-guard/references/permitted-mutations.md

@@ -0,0 +1,173 @@
+# Permitted mutations
+
+This is the explicit allowlist. Any mutation outside this list MUST be either rejected by the prompt rules OR refused by the cluster RBAC binding.
+
+## Service spec patches (low blast radius, reversible)
+
+### `internalTrafficPolicy` / `externalTrafficPolicy`
+
+Reversible field on `v1.Service`. Default is `Cluster`; `Local` constrains routing to node-local endpoints.
+
+```bash
+# Capture baseline
+kubectl get svc <name> -n <ns> -o yaml > /tmp/svc-<name>.before.yaml
+
+# Apply the patch
+kubectl patch svc <name> -n <ns> --type=merge \
+  -p '{"spec":{"externalTrafficPolicy":"Cluster"}}'
+
+# Verify EndpointSlices still serve the Service
+kubectl get endpointslice -n <ns> -l kubernetes.io/service-name=<name>
+
+# Rollback
+kubectl apply -f /tmp/svc-<name>.before.yaml
+```
+
+Refusal triggers inside this mutation type:
+- Setting `externalTrafficPolicy: Local` on a Service whose backend Pods are not present on every Node that the LoadBalancer health-check targets — blackhole risk.
+- Setting `internalTrafficPolicy: Local` on a Service consumed cluster-wide where backends are not co-located with consumers on every Node.
+
+### `service.kubernetes.io/topology-mode: Auto` annotation
+
+Annotation, additive. Only applies when `Service` is multi-zone with sufficient endpoints per zone.
+
+```bash
+kubectl annotate svc <name> -n <ns> \
+  service.kubernetes.io/topology-mode=Auto --overwrite
+```
+
+Rollback: `kubectl annotate svc <name> -n <ns> service.kubernetes.io/topology-mode-`
+
+### `spec.trafficDistribution` field (KEP-4444)
+
+Newer API; supersedes the annotation when both are set. Field-level patch on `v1.Service`.
+
+```bash
+kubectl patch svc <name> -n <ns> --type=merge \
+  -p '{"spec":{"trafficDistribution":"PreferClose"}}'
+```
+
+Rollback: `kubectl patch svc <name> -n <ns> --type=json -p='[{"op":"remove","path":"/spec/trafficDistribution"}]'`
+
+## CoreDNS Corefile patch (medium blast radius, reversible with backup)
+
+The CoreDNS `reload` plugin polls the Corefile every 30 seconds. If the new Corefile is invalid, CoreDNS rejects the reload and continues serving the previous config — but if the pod restarts for any other reason, it will fail to start. Always have a baseline.
+
+```bash
+# Capture baseline (CRITICAL — never skip)
+kubectl get cm coredns -n kube-system -o yaml > /tmp/coredns.before.yaml
+
+# Apply
+kubectl apply -f /tmp/coredns.new.yaml
+
+# Verify reload (look for "Reloading complete" in logs within 60 seconds)
+kubectl -n kube-system logs -l k8s-app=kube-dns --tail=50 --since=2m | grep -i "reload"
+
+# Verify no CrashLoopBackOff
+kubectl -n kube-system get pods -l k8s-app=kube-dns
+
+# If any pod is unhealthy — rollback
+kubectl apply -f /tmp/coredns.before.yaml
+```
+
+Refusal triggers:
+- New Corefile lacks the `reload` plugin (would prevent future zero-downtime updates).
+- New Corefile lacks the `loop` plugin (CoreDNS forward-loop detection).
+- New Corefile lacks the `health` plugin (liveness probe target removed).
+- New Corefile lacks the `kubernetes` plugin or its `pods insecure` mode set to anything other than the cluster's documented standard.
+- `forward .` target is changed to a private IP without confirming reachability from CoreDNS pod network.
+
+## NodeLocal DNSCache install / upgrade (medium blast radius, requires explicit human gate)
+
+Manifest from upstream `kubernetes/dns` repository (`nodelocaldns.yaml`). The install adds a `DaemonSet` and patches kube-proxy iptables / IPVS rules to redirect DNS traffic to the local cache. **This is a node-wide control-plane change**; refuse without an explicit human go-ahead even though the manifest itself is documented.
+
+```bash
+# Capture cluster DNS service IP for the manifest's __PILLAR__LOCAL__DNS__ token
+kubectl get svc -n kube-system kube-dns -o jsonpath='{.spec.clusterIP}'
+
+# Apply the upstream-rendered manifest (with values substituted)
+kubectl apply -f /tmp/nodelocaldns-rendered.yaml
+
+# Verify rollout — every Node must have a Ready node-local-dns pod within 5 minutes
+kubectl rollout status ds/node-local-dns -n kube-system --timeout=5m
+
+# Rollback (uninstall — high impact, plan before applying)
+kubectl delete -f /tmp/nodelocaldns-rendered.yaml
+```
+
+Refusal triggers:
+- Cluster does not run kube-proxy or Cilium kube-proxy replacement (NodeLocalDNS depends on a kube-proxy mode that supports the iptables / IPVS redirect).
+- The `DaemonSet` request lacks `resources.limits.memory` (NodeLocal DNSCache OOM is a known node-wide DNS outage).
+- The `DaemonSet` request lacks a `PodDisruptionBudget`.
+- Node selector excludes any node — partial DNS coverage is worse than none.
+
+## Gateway API resources (medium blast radius, reversible)
+
+### `Gateway` resource
+
+```bash
+# Pre-check: GatewayClass must reference a controller that is actually running
+GWC=$(yq '.spec.gatewayClassName' /tmp/gw.yaml)
+CONTROLLER=$(kubectl get gatewayclass $GWC -o jsonpath='{.spec.controllerName}')
+# Confirm controller pods are Ready before applying
+
+kubectl apply -f /tmp/gw.yaml
+kubectl wait --for=condition=Programmed gateway/<name> -n <ns> --timeout=2m
+
+# Status verification
+kubectl get gateway <name> -n <ns> -o jsonpath='{.status.conditions}'
+```
+
+Refusal triggers:
+- `GatewayClass` does not exist or its controller is not running.
+- `spec.allowedRoutes.namespaces.from: All` without an accompanying `ReferenceGrant` strategy — security boundary expansion.
+- `Listener` overlap on (port, protocol, hostname) with existing Gateway in same scope.
+
+### `HTTPRoute` / `GRPCRoute` / `TLSRoute`
+
+GA / Standard channel since Gateway API v1.1.0 (per `gateway-api.sigs.k8s.io/api-types/grpcroute`).
+
+```bash
+kubectl apply -f /tmp/route.yaml
+kubectl wait --for=condition=Accepted httproute/<name> -n <ns> --timeout=1m
+
+# Status verification — Accepted: True AND ResolvedRefs: True per parent
+kubectl get httproute <name> -n <ns> -o jsonpath='{.status.parents}'
+```
+
+Refusal triggers:
+- Route attaches to a Gateway that is not in `Programmed: True`.
+- `parentRefs` reference a Gateway in another namespace without a matching `ReferenceGrant`.
+
+### `ReferenceGrant`
+
+Cross-namespace authorization for routes. Always-additive; deletion can break in-flight routes.
+
+```bash
+kubectl apply -f /tmp/refgrant.yaml
+# No status conditions; verify by querying the route's ResolvedRefs.
+```
+
+## Cilium ClusterMesh peer Secret (medium blast radius, requires explicit human gate)
+
+Creates a `Secret` in the Cilium namespace whose data field carries the peer cluster's etcd client certificate, key, and CA. **Never log or print the data fields.**
+
+```bash
+# Capture baseline (confirm absence)
+kubectl get secret cilium-clustermesh -n kube-system 2>&1 | tee /tmp/clustermesh-pre.txt
+
+# Apply the peer secret — secret data is sensitive
+kubectl apply -f /tmp/clustermesh-peer.yaml
+
+# Verify ClusterMesh comes up
+kubectl exec -n kube-system ds/cilium -- cilium clustermesh status
+
+# Rollback
+kubectl delete secret cilium-clustermesh -n kube-system
+```
+
+Refusal triggers:
+- Secret destination namespace does not match the documented Cilium ClusterMesh namespace for this cluster.
+- Secret name does not exactly match the peer cluster identifier.
+- Secret data contains plaintext that looks like a CA or client key but is not properly base64-encoded for the `Secret` `data` field.
+- ClusterMesh peer `policy-default-local-cluster` flag has not been considered (delegate to `cilium-network-policy-review-agent`).