Skip to content

Install the reviewer on any Kubernetes cluster - #425

Merged
artyomsv merged 7 commits into
masterfrom
feat/k8s-any-cluster
Nov 15, 2026
Merged

artyomsv merged 7 commits into
masterfrom
feat/k8s-any-cluster

Conversation

@artyomsv

Copy link
Copy Markdown
Owner

Part of #391.

Lets anyone install the reviewer (gateway, orchestrator, review worker, dashboard) on any Kubernetes cluster
with the Helm chart, with no hand patch: external Postgres such as CloudNativePG, an external identity
provider, and no ingress controller. Agent work (the run worker) is out of scope until M5.

Design: docs/superpowers/specs/2026-11-15-k8s-any-cluster-design.md (revised after a design review).

What changes

  • Chart values:
    • ui.service (type, annotations, loadBalancerSourceRanges).
    • extraEnv and extraEnvFrom per service.
    • postgres.passwordSecret and postgres.gatewayPasswordSecret, so a password can come from any Secret,
      such as a CloudNativePG one.
    • storageClass for the bundled Postgres and Redpanda.
    • image.tag empty by default, which falls back to the chart's appVersion, so a release chart pulls its
      own release. The kustomize inputs pin edge, so deploy/k8s does not drift.
  • Render refusals, each with a render.sh --self-test case:
    • an extraEnv name that the chart already sets;
    • any way the master keyset or the main Secret could reach the gateway;
    • a half-filled password reference;
    • an unknown Service type.
  • CloudNativePG example: deploy/examples/cloudnative-pg/. The gateway managed role and schema come
    from a Database object, not from postInitApplicationSQL. kubeconform checks it in manifests.yml.
  • Production realm template: deploy/keycloak/realm-spire-production.json, with the three reviewer
    clients, no users, no secrets, no localhost, no wildcards and no direct grants.
    ProductionRealmTemplateIsSafeTest in spire-arch checks it.
  • Docs:
    • a "Install on any cluster" section in deploy/README.md, with checks for a real cluster;
    • TLS.md updated for a terminator inside the cluster;
    • new entries in UNVERIFIED.md and HISTORY.md;
    • a tech-debt entry for the missing NetworkPolicy.

Tests

CI only. No local build was run.

  • A local helm template (Helm 3.21.3) rendered both presets the same as the committed deploy/k8s.
  • Each refusal was triggered by hand with helm template.
  • The new render.sh assertions and the Java test run first in CI.

Not proven

  • No real cluster has run this install yet.
  • The CloudNativePG example has not run.
  • It is not proven that Keycloak generates client secrets on import.
  • The home install is the first live proof. These are recorded in docs/UNVERIFIED.md.

A reviewer-only install on a cluster with CloudNativePG Postgres, no
ingress controller and an external identity provider needed hand
patches. The chart now models what that install needs, and every
default renders exactly today's manifests (deploy/k8s does not drift):

- ui.service: type, annotations and loadBalancerSourceRanges for the
  dashboard Service, so it can leave the cluster through values. Ranges
  render only for a LoadBalancer.
- <service>.extraEnv / extraEnvFrom on the four services. The render
  fails on a name the chart already sets (read from the rendered env
  itself), and on the gateway for SPIRE_ENCRYPTION_KEYSET or any
  reference to the main Secret, which holds the master keyset.
- postgres.passwordSecret / gatewayPasswordSecret: read each database
  password from any Secret and key, such as a CloudNativePG basic-auth
  Secret, so a password lives once. Half a reference, or the gateway's
  password from the main Secret, is refused.
- kafka.storageClass and postgres.storageClass for the bundled PVCs.
- image.tag empty falls back to the chart's appVersion, so a chart
  packaged at a release pulls that release. The kustomize inputs, which
  also drive deploy/k8s, set edge explicitly.

