Stéphane Tailland
d4008e5e38
The domains' tools: arrays are hand-maintained, and that has now cost two defects an agent found the hard way — create-product could never succeed, and list-products cannot paginate, which let a model answer a product count that looked right and did not come from the data. Five limits measured against decK v1.64.0 and Kong Gateway 3.15, each reproduced rather than read: per-tool ACLs cannot express a consumer-group model and fail silently; the four MCP behavioural annotations are not generated; response schemas are not generated although the plugin consumes them for structuredOutput; servers is taken as the upstream target; every content type is copied and every operation exposed. FastMCP run on the same spec is recorded as a comparison point — it closes three of the five out of the box — with the reason we are not adopting it: it would move per-tool authorization out of the realm and into application code. Also records that MCP Composer and MCP Runner never shipped, so none of this is waiting on an imminent release. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
76 lines
3.2 KiB
Markdown
76 lines
3.2 KiB
Markdown
# k8s-platform
|
|
|
|
Platform-team owned, cluster-scoped only. Rare changes, cautious sync (not
|
|
aggressive auto-sync).
|
|
|
|
Per-domain gateway infrastructure (`Gateway`, `GatewayConfiguration`,
|
|
`KonnectAPIAuthConfiguration`) does NOT live here — see the dedicated
|
|
`dataplane-<domain>` repos, to avoid write contention across domains.
|
|
|
|
## MCP-TOOL-GENERATION.md
|
|
|
|
How the domains' MCP tool definitions are produced, the five limits of Kong's
|
|
`deck file openapi2mcp` generator, and the workaround each one forces. Read it
|
|
before editing any `<domain>-api/kong/mcp/ai-mcp-proxy.yaml` by hand — that file
|
|
is hand-maintained today, and that is precisely the problem it documents.
|
|
|
|
## flux/
|
|
|
|
The Flux Operator (`flux-system` namespace) that everything else in this
|
|
GitOps setup depends on. Installed 2026-08-19 on the local cluster.
|
|
|
|
The operator itself is installed manually via Helm — bootstrap problem,
|
|
Flux can't deploy the thing that deploys it:
|
|
|
|
```bash
|
|
helm install flux-operator oci://ghcr.io/controlplaneio-fluxcd/charts/flux-operator \
|
|
--namespace flux-system --create-namespace
|
|
```
|
|
|
|
`flux/fluxinstance.yaml` configures the actual Flux controllers
|
|
(source-controller, kustomize-controller, helm-controller,
|
|
notification-controller) — tracked in git, applied via
|
|
`kubectl apply -k flux/`.
|
|
|
|
`flux/gitrepository.yaml` is what lets Flux clone this (`k8s-platform`)
|
|
repo so other repos' `Kustomization`s can reference paths inside it (e.g.
|
|
`dataplane-template/`). `url` is a `PLACEHOLDER` — this repo has no git
|
|
remote yet. Once it does, apply it manually once
|
|
(`kubectl apply -f flux/gitrepository.yaml`) — same bootstrap-chicken-egg
|
|
reasoning as the operator install above.
|
|
|
|
## kong-platform/
|
|
|
|
Cluster-wide Kong foundations:
|
|
- `gatewayclass.yaml` — `GatewayClass` `kong-v2` (deliberately not named
|
|
`kong`, to avoid touching the pre-existing `kong` GatewayClass that backs
|
|
the unrelated `tasks`/`jira`/`openrouter` Gateway on this cluster).
|
|
- `operator/` — `HelmRepository` + `HelmRelease` for the Kong Gateway
|
|
Operator itself, matching the release already installed manually on this
|
|
cluster (`helm list -n kong`: chart `kong-operator-1.3.1`, `env.ENABLE_CONTROLLER_KONNECT: true`).
|
|
`helm-controller` can adopt an existing release under the same
|
|
`releaseName`/`targetNamespace` rather than reinstalling.
|
|
|
|
## dataplane-template/
|
|
|
|
The shared `KonnectAPIAuthConfiguration` + `GatewayConfiguration` + `Gateway`
|
|
+ `Secret` template (one copy, `${VAR}`-parameterized) that every domain's
|
|
Flux `Kustomization` builds via `postBuild.substitute` — see
|
|
`dataplane-catalog/README.md` for the full mechanism and the values/secret
|
|
side of it.
|
|
|
|
## Applying today (no git remote yet)
|
|
|
|
Nothing here reconciles from git automatically yet — `flux/gitrepository.yaml`
|
|
has no real URL. Apply directly:
|
|
|
|
```bash
|
|
kubectl apply -k flux/ # fluxinstance.yaml + gitrepository.yaml (the
|
|
# latter will just sit inert, PLACEHOLDER url)
|
|
kubectl apply -f kong-platform/gatewayclass.yaml
|
|
```
|
|
|
|
`dataplane-template/` is never applied on its own — it only makes sense
|
|
built + substituted by a domain's `flux-kustomization.yaml`, which itself
|
|
can't reconcile yet (needs the real `GitRepository`, see above).
|