pal-e-docs

Review: Add KEYCLOAK_* env vars to paldocs deployment

review-1704-2026-07-03 Review

review ready
Project

Verdict: READY

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- Related to paldocs #26 and #28
  • [x] Repo -- ldraney/pal-e-deployments
  • [x] User Story -- As the paldocs Rails app / Keycloak connection details / OmniAuth OIDC
  • [x] Context -- References landscaping-assistant pattern, identifies 4 KEYCLOAK_* keys
  • [x] File Targets -- 1 modify target, 1 reference-only exclusion
  • [x] Feature Flag -- none (appropriate for infra wiring)
  • [x] Acceptance Criteria -- 4 items, all verifiable
  • [x] Test Expectations -- kubectl describe + kustomize build
  • [x] Constraints -- Pattern reference, manual secret step, dependency on #26
  • [x] Checklist -- Standard PR/tests/no-unrelated
  • [x] Related -- pal-e-docs project reference

Traceability

  • [x] story:auth label -- role-based access control via Keycloak
  • [x] story note verified -- story-paldocs-auth exists in project paldocs, listed on project-paldocs user-stories section
  • [x] arch:k8s label -- Kubernetes (k3s) container orchestration
  • [x] arch note verified -- arch-k8s note exists (id: 2039, status: active)
  • [x] Forgejo issue -- ldraney/pal-e-deployments#224, state: open

File Targets

  • [x] overlays/paldocs/prod/deployment-patch.yaml -- verified: file exists, currently has 3 env vars (RAILS_ENV, SECRET_KEY_BASE, PALDOCS_DATABASE_URL), no KEYCLOAK_* vars yet (expected)
  • [x] overlays/landscaping-assistant/prod/deployment-patch.yaml -- verified: reference pattern exists with KEYCLOAK_URL, KEYCLOAK_REALM, KEYCLOAK_CLIENT_ID, KEYCLOAK_CLIENT_SECRET using secretKeyRef (lines 62-81 for initContainer, lines 134-153 for app container)

Repo Placement

Correct. Issue filed on pal-e-deployments, file targets are in pal-e-deployments. Single-repo change. No cross-repo work needed.

Dependencies

  • Depends on paldocs #26 (Keycloak client via Terraform) -- board item #1387, backlog. Explicitly documented in Constraints section. Must complete first to provide the client secret value.
  • Related to paldocs #28 (Rails OIDC integration) -- board item #1389, backlog. Downstream consumer of these env vars.
  • NetworkPolicy ticket #1708 (pal-e-platform #491) -- sprint:3, backlog. Ensures paldocs pods can reach Keycloak. Does not block this ticket but both must be done for auth to function end-to-end.
  • Manual step: paldocs-secrets k8s secret must be updated with KEYCLOAK_* values after #26 provisions the client. Documented in Constraints.

Acceptance Criteria

4 criteria, all verifiable. First two (env vars added, correct secretKeyRef) are code-review-verifiable. Last two (pod restart, kubectl exec) require the paldocs-secrets secret to contain the KEYCLOAK_* keys, which depends on paldocs #26. This is properly documented in the Constraints section. Test expectation uses kustomize build -- note that standalone kustomize is not on PATH, but kubectl kustomize succeeds. Agent should use kubectl kustomize instead.

Blast Radius

Minimal. 4 other services already use this exact KEYCLOAK_* env var pattern (basketball-api, landscaping-assistant, westsidekingsandqueens, pal-enterprises). The pattern is proven and well-established across the platform. Adding env vars to a deployment patch has no downstream side effects -- the vars are only consumed by the Rails app's OmniAuth configuration.

Decomposition Assessment

No decomposition needed. 1 file target, 4 acceptance criteria, estimated agent work under 2 minutes. This is a copy-and-adapt from the landscaping-assistant pattern: add 4 env var blocks referencing paldocs-secrets instead of landscaping-assistant-secrets.

Recommendation

No action needed. Ticket is well-scoped and ready for execution.