deploy/examples/cloudnative-pg holds a Cluster with the managed role
gateway, a Database object that makes the gateway schema (post-init SQL
runs before managed roles exist), and values that render with no --set.
render.sh asserts the new values set and unset, the example's shape,
and that only spire-ui may be external; --self-test renders each
refused shape and requires the refusal's own message. kubeconform
checks cluster.yaml against the CloudNativePG CRD schemas.

Part of #391
The dev realm is the only realm in the repository, and copying it to a
real identity provider brings its users, client secrets, password grant,
plaintext localhost redirect URIs and wildcard post-logout URIs with it.

realm-spire-production.json holds the three reviewer clients with their
audience mappers and the two realm roles, with SPIRE_REALM and
SPIRE_HOST as placeholders: https only, one exact callback per client,
sslRequired external, no users, no secrets, no password grant. The run
worker's client is left out until M5 brings the run worker to
Kubernetes.

ProductionRealmTemplateIsSafeTest (spire-arch, testFast) holds each of
those points and compares the clients and roles with the dev realm's
minus spire-run-worker, so a client the dev realm gains must reach the
template too. It reads JSON with a small strict reader so spire-arch
still depends on nothing but JUnit.

Part of #391
deploy/README.md gets one ordered section, "Install on any cluster":
namespace, Postgres (bundled, external or CloudNativePG), the two
Secrets and their keys, the realm from the template with Regenerate on
each client, helm install with the example values, the terminator, and
the checks to run by hand, because deploy/e2e.sh needs the dev realm's
users and docker compose. It also says no NetworkPolicy is shipped.

docs/TLS.md replaces the kubectl patch advice with chart values and
keeps an in-cluster terminator as the first choice; the nginx proxy
manager table gains the in-cluster forward target. UNVERIFIED.md
records what no install has shown yet, HISTORY.md the delivery, and a
techdebt entry the missing NetworkPolicy.

Part of #391
A 187-line JSON reader in a test was more code to review than the
check it served. spire-arch now takes jackson-databind 2.22.4, the
version the root build already pins, as a test-only dependency. It is
an external library, so the module still depends on no other project
module.

Part of #391
@artyomsv artyomsv added the review: requested the code waits for a reviewer label Nov 15, 2026

@artyomsv artyomsv left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

First review at eb42e87. The chart changes are careful: the gateway password reference may never name the main Secret, a half-filled reference fails, extraEnv may only add names (read from the rendered list, not a second hand-kept list), the gateway refuses the master keyset by name and by a reference to the main Secret in extraEnv and extraEnvFrom, the Service type is checked, and the kustomize inputs pin edge so deploy/k8s does not drift. The realm template matches the dev realm's clients and roles (minus the run worker, which is out of scope), is confidential with no password grant, exact https callbacks, no users and no secrets, and the arch test that guards it is declared as a Gradle input so a cached PASS cannot hide an edit. The not-proven parts (no real cluster, the CloudNativePG example, Keycloak making secrets on import) are written down in UNVERIFIED.md and the README. PR CI is green. I found no defect. One LOW suggestion.

Findings: 1 LOW. Reviewed head eb42e87825 as @artyomsv.

@artyomsv artyomsv left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ APPROVED

Posted as a comment: GitHub does not let an account approve or request changes on its own pull request. The label carries the verdict.

Agent findings: 0 resolved, 1 open. CI: 13/14 checks passing. Head eb42e87825, reviewed by @artyomsv.

Open findings:

@artyomsv artyomsv added review: approved Agent review verdict: approved and removed review: requested the code waits for a reviewer labels Nov 15, 2026
The gateway guards refused the main Secret but accepted the Secret named
by postgres.passwordSecret, so extraEnv, extraEnvFrom or the gateway's own
password reference could hand the internet-facing edge the owner's
password (ADR-015). Refuse all three, each with a self-test case.

Part of #391
@artyomsv artyomsv added review: requested the code waits for a reviewer and removed review: approved Agent review verdict: approved labels Nov 15, 2026

@artyomsv artyomsv left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ APPROVED

Posted as a comment: GitHub does not let an account approve or request changes on its own pull request. The label carries the verdict.

