docs: collapse the AI Gateway prereqs into one static file - #172
Open
dcmcand wants to merge 2 commits into
Open
Conversation
This was referenced Aug 21, 2026
Base automatically changed from
docs/nic-overlay-install-simplification
to
main
August 21, 2026 22:13
Sections 4 and 5 had operators author four files to install three upstream components, and one of those files carried the runbook's only placeholders: the gateway-api-inference-extension Application pointed at a kustomize directory you had to write yourself, wrapping the upstream release asset, because a flat manifests.yaml cannot be an ArgoCD source. Upstream also ships config/crd/kustomization.yaml, which can. At v1.5.0 `kubectl kustomize config/crd` renders the same four CRDs as the release asset, spec-identical, so the Application can point at the GIE repo directly. That removes the hand-authored kustomization and the last three placeholders, which leaves nothing in the prerequisites that varies by cluster: fixed upstream versions, fixed namespaces. So they ship as one file. examples/ai-gateway-prereqs.yaml holds all three Applications and is applied as-is; section 4 is now a single command and section 5 is the verification that used to be split across 4.2 and 5.2. Sections 6 onward keep their numbers, so no anchors move except the two being rewritten. Two things made explicit rather than left implicit in section ordering: the controller must come up before the section 6 overlay points envoy-gateway's extensionManager at its Service, and the two CRD-owning Applications set `prune: false` because pruning a CRD deletes every custom resource of that kind cluster-wide. An errant resync must not be able to remove every AIGatewayRoute and InferencePool on the cluster, including ones this pack did not create. The cost is that a CRD dropped upstream survives a version bump and needs removing by hand. Deletes examples/envoy-ai-gateway.yaml, which the new file supersedes and which nothing referenced any more. Also fixes a leftover from the previous commit: the 10.2 pod-health loop still probed only nvidia-gpu-operator, so it missed NIC's gpu-operator namespace. It now tries both and skips whichever is absent.
dcmcand
force-pushed
the
docs/ai-gateway-prereqs-bundle
branch
from
August 21, 2026 22:14
d9d0d9e to
9c1c0fe
Compare
The docs suite asserted on examples/envoy-ai-gateway.yaml, which the previous commit deleted, so `vitest run` failed with ENOENT. My grep for references to that file covered README, the docs pages, examples/ and dev/ but not docs/test/, and I did not run the docs suite locally. CI caught it. The invariant it was protecting (repoURL in NIC's prefix-less form, no oci://) still applies, so it moves to the new file. Three assertions are added for properties specific to the bundle: that all three prerequisites are present under project nebari-apps, that no placeholder survives (the whole point of the file being applied as-is), and that the two CRD-owning Applications stay prune: false while the controller prunes. The per-Application lookup anchors the name to end of line. A \b after "envoy-ai-gateway" also matches inside "envoy-ai-gateway-crds", which selected the wrong document and made the prune assertion pass for the wrong reason.
|
📄 Docs preview for |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
#171 has merged; this is now rebased onto
mainas a single commit.Why
§4 and §5 had operators author four files to install three upstream components, and one carried the runbook's only placeholders (
<your-org>,<cluster-config-repo>,<name>). Those existed for a single reason: thegateway-api-inference-extensionApplication pointed at a kustomize directory you had to write, wrapping the upstream release asset, because a flatmanifests.yamlcannot be an ArgoCD source.It doesn't have to be. Upstream also ships
config/crd/kustomization.yaml, which ArgoCD consumes natively:Rendered against the v1.5.0 release asset, the four CRDs are name- and spec-identical. So the Application points at the GIE repo directly, the hand-authored kustomization goes away, and with it the last three placeholders. Nothing left in the prerequisites varies by cluster: pinned upstream versions, fixed namespaces.
Hence one file.
examples/ai-gateway-prereqs.yamlholds all three Applications:envoy-ai-gateway-crdsai-gateway-crds-helmv0.5.0gateway-api-inference-extensionpath: config/crdenvoy-ai-gatewayai-gateway-helmv0.5.0§4 becomes one command; §5 becomes the verification previously split across 4.2 and 5.2. §6 onward keep their numbers, so no anchors move except the two rewritten.
Two decisions made explicit
Both were previously implicit in section ordering, which is a bad place for them to live:
extensionManagerat the controller's Service, so the reverse order spends a while logging connection-refused during XDS translation. Recoverable, but alarming. This is the same orderingdev/Makefilealready waits on.prune: falseon the two CRD Applications. Pruning a CRD deletes every custom resource of that kind cluster-wide. An errant resync must not be able to remove everyAIGatewayRouteandInferencePoolon the cluster, including ones this pack never created. The cost: a CRD dropped upstream survives a version bump and needs removing by hand. For CRDs that's the better failure.Note on
#44Closes #44.
This supersedes the
envoyAIGateway.installchart flag proposed in #44 rather than implementing it. With nothing cluster-specific to template, a chart flag would generate manifests that don't need generating - and it would make the CRDs part of the pack's Helm release, so flipping a value off could cascade into the CRD deletion described above. A static file the operator owns explicitly avoids that entirely and outlives the pack. Happy to be argued out of this.examples/envoy-ai-gateway.yamlis deleted: superseded by the new file, and nothing referenced it any more.Verification
kubectl kustomizeequivalence check above, run against a real v1.5.0 checkoutnpm run buildclean;scripts/check-links.sh→LINKS_OK; all 9 cross-page anchors resolve, including the renamed#4-install-the-ai-gateway-prerequisitessection 4/section 5cross-reference left dangling in the runbooknvidia-gpu-operatorand missed NIC'sgpu-operator. Now tries both, skips whichever is absent.The
kubectl apply -f https://raw.githubusercontent.com/.../main/examples/ai-gateway-prereqs.yamlURL 404s until this merges, as usual for docs that describe the merged state.