pal-e-docs

Review 2: feat: add overlays/notion-mcp-remote/prod kustomize overlay

review-1044-2026-04-21-v2 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Re-review of board item #1044 (Forgejo forgejo_admin/pal-e-deployments#132) after refinement. Six of seven fixes from review-1044-2026-04-21 landed cleanly. One new issue found: the remote-base kustomize URL uses single-slash form, which kustomize cannot parse -- it requires // as the separator between git repo root and subpath. This will fail at kubectl kustomize time.

Template Completeness

  • [x] Type (Feature)
  • [x] Lineage
  • [x] Repo
  • [x] User Story
  • [x] Context
  • [x] File Targets
  • [x] Acceptance Criteria
  • [x] Test Expectations
  • [x] Constraints
  • [x] Checklist
  • [x] Related

Verification of Prior Fixes

# Fix Requested Landed? Evidence
1 Base factoring: remote base referencing service repo's <code>k8s/</code> YES Context explicitly picks remote-base pattern, gives URL, rejects <code>bases/standard/</code>. File Targets "Files NOT to touch" excludes <code>bases/notion-mcp-remote/</code>.
2 Remove envFrom; base uses <code>valueFrom: secretKeyRef: name: notion-mcp-secrets</code> YES Context "Secrets" subsection states base already wires env via <code>valueFrom: secretKeyRef: name: notion-mcp-secrets</code> with kebab-case keys and instructs overlay not to override. AC includes "Overlay does not redefine env vars or <code>envFrom</code>".
3 Name sibling ticket #7 / board #1047 explicitly YES Context names <code>forgejo_admin/notion-mcp-remote#7</code> (board item #1047); Related section repeats it.
4 Remove <code>ingress.yaml</code> (Funnel via pal-e-services terraform) YES Context "Ingress" subsection states Funnel is provisioned by pal-e-services terraform and forbids <code>ingress.yaml</code>. No <code>ingress.yaml</code> in File Targets.
5 Replace <code>newTag: latest</code> with hex SHA YES (placeholder) File Targets specifies "a bootstrap <code>newTag</code> of a real commit SHA (placeholder <code>&lt;7-40 hex chars, first SHA from notion-mcp-remote main&gt;</code>)"; Checklist requires SHA matching <code>^[0-9a-f]{7,40}$</code>, not <code>latest</code>.
6 AC adjustments: drop envFrom AC, drop container-port AC, add images: transformer AC YES envFrom AC removed; container-port AC removed; new AC for <code>images:</code> transformer with <code>name: harbor.tail5b443a.ts.net/notion-mcp-remote/notion-mcp-remote</code> and SHA <code>newTag</code>.
7 Body references <code>convention-kustomize-overlay</code> and <code>arch-deployment-notion-mcp-remote</code> YES Lineage cites <code>convention-kustomize-overlay</code>; Context cites <code>arch-deployment-notion-mcp-remote</code>; both listed in Related.