Agent findings: 1 resolved, 0 open. CI: 13/14 checks passing. Head 29310b7c52, reviewed by @artyomsv.

@artyomsv artyomsv added review: approved Agent review verdict: approved and removed review: requested the code waits for a reviewer labels Nov 15, 2026

@code-spire-beaver code-spire-beaver left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the full PR and the follow-up at 29310b7 against 0192ca6 across security, correctness, repository rules and tests. No new actionable findings. The existing sec/L-1 finding is fixed by the owner-Secret guards, with three passing CI regression cases. Real-cluster installation with CloudNativePG and an external identity provider remains explicitly unverified.

Findings: none. Reviewed head 29310b7c52 as @code-spire-beaver.

@code-spire-beaver code-spire-beaver left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ APPROVED

Reviewed 29310b7c52657f1fefafb20554fd8d8e8cc8f2b5 against 0192ca6fa18268bf53885ec79825ba679c664e5d (global/k8s-any-cluster), including the full original change and the follow-up Secret guards. No new actionable findings.

The existing sec/L-1 finding is fixed: the gateway refuses the database owner's Secret through extraEnv, extraEnvFrom and its password reference. All three new cases passed in CI and assert the refusal's own message.

  • Security: checked master/webhook key separation, database password references and role isolation, gateway environment guards, the production realm's confidential clients, exact HTTPS callbacks, audience/role mappings and absence of users or credentials. The existing NetworkPolicy gap is documented and outside this change. Semgrep ran 144 rules on 22 changed files and 442 rules on 1,735 files in the full scan, with zero findings; CodeQL and gitleaks passed.
  • Correctness: traced the password helpers through all consumers, service-specific environment rendering, UI Service types/source ranges, storage classes, appVersion fallback, explicit edge pins and the external-Postgres example. CloudNativePG 1.26 documents both schema ownership and adoption of existing databases, matching the example's approach (official documentation). This is a source check, not a claim that the example has run live.
  • Rules: applied root CLAUDE.md and the matching global rules. Checked Java method/class/parameter limits, existing architecture-test conventions, source-derived client/role lists, synthetic fixtures, documentation boundaries, debt tracking and all seven commit messages. No nested CLAUDE.md, project rule files or matching prior review-state file were present; the prescribed memory locations were absent.
  • Tests: checked positive/default/custom renders, the appVersion mutation, exact-message negative cases, service isolation and the production realm checks. The two realm JSON files are declared Gradle inputs so changes invalidate the architecture-test cache. The new guard cases would fail before the follow-up.

CI evidence at the reviewed head: CI run 43720747809 passed fast tests, service tests and packaging, dashboard type checking, all 1,342 UI tests in 127 files, and the UI build. The Gradle logs do not publish Java test totals, so none are claimed. Manifest run 43720747830 passed the render checks, all 23 self-check assertions, rendered-manifest drift and the simple-preset kind install; kubeconform validated 30 resources in three files with zero invalid, errored or skipped resources. CodeQL, Semgrep and gitleaks also passed. The only skipped check was the Dependabot merge job.

Applicable global rules: clean-code-general.md, clean-code-java.md, secrets-and-env-handling.md, observability-and-logging.md, documentation-maintenance.md, blog-material-capture.md, tech-debt-tracking.md, reference-pattern-adoption.md, git-workflow.md, no-synthetic-data.md, no-local-builds.md and pr-review-labels.md. The user's commit instructions take precedence over the generic conventional-commit template.

Residual limits: CI's live install uses the simple preset on kind. The external-Postgres/external-identity-provider install, CloudNativePG example and automatic client-secret generation on realm import are not live-proven. The README requires explicit secret regeneration and records manual acceptance checks; UNVERIFIED.md retains those limits. No local builds, test suites or linters were run, and the working tree was not changed.

Agent findings: 1 resolved, 0 open. CI: 13/14 checks passing. Head 29310b7c52, reviewed by @code-spire-beaver.

@artyomsv
artyomsv merged commit 0e6fbde into master Nov 15, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review: approved Agent review verdict: approved

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants