docs(ecosystem): add Kong Operator installation guide#799
Open
luohua13 wants to merge 5 commits into
Open
Conversation
Adds an OLM-operator install + quickstart for Kong Operator (KGO) 2.2.0 wrapping the upstream Kong/charts kong-operator-1.3.0 chart. Follows the Authorino guide format: overview, prerequisites (cert-manager required), OperatorHub install with violet push fallback, verify step, then a full Gateway API quickstart that takes a GatewayClass + GatewayConfiguration + Gateway + HTTPRoute + echo upstream to a curl-verified 200 response. The quickstart frames the layered model explicitly so users understand why the install CR (Kong) is intentionally limited to install-time config and day-to-day routing happens through standalone Gateway API resources. FAQ covers the OLM-wrap vs upstream-KGO distinction, why Gateway/HTTPRoute are not embedded in the install CR, the docker.io / kong-gateway image mirror case for restricted clusters, and the helm `keep`-policy CRD ownership conflict that bites when a previous Kong install left CRDs behind under a different release name. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ll section Per review: - Move "Create a Kong instance" out of Quickstart into Install. The Kong CR is install-level (singleton, install-time config), not part of using Kong; the Quickstart now starts from a working Kong and walks through Gateway API. - Frame the Kong instance as form-driven (OperatorHub Create Instance), with an explicit per-field table: cert-manager toggles (both default ON for cert-manager-equipped ACP business clusters), replicaCount, and advanced resource requests/limits. Show the resulting YAML so kubectl users can produce the same CR. Drop the redundant "Tuning the Install" table. - Renumber Quickstart steps 1-6 (was 2-7) and fix internal cross-refs in step 3 body + ImagePullBackOff FAQ.
…p FAQ KGO 2.2.0 watches gateway.networking.k8s.io/v1 ReferenceGrant, which only exists in Gateway API CRDs at v1.5 or newer. Envoy Gateway v1.7 (current stable) bundles Gateway API v1.4.1 — when EG is installed first, the Kong Operator chart's gwapi-standard-crds sub-chart is skipped (Helm refuses to overwrite existing CRDs), leaving KGO crashlooping on missing v1 CRDs. Prereqs section now tells users to kubectl-apply v1.5.1 standard CRDs explicitly with the verify-and-restart command spelled out. New FAQ entry "KGO pod CrashLoops with 'failed to wait for Cache to sync'" documents the symptom + fix for anyone who hits it post-install.
After applying the quickstart end-to-end on a real ACP cluster (Gateway Programmed, HTTPRoute Accepted, curl returns echo body): 1. Step 2 (GatewayConfiguration): also pin `dataPlaneOptions.network.services.ingress.type: NodePort`. The chart default is LoadBalancer; on clusters without a LoadBalancer provider the ingress Service stays EXTERNAL-IP=<pending> and Gateway never becomes Programmed. NodePort works in all environments and keeps the external-reachability story simple. 2. Step 2 also gets an IMPORTANT callout: GatewayConfiguration is a snapshot at DataPlane create time. Changes do NOT propagate to an existing DataPlane CR — `kubectl delete dataplane` to force re-render. Hit this when patching ingress.type after Gateway was already created. 3. Step 6 (curl): the doc selector `gateway-operator.konghq.com/managed-by=dataplane` matches BOTH the admin Service (8444) and the ingress Service (80). Filter by name pattern `dataplane-ingress-*` to hit the proxy listener only. Probe command now exercises both the valid-host (200) and wrong-host (404) cases in one pod and demonstrates the NodePort external path too.
…plugin" Five review fixes: 1. Add Kubernetes 1.30+ to Supported Versions (carried by the Gateway API v1.5 prereq — GW API v1.5 requires K8s 1.30+ per its release notes). 2. Drop the OperatorHub-enabled and cert-manager-installed Prerequisites bullets — both are universally true on ACP business clusters and were noise. 3. "Kong Operator plugin" → "Kong Operator package" everywhere. The .tgz is an OLM operator bundle, not a plugin; the word was misleading. 4. Step 2 explainer + ImagePullBackOff FAQ updated: kong/kong-gateway:3.10 is now bundled with the package (added to csv.images in the source repo), synced to the cluster's internal registry by the build pipeline, and rewritten by the platform image whitelist. The docker-mirrors TIP in step 2 and the per-namespace mirror override recipe in the FAQ are no longer needed for normal flow; FAQ now scopes itself to the rare case where the whitelist hasn't propagated. 5. Supported Versions table now flags Gateway API CRDs as required v1.5+ (was just "v1 standard channel") and notes kong-gateway is bundled.
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.
Adds an OLM-operator install + quickstart for Kong Operator (KGO) 2.2.0 wrapping the upstream Kong/charts kong-operator-1.3.0 chart. Follows the Authorino guide format: overview, prerequisites (cert-manager required), OperatorHub install with violet push fallback, verify step, then a full Gateway API quickstart that takes a GatewayClass + GatewayConfiguration + Gateway + HTTPRoute + echo upstream to a curl-verified 200 response.
The quickstart frames the layered model explicitly so users understand why the install CR (Kong) is intentionally limited to install-time config and day-to-day routing happens through standalone Gateway API resources. FAQ covers the OLM-wrap vs upstream-KGO distinction, why Gateway/HTTPRoute are not embedded in the install CR, the docker.io / kong-gateway image mirror case for restricted clusters, and the helm
keep-policy CRD ownership conflict that bites when a previous Kong install left CRDs behind under a different release name.