feat(CC-0090): Add NetworkPolicy for operator pod egress restriction

[berendt]

GitHub Issue #127: Add NetworkPolicy for operator pod egress restriction

Category: security | Scope: Small

Description: The NetworkPolicy sub-reconciler creates policies for Keystone API pods but not for the operator Deployment itself. Add a NetworkPolicy that restricts the operator pod's egress to only the Kubernetes API server and the namespaces it needs to communicate with.

Motivation: The operator pod currently has unrestricted network egress. If compromised, it could be used to reach arbitrary destinations. Restricting egress to only necessary endpoints reduces the blast radius.

Affected Areas (chart-level, opt-in via networkPolicy.enabled=true — CC-0090):

• operators/keystone/helm/keystone-operator/Chart.yaml — version bump 0.2.0 → 0.3.0 + changelog annotation
• operators/keystone/helm/keystone-operator/templates/networkpolicy.yaml — new NetworkPolicy template (REQ-001 — REQ-008)
• operators/keystone/helm/keystone-operator/values.yaml — new top-level networkPolicy key with kind defaults commented out (REQ-005)
• operators/keystone/helm/keystone-operator/values.schema.json — CIDR/port validation and enabled=true ⇒ kubeApiServer.{cidrs,ports} required fail-closed clause (REQ-005, REQ-006)
• operators/keystone/helm/keystone-operator/tests/networkpolicy_test.yaml — helm-unittest coverage for all render branches
• operators/keystone/helm/keystone-operator/tests/schema_validation_test.yaml — schema-level validation cases for the new key
• tests/e2e/keystone-operator/network-policy-egress/ — chainsaw E2E installing a second Helm release with networkPolicy.enabled=true (REQ-010, REQ-011); note: kindnet does not enforce NetworkPolicy, so this covers chart rendering + install-under-policy only, not packet-level enforcement
• tests/e2e-chaos/operator-pod-crash/chainsaw-test.yaml — adjusted to coexist with the new restricted release
• docs/reference/keystone-operator-networkpolicy.md, docs/how-to/enable-keystone-operator-networkpolicy.md, docs/reference/keystone-reconciler.md, docs/.vitepress/config.ts — reference + how-to docs and nav wiring (REQ-012, REQ-013)

Note: the per-CR reconciler operators/keystone/internal/controller/reconcile_networkpolicy.go is not modified — this PR hardens the operator pod itself via a chart-level NetworkPolicy, which is orthogonal to the per-Keystone-CR NetworkPolicies that reconciler continues to manage.

Acceptance Criteria:

• NetworkPolicy restricts operator pod egress to kube-apiserver CIDR
• DNS egress to kube-dns is permitted
• Operator functions correctly with the restricted policy
• E2E tests pass with the NetworkPolicy applied (chart-render + install-under-policy scope; see caveat above)

---

Source: #127

[berendt]

Reviewed by planwerk-review a716ce1 with Claude Code

WARNING (2)

W-001: Chart.yaml artifacthub.io/changes not updated for CC-0090 and chart version not bumped

File: operators/keystone/helm/keystone-operator/Chart.yaml:7-13 — Fix: AUTO-FIX — Confidence: verified — Pattern: Helm Chart Structure Conventions

Problem: CC-0090 introduces a significant new chart feature (opt-in NetworkPolicy for operator pod hardening) and a new top-level values key (networkPolicy). The artifacthub.io/changes annotation is not updated, so Artifact Hub consumers will not see the new feature advertised. The chart version (0.2.0) is also not bumped despite the chart surface growing with a new top-level key.

Code:

version: 0.2.0
appVersion: "0.1.0"
# CC-0069, REQ-007: Helm validates values against values.schema.json automatically.
annotations:
  artifacthub.io/prerelease: "true"
  artifacthub.io/changes: |
    - kind: added
      description: JSON Schema validation for chart values (CC-0069)

Action Required: Add a new changelog entry for CC-0090 to artifacthub.io/changes and bump the chart version from 0.2.0 to 0.3.0 since the chart surface grew (new top-level key).

Suggested Fix:

version: 0.3.0
appVersion: "0.1.0"
# CC-0069, REQ-007: Helm validates values against values.schema.json automatically.
annotations:
  artifacthub.io/prerelease: "true"
  artifacthub.io/changes: |
    - kind: added
      description: JSON Schema validation for chart values (CC-0069)
    - kind: added
      description: Opt-in NetworkPolicy for operator pod egress/ingress restriction (CC-0090)

---

W-002: E2E test cannot exercise NetworkPolicy enforcement on kindnet CI cluster

File: tests/e2e/keystone-operator/network-policy-egress/chainsaw-test.yaml:30-99 — Fix: ASK — Confidence: verified — Pattern: Detect no-op retry/wait loops; Verify benchmarks measure what acceptance criteria claim

Problem: The CI kind cluster uses default kindnet, which does not enforce NetworkPolicy. The E2E test only asserts that (a) the NetworkPolicy resource is created and (b) a Keystone CR reaches Ready=True. On kindnet these pass vacuously with respect to enforcement — the policy is rendered but has no effect, so cidrs: [10.96.0.1/32] is never actually tested for correctness. Moreover, 10.96.0.1/32 is the in-cluster Service VIP; on Calico/Cilium the packet is DNAT'd before policy evaluation, meaning this CIDR would be wrong on most enforcing CNIs. Additionally, the two-operator leader-election topology (primary installed by hack/ci-deploy-operator.sh, secondary by the test) competes for the same LeaderElectionID across different namespaces, so there is no guarantee the restricted operator is the one reconciling the CR in Step 4.

