pal-e-docs

Review: Create kustomize overlay in pal-e-deployments

review-594-2026-03-28 Doc

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — Standalone, scoped from westside-ai-assistant design spec (2026-03-28)
  • [x] Repo — forgejo_admin/pal-e-deployments
  • [x] User Story — Marcus (admin) wants kustomize overlay so ArgoCD can deploy the AI assistant
  • [x] Context — Explains standard base pattern, references basketball-api/prod as model
  • [x] File Targets — 3 files to create, exclusion list present
  • [x] Acceptance Criteria — 6 criteria
  • [x] Test Expectations — kustomize render + dry-run commands provided
  • [x] Constraints — Pattern reference, Harbor URL, port, no secret data in git
  • [x] Checklist — PR opened, kustomize renders, no unrelated changes
  • [x] Related — project page + convention reference
All required Feature template sections are present and filled.

Traceability

  • [x] story:read-ops — present on board item
  • [x] story:write-ops — present on board item
  • [x] arch:A4 — present on board item (infrastructure/deployment component)
  • [x] Forgejo issue — forgejo_admin/westside-ai-assistant#2, open

File Targets

  • [x] overlays/westside-ai-assistant/prod/kustomization.yaml — NEW file. Parent directory does not exist yet (expected for new service overlay). Reference pattern at overlays/basketball-api/prod/kustomization.yaml verified: exists, contains base ref, JSON6902 rename patches, images transformer.
  • [x] overlays/westside-ai-assistant/prod/deployment-patch.yaml — NEW file. Reference at overlays/basketball-api/prod/deployment-patch.yaml verified: exists, contains env vars via individual env[].valueFrom.secretKeyRef entries, volumes, strategy override.
  • [x] overlays/westside-ai-assistant/prod/harbor-creds.enc.yaml — NEW file. Reference at overlays/basketball-api/prod/harbor-creds.enc.yaml verified: exists, SOPS-encrypted with age key.
  • [x] bases/standard/* — exclusion verified. Standard base exists at expected path with deployment.yaml (name: app, port 8000, /healthz probes), service.yaml (name: app, port 8000), kustomization.yaml. No changes needed.
Targets are specific enough for an agent to act on. The reference pattern is fully verified.

Repo Placement

Cross-repo issue placement: The Forgejo issue lives on forgejo_admin/westside-ai-assistant but work targets forgejo_admin/pal-e-deployments. The issue body correctly declares ### Repo: forgejo_admin/pal-e-deployments. This is acceptable for project-scoped tracking (issue stays with the project, PR goes to the target repo). However, the issue body lacks an explicit instruction telling the agent to open the PR on pal-e-deployments and cross-reference westside-ai-assistant#2. Single-repo change — no additional Forgejo issues needed.

Dependencies

  • [ ] Board item #593 (Provision infrastructure in pal-e-services) — PENDING, not documented in issue. This creates the Harbor project, namespace, and ArgoCD Application. Without it: (a) no Harbor project for the image reference, (b) no namespace for kubectl apply --dry-run=server to validate against, (c) no ArgoCD Application to consume the overlay. The Woodpecker CI pipeline runs server-side dry-run against the live cluster — it will fail if the namespace doesn't exist. This is a hard blocker for AC #6 (CI pipeline passes).
  • [x] Board item #595 (NetworkPolicy update in pal-e-platform) — independent of overlay creation. Not a blocker.
  • [x] SOPS age key — required for encrypting harbor-creds.enc.yaml. Available on the host but agent must have access. Not documented as a constraint.

Acceptance Criteria

6 criteria evaluated:
  • [x] AC1: kubectl kustomize overlays/westside-ai-assistant/prod/ renders valid manifests — testable, command provided
  • [x] AC2: Deployment named westside-ai-assistant with port 8000 — verifiable by inspecting rendered YAML
  • [x] AC3: Service named westside-ai-assistant with port 8000 — verifiable by inspecting rendered YAML
  • [ ] AC4: "Env vars set for all config, secrets referenced via envFrom secretRef" — contradicts established pattern. The basketball-api reference uses individual env[].valueFrom.secretKeyRef entries, not envFrom. The convention-kustomize-overlay doc says "Env vars: Strategic merge patch in deployment-patch.yaml." The AC is ambiguous about which pattern to follow.
  • [x] AC5: harbor-creds.enc.yaml is SOPS-encrypted — verifiable by checking for ENC[] markers
  • [ ] AC6: Woodpecker CI validation pipeline passes — depends on #593 completing first (namespace must exist for server-side dry-run). The CI pipeline at .woodpecker.yaml validates ALL overlays, so a broken new overlay would block all other PRs too.

Blast Radius

  • CI pipeline scope: The Woodpecker CI pipeline iterates all overlays/*/prod/ directories. A malformed new overlay would fail the entire validation step and block all other pal-e-deployments PRs. Risk is low since kustomize render is the first gate and catches most errors before server-side dry-run.
  • No downstream consumers: No existing services reference westside-ai-assistant. No cross-namespace network policies point to it yet (that's board item #595).
  • Rollback: Straightforward — delete the overlay directory. ArgoCD won't have an Application pointing to it until #593 completes.

Decomposition Assessment

Apply the three-thing limit and five-minute rule:
  • File count: 3 new files in 1 repo — within the three-thing limit.
  • AC count: 6 acceptance criteria — borderline but 4 are simple YAML inspection checks.
  • Estimated agent time: ~3 minutes. This is a templated copy-adapt from a verified reference pattern (basketball-api/prod). The agent copies 3 files, changes names/env vars/image refs. Well within 5-minute rule.
  • Independent subtasks: None — the 3 files are tightly coupled (kustomization.yaml references the other two).
No decomposition needed.

Recommendation

  • [BODY] Add dependency: "Depends on westside-ai-assistant#1 (Provision infrastructure in pal-e-services) — namespace and Harbor project must exist before CI server-side dry-run can pass."
  • [BODY] Fix Harbor image URL in Constraints: change harbor-core.harbor.svc.cluster.local to harbor.tail5b443a.ts.net. All existing overlays and the convention-kustomize-overlay doc use the external Tailscale URL. The internal URL would fail image pulls from outside the Harbor namespace.
  • [BODY] Clarify secret injection pattern in AC4: change "secrets referenced via envFrom secretRef" to "secrets referenced via individual env[].valueFrom.secretKeyRef entries (matching basketball-api pattern)." The envFrom approach is valid Kubernetes but diverges from the established codebase convention.
  • [BODY] Add agent instruction to Constraints: "Open PR on forgejo_admin/pal-e-deployments. Reference westside-ai-assistant#2 in PR body."