Traceability

  • [x] story:ops-deploy-gitops label -- verified present on board item; story entry in project-notion-mcp-remote user-stories
  • [x] arch:kustomize-overlay label -- present; backing note is convention-kustomize-overlay. Prior review noted [SCOPE] ambiguity (convention vs arch); not blocking this review.
  • [x] type:feature label matches Type header
  • [x] Forgejo issue open (forgejo_admin/pal-e-deployments#132)

File Targets

  • [x] overlays/notion-mcp-remote/prod/kustomization.yaml -- new file; parent path aligns with sibling overlays (overlays/pal-e-docs/prod/, etc.)
  • [x] overlays/notion-mcp-remote/prod/deployment-patch.yaml -- new file; standard overlay pattern per convention-kustomize-overlay
  • [x] Remote base source verified: forgejo_admin/notion-mcp-remote/k8s/ on main contains deployment.yaml, service.yaml, pvc.yaml, servicemonitor.yaml, kustomization.yaml. Base deployment image: harbor.tail5b443a.ts.net/notion-mcp-remote/notion-mcp-remote:latest. Base secret wiring uses valueFrom: secretKeyRef: name: notion-mcp-secrets with kebab-case keys. All matches issue body claims.

New Issue: Remote-Base URL Format (BLOCKER for dev agent)

The issue body specifies the remote kustomize resources: URL as:
Kustomize's remote-source syntax requires a // separator between the git repository URL and the subdirectory within the repo. With single-slash form, kustomize will either try to clone .../notion-mcp-remote.git/k8s as the repo URL (fails) or parse the entire path as the repo with no subpath. Sibling overlays in pal-e-deployments don't use remote bases (they use filesystem paths ../../../bases/standard), so there's no in-repo exemplar, but kustomize behaviour is consistent on this.
Correct form:
Note the .git//k8s (double slash). This syntax is required for kubectl kustomize overlays/notion-mcp-remote/prod/ to render clean, which is AC #1. Without this fix, the dev agent will either (i) hit a render error, (ii) "fix" the URL themselves and guess, or (iii) silently use a different factoring. One-character BODY edit avoids all three.

Sanity Check: images Transformer vs Real Harbor Path

Base deployment (fetched from notion-mcp-remote/k8s/deployment.yaml on main) uses image harbor.tail5b443a.ts.net/notion-mcp-remote/notion-mcp-remote:latest.
AC specifies images transformer with name: harbor.tail5b443a.ts.net/notion-mcp-remote/notion-mcp-remote. Matches exactly. Because the overlay consumes the base directly (not via name: app placeholder as in bases/standard), only ONE images entry is needed (not two as in overlays/pal-e-docs/prod/, which needs both app-image and the Harbor URL). AC correctly reflects this.

Repo Placement

Correct. Issue filed on pal-e-deployments, all File Targets under overlays/notion-mcp-remote/prod/*.

Dependencies

  • [pending] Sibling secret-provisioning ticket -- forgejo_admin/notion-mcp-remote#7 (board item #1047) must create Secret notion-mcp-secrets with keys base-url, oauth-client-id, oauth-client-secret, session-secret, onboard-secret. Not blocking overlay merge (inert until ArgoCD syncs).
  • [pending] Downstream -- pal-e-platform#296 (board item #1045) creates ArgoCD Application.
  • [pending] Downstream -- pal-e-services#57 (board item #1043) adds var.services entry with source_path = "overlays/notion-mcp-remote/prod". Overlay path is contractual with this ticket.
  • All dependencies documented in Context and Related sections of the issue body.

Acceptance Criteria

  • AC #1 (kubectl kustomize renders clean) -- achievable ONCE the // URL fix lands. Network access to tailnet required to fetch remote base.
  • AC #2 (resources: references service repo k8s/ pinned to main) -- testable via file inspection.
  • AC #3 (images: transformer with correct name + SHA-regex newTag) -- testable via file inspection + regex.
  • AC #4 (Image Updater annotations present in kustomization.yaml) -- AMBIGUOUS. Per convention-kustomize-overlay "Terraform Integration", Image Updater annotations live on the ArgoCD Application (provisioned by pal-e-services terraform with source_repo set), not on the overlay's kustomization.yaml. The overlay's role is to expose images: entries that Image Updater rewrites (plus write-back-target: kustomization on the Application). Inspection of overlays/pal-e-docs/prod/kustomization.yaml confirms: no Image Updater annotations in the overlay. AC #4 as written may be unachievable in a literal reading. Suggest rephrasing to "images: transformer written in form compatible with Image Updater write-back (regex ^[0-9a-f]{7,40}$)" -- already covered by AC #3. Non-blocking for this review since an astute dev agent can infer intent, but ideally clarified.
  • AC #5 (no stringData/data secret values) -- testable via grep.
  • AC #6 (overlay does not redefine env/envFrom) -- testable by diffing rendered output against base.

Blast Radius

Low. Single overlay directory in pal-e-deployments; no change to other services' overlays or bases/. Overlay is inert until pal-e-services ArgoCD Application (#1045) points at it AND Secret exists (#1047). Cannot break prod by merging alone. Rollback is git revert.

Decomposition Assessment

3 points, 2 files, 1 repo, 6 AC. Fits single agent pass (<5 min). No decomposition needed.

Recommendation

One fix remaining:
  • [BODY] Correct the remote-base kustomize URL to use // as the separator between the .git repo root and the k8s subpath. Change both occurrences (in Context section and File Targets section) from https://forgejo.tail5b443a.ts.net/forgejo_admin/notion-mcp-remote.git/k8s?ref=main to https://forgejo.tail5b443a.ts.net/forgejo_admin/notion-mcp-remote.git//k8s?ref=main.
Optional non-blocking:
  • [BODY] Clarify AC #4 ("ArgoCD Image Updater annotations present") -- per convention-kustomize-overlay these annotations live on the ArgoCD Application (via pal-e-services terraform), not on the overlay's kustomization.yaml. Suggest dropping AC #4 (redundant with #3) or rewording to reference the images: entry format only.
Once the URL fix lands, verdict will be APPROVED and the board item can be tagged review,ready.