Code:

networkPolicy:
  enabled: true
  kubeApiServer:
    cidrs:
      - 10.96.0.1/32   # Service VIP, not actual endpoint
    ports:
      - 6443

Action Required: Choose between: (A) add an explicit assertion in Step 4 that the keystone-operator-netpol pod is the one that transitioned the CR to Ready (e.g. scrape operator logs for the CR UID); (B) accept the limitation and add an inline comment at the top of chainsaw-test.yaml stating the test validates chart rendering/Helm install, not NetworkPolicy enforcement (requires Calico/Cilium); or (C) file a follow-up ticket to provision a Calico-enabled kind cluster in a dedicated CI job for enforcement tests.

Suggested Fix:

Add an explicit comment at the top of chainsaw-test.yaml clarifying that this test validates chart rendering and Helm install under kindnet (non-enforcing CNI), not actual NetworkPolicy enforcement; optionally add a Step 4 assertion that the restricted operator pod is the one reconciling the CR, and open a follow-up ticket for a Calico-enabled kind CI job.

---

INFO (2)

I-001: PR description 'Affected Areas' references unmodified reconciler file

File: PR description — Fix: ASK — Confidence: verified

Problem: The PR description lists operators/keystone/internal/controller/reconcile_networkpolicy.go under 'Affected Areas', but the PR does not modify that file. The author chose a chart-level approach (Helm template) instead of extending the per-CR reconciler (CC-0039). This is a reasonable and explicitly justified choice (documented in the reference doc), but the PR description misrepresents the final scope.

Code:

**Affected Areas:** `operators/keystone/internal/controller/reconcile_networkpolicy.go`

Action Required: Update the PR description's 'Affected Areas' section to reflect the actual chart-level scope: operators/keystone/helm/keystone-operator/templates/networkpolicy.yaml, tests/, values.{yaml,schema.json}, and tests/e2e/keystone-operator/network-policy-egress/.

Suggested Fix:

Rewrite the 'Affected Areas' section to list: operators/keystone/helm/keystone-operator/templates/networkpolicy.yaml, operators/keystone/helm/keystone-operator/values.yaml, operators/keystone/helm/keystone-operator/values.schema.json, tests/e2e/keystone-operator/network-policy-egress/, plus related unit/chainsaw test files.

---

I-002: IPv6 CIDR schema pattern is structurally lax

File: operators/keystone/helm/keystone-operator/values.schema.json:21-24 — Fix: ASK — Confidence: verified

Problem: The IPv4 half of the CIDR regex is rigorous (octets 0-255, prefix 0-32), but the IPv6 half is [0-9a-fA-F:]+, which accepts any non-empty run of hex digits and colons. Malformed forms like : alone or 1:2:3:4:5:6:7:8:9/32 (too many groups) pass. The schema comment frames this as 'surface obvious typos' rather than full validation, so it is documented intent — but the stated goal of catching issues at helm render time rather than opaque kubectl admission errors is only partially achieved for IPv6.

Code:

"cidr": {
  "description": "IPv4 or IPv6 CIDR block (e.g., '10.96.0.1/32', '2001:db8::/32'). IPv4 octets are bounded 0-255 to surface obvious typos (e.g. '999.0.0.1/32') at helm render time rather than as opaque kubectl apply admission errors (CC-0090, REQ-005).",
  "type": "string",
  "pattern": "^(((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)/([0-9]|[12][0-9]|3[0-2])|[0-9a-fA-F:]+/([0-9]|[1-9][0-9]|1[01][0-9]|12[0-8]))$"
}

Action Required: Consider tightening the IPv6 half of the pattern in a future change to reject malformed forms (too many groups, lone colon, etc.). Not a defect; noted for future tightening.

Suggested Fix:

In a future iteration, replace the IPv6 half of the pattern with a stricter alternation that enforces valid group counts (e.g. a standard RFC-4291-compatible IPv6 regex), or document that IPv6 is intentionally loosely validated and rely on kubectl admission for final checks.

---

Summary

High-quality PR with a well-reasoned chart-level design (instead of per-CR reconciler), thorough schema and helm-unittest coverage with comprehensive fail-closed defense-in-depth guards, and exemplary documentation (reference doc, how-to, cross-references, sidebar updates). The most substantive gap is that the Chainsaw E2E test cannot exercise actual NetworkPolicy enforcement on kindnet, making it closer to a smoke test — this matches CC-0039 precedent and is acknowledged in the how-to, but the test itself would benefit from explicit comment or a CNI follow-up. Minor cleanups remain: the Chart.yaml artifacthub.io/changes annotation and chart version bump were missed, and the PR description's 'Affected Areas' names a reconciler file that wasn't modified.

Severity	Count
BLOCKING	0
CRITICAL	0
WARNING	2
INFO	2

Important

Recommendation: Merge after applying the auto-fix for Chart.yaml (changelog annotation + version bump) and updating the PR description. The E2E-enforcement gap and IPv6 schema laxity are acceptable as-is given documented intent and precedent, but should be tracked as follow-ups.