Production Change Record

Change MetadataCopy Anchor Link

• Change id: CR-2026-04-21-graph-v1-kong-route-rollout
• Date and time (UTC): 2026-04-21 00:54-00:57
• Requester: owner
• Approver (owner): owner
• Executor: GitHub Copilot agent (owner-approved execution)
• Environment: VPS production
• Related ticket or incident id: gateway-graph-v1-extension

ScopeCopy Anchor Link

• Services or stacks affected: runtime/stacks/infrastructure/gateway (Kong bootstrap routes/plugins), gateway docs and validation artifacts
• Expected impact: additive graph route coverage on Kong (/graph/docs, /graph/v1/*) with no removal of existing graph compatibility routes
• User-facing risk window: low after apply; fallback routes remain available

Risk AssessmentCopy Anchor Link

• Risk level: medium
• Main failure modes:
  • route-priority conflict with graph-protected
  • incorrect rewrite target for graph v1
  • accidental JWT gate on docs route
• Data integrity impact if failed: none expected (routing/auth layer only)

PreconditionsCopy Anchor Link

• Owner approval captured.
• Backup or rollback checkpoint confirmed.
• Validation plan prepared.
• Communication plan prepared.

Execution PlanCopy Anchor Link

1. Validate script syntax: bash -n runtime/stacks/infrastructure/gateway/kong-bootstrap-ocelot.sh.
2. Load live gateway env and apply bootstrap script in approved window.
3. Verify Kong route/plugin inventory for graph-docs-public and graph-v1-protected.
4. Run route and CORS smoke checks from validation artifact.
5. Record evidence and update completion status in state docs.

Rollback PlanCopy Anchor Link

1. Remove graph-docs-public and graph-v1-protected routes from Kong Admin API if regression appears.
2. Remove associated per-route plugins (request-transformer, rate-limiting, jwt) for those routes.
3. Re-run known-good bootstrap baseline from repository and re-validate prior graph route set.

Validation ResultsCopy Anchor Link

• Route validation:
  • GET /graph/docs -> HTTP 500 (public route reached, not JWT-gated)
  • GET /graph/v1/health without JWT -> HTTP 401 (expected deny)
  • GET /graph/v1/health with valid JWT -> HTTP 500 (JWT allow-path reached upstream)
• Health validation: Kong bootstrap apply completed successfully (Kong Ocelot migration applied successfully.)
• Auth and access validation:
  • graph-v1-protected route has jwt, request-transformer, and rate-limiting
  • graph-docs-public route has request-transformer and rate-limiting
• Log and alert review: no gateway apply errors observed during command execution

Evidence ReferencesCopy Anchor Link

• Validation runbook: docs/operations/validations/2026-04-21-graph-v1-kong-access-validation.mdx
• Mapping update: runtime/stacks/infrastructure/gateway/ocelot-to-kong-mapping.md
• Bootstrap source: runtime/stacks/infrastructure/gateway/kong-bootstrap-ocelot.sh
• Declarative state source: runtime/stacks/infrastructure/gateway/kong.yml

OutcomeCopy Anchor Link

• Result: success
• Start time (UTC): 2026-04-21T00:54:00Z
• End time (UTC): 2026-04-21T00:57:00Z
• Follow-up actions: investigate upstream graph application responses returning HTTP 500 for /docs and /api/v1/health probes (routing/auth path is functioning)
• Owner sign-off: pending