From 33793d3358277a61dbfe8d9c9cc785af448d1b4e Mon Sep 17 00:00:00 2001 From: luohua13 Date: Tue, 30 Jun 2026 08:40:54 +0000 Subject: [PATCH 1/5] docs(ecosystem): add Kong Operator installation guide 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) --- .../ecosystem/kong/Kong_Installation_Guide.md | 425 ++++++++++++++++++ 1 file changed, 425 insertions(+) create mode 100644 docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md diff --git a/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md b/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md new file mode 100644 index 000000000..7406af9ae --- /dev/null +++ b/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md @@ -0,0 +1,425 @@ +--- +products: + - Alauda Application Services +kind: + - Solution +ProductsVersion: + - '4.1,4.2,4.3' +id: TBD +--- + +# Kong Installation Guide + +## Overview + +Kong is a Kubernetes-native API gateway built around the [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/). The Kong Gateway Operator (KGO) watches Gateway API resources (`GatewayClass`, `Gateway`, `HTTPRoute`, ...) and reconciles the underlying Kong control plane (Kong Ingress Controller) and data plane (Kong Gateway) for you. This guide describes how to install the Kong Operator from the ACP Marketplace, create a `Kong` instance, and validate end-to-end traffic with a minimal Gateway + HTTPRoute example. + +### Supported Versions + +| Component | Supported Versions | +|-----------|--------------------| +| Kong Operator (KGO) | 2.2.0 | +| Kong Operator chart | 1.3.0 | +| Kong Gateway (data plane, for the quickstart) | 3.10 | +| Kubernetes Gateway API | v1 (standard channel CRDs) | +| cert-manager (required) | 1.13+ | + +## Prerequisites + +- An ACP cluster with the **OperatorHub** feature enabled. +- **cert-manager installed and Ready in the cluster.** KGO 2.2.0 uses cert-manager to issue its admission/conversion webhook certificates and its internal CA. The default form options assume cert-manager is present; without it the install will fail to create `Issuer`/`Certificate` resources. ACP business clusters ship cert-manager by default. +- A target namespace where you will deploy the `Kong` instance. +- Business cluster nodes can access the platform image registry. The Kong Gateway data plane image (`kong/kong-gateway`) must be pullable; on restricted networks use a mirror (see [FAQ](#kong-gateway-pods-stay-in-imagepullbackoff)). +- (Optional) The `violet` CLI, downloaded from **App Store > App Onboarding** and matching the target platform version. Only required if the Kong Operator plugin package is not yet uploaded to the target platform. + +## Install the Kong Operator + +1. Download the **Kong Operator** plugin from the [Alauda Cloud Console](https://cloud.alauda.io/) Marketplace. +2. If the plugin package has not been uploaded to the target platform, follow the [Upload Packages](https://docs.alauda.io/container_platform/4.2/extend/upload_package.html) guide to upload it to the cluster, or push directly with `violet`: + + ```bash + violet push \ + --platform-address \ + --clusters \ + --platform-username \ + --platform-password \ + .tgz + ``` + +3. Sign in to the platform as an administrator. Navigate to **Administrator > Marketplace > OperatorHub**. +4. Locate **Kong Operator** and click **Install**. Choose the target namespace and accept the defaults. The platform creates a `Subscription` and approves the `InstallPlan`. +5. Wait until the operator `ClusterServiceVersion` reaches the `Succeeded` phase. + +### Verify the Operator + +```bash +# The CSV should be in the Succeeded phase +kubectl -n get csv | grep kong-operator + +# The operator Deployment should be Available +kubectl -n get deploy kong-operator +``` + +Expected result: + +- The `kong-operator.v2.2.0` CSV is in the `Succeeded` phase. +- The `kong-operator` Deployment is `1/1` ready. + +> [!NOTE] +> The `kong-operator` Deployment in the operator namespace is the OLM **wrap operator** — it watches `Kong` custom resources and installs the upstream Kong Operator chart when one is created. The actual Kong Gateway Operator (KGO) controller comes up only after you create a `Kong` instance in the next step. + +## Quick Start: Serve Traffic Through Kong Gateway + +This section walks through a minimal end-to-end example: create a `Kong` instance, define a `GatewayClass` + `Gateway`, route HTTP traffic to a sample upstream with an `HTTPRoute`, and verify with `curl`. + +Set variables used in the commands below: + +```bash +export NAMESPACE=kong-demo +export KONG_CR=kong-sample +export GATEWAY=demo-gateway +kubectl create namespace ${NAMESPACE} +``` + +### 1. Create a Kong Instance + +The `Kong` CR represents an installation of the Kong Gateway Operator. Its `spec` mirrors the upstream Helm chart's [values.yaml](https://github.com/Kong/charts/blob/kong-operator-1.3.0/charts/kong-operator/values.yaml); an empty `spec: {}` uses sensible defaults (cert-manager-issued webhook certs, single replica, KGO 2.2.0 image). + +```yaml +apiVersion: kong-operator.alauda.io/v1 +kind: Kong +metadata: + name: kong-sample + namespace: kong-demo +spec: {} +``` + +Apply the manifest and wait for the KGO Deployment to become Available: + +```bash +kubectl apply -f kong.yaml +kubectl -n ${NAMESPACE} wait kong/${KONG_CR} --for=jsonpath='{.status.conditions[?(@.type=="Deployed")].status}'=True --timeout=300s +kubectl -n ${NAMESPACE} rollout status deploy/${KONG_CR}-kong-operator-controller-manager --timeout=300s +``` + +Expected result: + +- The `Kong` resource reports `status.conditions[Deployed] = True`. +- The `${KONG_CR}-kong-operator-controller-manager` Deployment is Available (1/1). +- The Kubernetes Gateway API CRDs (`gateways.gateway.networking.k8s.io`, `gatewayclasses.gateway.networking.k8s.io`, `httproutes.gateway.networking.k8s.io`, ...) and KGO's own CRDs (`controlplanes.gateway-operator.konghq.com`, `dataplanes.gateway-operator.konghq.com`, `gatewayconfigurations.gateway-operator.konghq.com`) are registered cluster-wide. + +> [!NOTE] +> The `Kong` CR is a **singleton install-level resource** — it controls how KGO itself is deployed (replicas, resources, cert-manager toggles). Day-to-day routing is managed through the standard Gateway API resources (`GatewayClass`, `Gateway`, `HTTPRoute`), which are created independently of the `Kong` CR. This separation lets cluster admins manage the install once while application teams add routes on their own cadence. + +### 2. Create a GatewayClass + +`GatewayClass` is cluster-scoped and tells the Gateway API which controller manages a given class of Gateways. KGO watches GatewayClasses whose `controllerName` is `konghq.com/gateway-operator`. + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: GatewayClass +metadata: + name: kong +spec: + controllerName: konghq.com/gateway-operator +``` + +Apply and confirm KGO has accepted the class: + +```bash +kubectl apply -f gatewayclass.yaml +kubectl get gatewayclass kong \ + -o jsonpath='{.status.conditions[?(@.type=="Accepted")].status}{"\n"}' +``` + +Expected result: `True`. KGO is now ready to reconcile Gateways that reference this class. + +### 3. Pin the Kong Gateway Data Plane Image (Optional but Recommended) + +By default KGO selects a built-in default Kong Gateway image when it creates a `DataPlane` for a `Gateway`. Pinning the image via `GatewayConfiguration` makes the version explicit and lets you point to an internal registry mirror if your cluster cannot reach `docker.io` directly. + +```yaml +apiVersion: gateway-operator.konghq.com/v1beta1 +kind: GatewayConfiguration +metadata: + name: kong-config + namespace: kong-demo +spec: + dataPlaneOptions: + deployment: + podTemplateSpec: + spec: + containers: + - name: proxy + image: kong/kong-gateway:3.10 + controlPlaneOptions: + deployment: + podTemplateSpec: + spec: + containers: + - name: controller + image: kong/kong-operator:2.2.0 +``` + +> [!TIP] +> If your cluster mirrors `docker.io`, replace the image references with the mirrored equivalents — for example `docker-mirrors.alauda.cn/kong/kong-gateway:3.10`. + +### 4. Create a Gateway + +A `Gateway` is the request entry point. It references the `GatewayClass` from step 2 and (optionally) the `GatewayConfiguration` from step 3. KGO sees the `Gateway` and dynamically creates a `ControlPlane` + `DataPlane` to serve it. + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: demo-gateway + namespace: kong-demo +spec: + gatewayClassName: kong + infrastructure: + parametersRef: + group: gateway-operator.konghq.com + kind: GatewayConfiguration + name: kong-config + listeners: + - name: proxy + port: 80 + protocol: HTTP + allowedRoutes: + namespaces: + from: Same +``` + +Apply and wait for the Gateway to be programmed: + +```bash +kubectl apply -f gateway.yaml +kubectl -n ${NAMESPACE} wait gateway/${GATEWAY} --for=condition=Programmed --timeout=300s +kubectl -n ${NAMESPACE} get gateway ${GATEWAY} +``` + +Expected result: + +- `Accepted=True` (KGO acknowledged the Gateway). +- `Programmed=True` (the underlying `ControlPlane` + `DataPlane` Pods are running and reconciled). +- The Gateway's `status.addresses` shows a Service address you can route traffic to. + +### 5. Deploy a Sample Upstream Service + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: echo + namespace: kong-demo +spec: + replicas: 1 + selector: {matchLabels: {app: echo}} + template: + metadata: {labels: {app: echo}} + spec: + containers: + - name: echo + image: python:3.12-alpine + command: + - python3 + - -c + - | + from http.server import BaseHTTPRequestHandler, HTTPServer + class H(BaseHTTPRequestHandler): + def do_GET(s): + s.send_response(200); s.end_headers() + s.wfile.write(b'hello from echo upstream\n') + HTTPServer(('', 8080), H).serve_forever() + ports: [{containerPort: 8080}] +--- +apiVersion: v1 +kind: Service +metadata: {name: echo, namespace: kong-demo} +spec: + selector: {app: echo} + ports: [{port: 8080, targetPort: 8080}] +``` + +Apply and wait: + +```bash +kubectl apply -f echo.yaml +kubectl -n ${NAMESPACE} rollout status deploy/echo +``` + +### 6. Route Traffic with an HTTPRoute + +`HTTPRoute` declares which host/path on the Gateway maps to which backend Service. This is the resource application teams typically create — separately from the `Kong` install CR. + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: echo-route + namespace: kong-demo +spec: + parentRefs: + - name: demo-gateway + hostnames: + - echo.kong-demo.example.com + rules: + - matches: + - path: + type: PathPrefix + value: / + backendRefs: + - name: echo + port: 8080 +``` + +Apply: + +```bash +kubectl apply -f httproute.yaml +kubectl -n ${NAMESPACE} get httproute echo-route \ + -o jsonpath='{.status.parents[0].conditions[?(@.type=="Accepted")].status}{"\n"}' +``` + +Expected result: `True`. The route is bound to the Gateway and KGO has pushed the Kong configuration to the data plane. + +### 7. Verify with curl + +Find the Gateway's in-cluster Service and probe it from a curl pod: + +```bash +# The DataPlane Service that fronts the Gateway listeners +GATEWAY_SVC=$(kubectl -n ${NAMESPACE} get svc \ + -l gateway-operator.konghq.com/managed-by=dataplane \ + -o jsonpath='{.items[0].metadata.name}') +echo "Gateway service: ${GATEWAY_SVC}" + +kubectl -n ${NAMESPACE} run probe --rm -it --restart=Never \ + --image=curlimages/curl:latest \ + -- curl -sS -H 'Host: echo.kong-demo.example.com' \ + http://${GATEWAY_SVC}.${NAMESPACE}.svc:80/ +``` + +Expected output: + +```text +hello from echo upstream +``` + +Requests to the same Gateway with a Host header that doesn't match the `HTTPRoute.hostnames` return `404` — Kong rejects them as unrouted. + +## Cleanup + +For a test deployment, remove the resources created above: + +```bash +kubectl delete namespace ${NAMESPACE} +kubectl delete gatewayclass kong +``` + +> [!IMPORTANT] +> Many of the chart-installed CRDs are annotated with `helm.sh/resource-policy: keep` to preserve schema (and therefore any user resources) across re-installs. Deleting the namespace removes the `Kong` CR and triggers `helm uninstall`, but the CRDs persist by design. If you intend to re-install Kong with a **different release name later**, you may need to re-stamp the ownership annotations on those CRDs so the new release can claim them. Re-installing with the same `Kong` CR name (`kong-sample` in this guide) avoids the issue. + +To remove the operator, delete its `Subscription` and `ClusterServiceVersion` from **Administrator > Marketplace > OperatorHub > Installed**, or: + +```bash +kubectl -n delete subscription kong-operator +kubectl -n delete csv kong-operator.v2.2.0 +``` + +## Tuning the Install + +Re-open the `Kong` CR (or the OperatorHub form) to change any of these install-time options: + +| Field | Default | What it does | +|-------|---------|--------------| +| `global.webhooks.options.certManager.enabled` | `true` | When on, cert-manager issues webhook certificates. Disable only if cert-manager is not installed; the chart will then self-sign. | +| `global.certificateAuthority.options.certManager.enabled` | `true` | When on, cert-manager creates the Operator CA Issuer. The CA signs DataPlane/ControlPlane mutual-TLS certificates. | +| `replicaCount` | `1` | KGO controller replicas. Set `>= 2` in production for leader-election-driven failover. | +| `resources.requests.{cpu,memory}` | `10m / 128Mi` | KGO controller per-Pod requests. Raise when managing many DataPlanes. | +| `resources.limits.{cpu,memory}` | `500m / 256Mi` | KGO controller per-Pod limits. The 256Mi memory limit can OOM on clusters with many DataPlanes; bump to `512Mi+`. | + +Gateway-level options (replicas, images, environment, scheduling for the *Kong Gateway* data plane and *Kong Ingress Controller* control plane themselves) live on the `GatewayConfiguration` resource, not on the `Kong` CR. See step 3 for an example. + +## FAQ + +### What is the difference between the "Kong Operator" in OperatorHub and the "Kong Gateway Operator"? + +There are two operators in this stack: + +1. **The OLM wrap operator** (shown as "Kong Operator" in OperatorHub) is a thin helm-operator installed by ACP. Its job is to watch the `Kong` custom resource and apply the upstream Kong Operator Helm chart for you. +2. **The Kong Gateway Operator (KGO)** is the upstream Kong project (`github.com/Kong/kong-operator`). It reconciles Gateway API resources into actual Kong Gateway and Kong Ingress Controller Pods. + +You install (1) once from OperatorHub. Creating a `Kong` CR triggers (1) to deploy (2). All day-to-day routing work targets the Gateway API resources reconciled by (2). + +### Why isn't there a single "Kong" CR that contains my Gateways and HTTPRoutes? + +`Gateway`, `GatewayClass`, and `HTTPRoute` are first-class Kubernetes Gateway API resources, designed to be managed independently: + +- `GatewayClass` is cluster-scoped and typically owned by the platform admin. +- `Gateway` is namespaced and typically owned by a network/platform team. +- `HTTPRoute` is namespaced and typically owned by an application team — there can be hundreds of them. + +Embedding these inside the `Kong` install CR would collapse three distinct lifecycles into one giant object and break the standard tooling (kubectl plugins, GitOps, policy engines) that expects them as separate resources. The `Kong` CR is intentionally limited to install-time concerns. + +### Kong Gateway Pods stay in `ImagePullBackOff` + +Symptom: after step 4 the Gateway never reaches `Programmed=True`, and `kubectl describe pod` on a DataPlane Pod shows `Failed to pull image "kong/kong-gateway:3.10": rpc error: ...`. + +Cause: your cluster cannot reach `docker.io` directly. + +Fix: set the data plane and control plane images on the `GatewayConfiguration` to your internal mirror, for example: + +```yaml +spec: + dataPlaneOptions: + deployment: + podTemplateSpec: + spec: + containers: + - name: proxy + image: docker-mirrors.alauda.cn/kong/kong-gateway:3.10 + controlPlaneOptions: + deployment: + podTemplateSpec: + spec: + containers: + - name: controller + image: docker-mirrors.alauda.cn/kong/kong-operator:2.2.0 +``` + +Re-apply the `GatewayConfiguration`. KGO rolls the DataPlane to the new image. + +### The `Kong` install fails with "cannot import: invalid ownership metadata" + +Symptom: `kubectl describe kong kong-sample` reports a `ReleaseFailed` condition with text like: + +``` +CustomResourceDefinition "" exists and cannot be imported into the current release: +invalid ownership metadata; annotation validation error: key "meta.helm.sh/release-name" +must equal "": current value is "" +``` + +Cause: a previous `Kong` CR with a different name (or in a different namespace) installed the chart, was deleted, and the chart's cluster-scoped CRDs (annotated `helm.sh/resource-policy: keep`) survived. The new `Kong` install cannot claim CRDs owned by a different Helm release. + +Fix: either re-install with the original release name, or re-stamp the CRD ownership to the new release: + +```bash +NEW_REL=kong-sample +NEW_NS=kong-demo +for crd in $(kubectl get crd -o name | grep -E 'konghq\.com$|kong-operator'); do + kubectl annotate $crd \ + meta.helm.sh/release-name=$NEW_REL \ + meta.helm.sh/release-namespace=$NEW_NS --overwrite + kubectl label $crd app.kubernetes.io/managed-by=Helm --overwrite +done +``` + +Repeat for `ClusterRole`, `ClusterRoleBinding`, `ValidatingAdmissionPolicy`, `ValidatingAdmissionPolicyBinding`, and `ValidatingWebhookConfiguration` resources if their ownership metadata also mismatches. + +### Where can I learn more? + +- Upstream Kong Operator: [github.com/Kong/kong-operator](https://github.com/Kong/kong-operator) +- Upstream Helm chart: [github.com/Kong/charts](https://github.com/Kong/charts/tree/main/charts/kong-operator) +- Kubernetes Gateway API: [gateway-api.sigs.k8s.io](https://gateway-api.sigs.k8s.io/) +- Kong Gateway documentation: [docs.konghq.com/gateway](https://docs.konghq.com/gateway/) From 7aa184750243876563a6156ae3332c62519f65e9 Mon Sep 17 00:00:00 2001 From: luohua13 Date: Tue, 30 Jun 2026 09:10:43 +0000 Subject: [PATCH 2/5] docs(ecosystem/kong): make Create-Kong-Instance form-driven, in Install 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. --- .../ecosystem/kong/Kong_Installation_Guide.md | 117 ++++++++++-------- 1 file changed, 65 insertions(+), 52 deletions(-) diff --git a/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md b/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md index 7406af9ae..2ff85b9a5 100644 --- a/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md +++ b/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md @@ -68,50 +68,77 @@ Expected result: > [!NOTE] > The `kong-operator` Deployment in the operator namespace is the OLM **wrap operator** — it watches `Kong` custom resources and installs the upstream Kong Operator chart when one is created. The actual Kong Gateway Operator (KGO) controller comes up only after you create a `Kong` instance in the next step. -## Quick Start: Serve Traffic Through Kong Gateway +### Create a Kong Instance + +Installing the OLM bundle only brings up the wrap operator. To actually deploy the Kong Gateway Operator (KGO) you create a single **`Kong`** custom resource. We recommend creating it through the OperatorHub form so the install-time defaults are explicit and reviewable. + +1. From **Administrator > Marketplace > OperatorHub > Installed**, open **Kong Operator**, switch to the **`Kong`** tab, and click **Create Instance**. +2. The form is grouped into three sections; defaults are tuned for a typical ACP business cluster (which ships cert-manager): + + | Group | Field | Default | Recommendation | + |-------|-------|---------|----------------| + | **Certificates** | Use cert-manager for Webhooks | **On** | Leave on. Lets cert-manager issue and auto-renew the conversion / validating webhook certificates. Turn off only if cert-manager is not installed in the cluster (the chart will then self-sign). | + | **Certificates** | Use cert-manager for Operator CA | **On** | Leave on. cert-manager creates the Issuer that signs the DataPlane ↔ ControlPlane mutual-TLS certificates. | + | **High Availability** | Replica Count | `1` | Set to `2` or more for production so KGO survives a single Pod restart (leader election handles failover). | + | **Resources** (advanced) | CPU / Memory requests + limits | `10m / 128Mi` request, `500m / 256Mi` limit | Raise the memory limit to `512Mi+` if you expect many `DataPlane` instances; the default 256Mi limit can OOM under load. | + +3. Submit the form. The platform creates a `Kong` resource equivalent to the YAML below (cert-manager toggles on, single replica). All of these fields can also be edited later by reopening the `Kong` instance in the same UI. + + ```yaml + apiVersion: kong-operator.alauda.io/v1 + kind: Kong + metadata: + name: kong-sample + namespace: kong-system # any namespace works; the wrap operator watches cluster-wide + spec: + global: + webhooks: + options: + certManager: + enabled: true + certificateAuthority: + options: + certManager: + enabled: true + replicaCount: 1 + ``` -This section walks through a minimal end-to-end example: create a `Kong` instance, define a `GatewayClass` + `Gateway`, route HTTP traffic to a sample upstream with an `HTTPRoute`, and verify with `curl`. +> [!NOTE] +> The `Kong` CR is a **singleton install-level resource** — it controls how KGO itself is deployed (replicas, resources, cert-manager toggles). Day-to-day routing is managed through the standard Gateway API resources (`GatewayClass`, `Gateway`, `HTTPRoute`), which are created independently of the `Kong` CR. This separation lets cluster admins manage the install once while application teams add routes on their own cadence. -Set variables used in the commands below: +Verify the install completed: ```bash -export NAMESPACE=kong-demo -export KONG_CR=kong-sample -export GATEWAY=demo-gateway -kubectl create namespace ${NAMESPACE} +NAMESPACE= +KONG_CR=kong-sample + +kubectl -n ${NAMESPACE} wait kong/${KONG_CR} \ + --for=jsonpath='{.status.conditions[?(@.type=="Deployed")].status}'=True --timeout=300s +kubectl -n ${NAMESPACE} rollout status \ + deploy/${KONG_CR}-kong-operator-controller-manager --timeout=300s +kubectl -n ${NAMESPACE} get certificates ``` -### 1. Create a Kong Instance +Expected result: -The `Kong` CR represents an installation of the Kong Gateway Operator. Its `spec` mirrors the upstream Helm chart's [values.yaml](https://github.com/Kong/charts/blob/kong-operator-1.3.0/charts/kong-operator/values.yaml); an empty `spec: {}` uses sensible defaults (cert-manager-issued webhook certs, single replica, KGO 2.2.0 image). +- The `Kong` resource reports `status.conditions[Deployed] = True`. +- The `${KONG_CR}-kong-operator-controller-manager` Deployment is Available (1/1). +- Two cert-manager `Issuers` and three `Certificates` (webhook serving, validating webhook serving, operator CA) are all `Ready=True`. +- KGO's own CRDs (`controlplanes`, `dataplanes`, `gatewayconfigurations` under `gateway-operator.konghq.com`) and the Kubernetes Gateway API standard CRDs (`gateways`, `gatewayclasses`, `httproutes`, ... under `gateway.networking.k8s.io`) are registered cluster-wide. -```yaml -apiVersion: kong-operator.alauda.io/v1 -kind: Kong -metadata: - name: kong-sample - namespace: kong-demo -spec: {} -``` +## Quick Start: Serve Traffic Through Kong Gateway -Apply the manifest and wait for the KGO Deployment to become Available: +This section assumes the install from the previous chapter is complete — you have a running `Kong` instance and KGO is reconciling Gateway API resources. The quickstart walks through a minimal end-to-end example: declare a `GatewayClass` + `Gateway`, route HTTP traffic to a sample upstream with an `HTTPRoute`, and verify with `curl`. + +Set variables used in the commands below: ```bash -kubectl apply -f kong.yaml -kubectl -n ${NAMESPACE} wait kong/${KONG_CR} --for=jsonpath='{.status.conditions[?(@.type=="Deployed")].status}'=True --timeout=300s -kubectl -n ${NAMESPACE} rollout status deploy/${KONG_CR}-kong-operator-controller-manager --timeout=300s +export NAMESPACE=kong-demo +export GATEWAY=demo-gateway +kubectl create namespace ${NAMESPACE} ``` -Expected result: - -- The `Kong` resource reports `status.conditions[Deployed] = True`. -- The `${KONG_CR}-kong-operator-controller-manager` Deployment is Available (1/1). -- The Kubernetes Gateway API CRDs (`gateways.gateway.networking.k8s.io`, `gatewayclasses.gateway.networking.k8s.io`, `httproutes.gateway.networking.k8s.io`, ...) and KGO's own CRDs (`controlplanes.gateway-operator.konghq.com`, `dataplanes.gateway-operator.konghq.com`, `gatewayconfigurations.gateway-operator.konghq.com`) are registered cluster-wide. - -> [!NOTE] -> The `Kong` CR is a **singleton install-level resource** — it controls how KGO itself is deployed (replicas, resources, cert-manager toggles). Day-to-day routing is managed through the standard Gateway API resources (`GatewayClass`, `Gateway`, `HTTPRoute`), which are created independently of the `Kong` CR. This separation lets cluster admins manage the install once while application teams add routes on their own cadence. - -### 2. Create a GatewayClass +### 1. Create a GatewayClass `GatewayClass` is cluster-scoped and tells the Gateway API which controller manages a given class of Gateways. KGO watches GatewayClasses whose `controllerName` is `konghq.com/gateway-operator`. @@ -134,7 +161,7 @@ kubectl get gatewayclass kong \ Expected result: `True`. KGO is now ready to reconcile Gateways that reference this class. -### 3. Pin the Kong Gateway Data Plane Image (Optional but Recommended) +### 2. Pin the Kong Gateway Data Plane Image (Optional but Recommended) By default KGO selects a built-in default Kong Gateway image when it creates a `DataPlane` for a `Gateway`. Pinning the image via `GatewayConfiguration` makes the version explicit and lets you point to an internal registry mirror if your cluster cannot reach `docker.io` directly. @@ -164,9 +191,9 @@ spec: > [!TIP] > If your cluster mirrors `docker.io`, replace the image references with the mirrored equivalents — for example `docker-mirrors.alauda.cn/kong/kong-gateway:3.10`. -### 4. Create a Gateway +### 3. Create a Gateway -A `Gateway` is the request entry point. It references the `GatewayClass` from step 2 and (optionally) the `GatewayConfiguration` from step 3. KGO sees the `Gateway` and dynamically creates a `ControlPlane` + `DataPlane` to serve it. +A `Gateway` is the request entry point. It references the `GatewayClass` from step 1 and (optionally) the `GatewayConfiguration` from step 2. KGO sees the `Gateway` and dynamically creates a `ControlPlane` + `DataPlane` to serve it. ```yaml apiVersion: gateway.networking.k8s.io/v1 @@ -204,7 +231,7 @@ Expected result: - `Programmed=True` (the underlying `ControlPlane` + `DataPlane` Pods are running and reconciled). - The Gateway's `status.addresses` shows a Service address you can route traffic to. -### 5. Deploy a Sample Upstream Service +### 4. Deploy a Sample Upstream Service ```yaml apiVersion: apps/v1 @@ -248,7 +275,7 @@ kubectl apply -f echo.yaml kubectl -n ${NAMESPACE} rollout status deploy/echo ``` -### 6. Route Traffic with an HTTPRoute +### 5. Route Traffic with an HTTPRoute `HTTPRoute` declares which host/path on the Gateway maps to which backend Service. This is the resource application teams typically create — separately from the `Kong` install CR. @@ -283,7 +310,7 @@ kubectl -n ${NAMESPACE} get httproute echo-route \ Expected result: `True`. The route is bound to the Gateway and KGO has pushed the Kong configuration to the data plane. -### 7. Verify with curl +### 6. Verify with curl Find the Gateway's in-cluster Service and probe it from a curl pod: @@ -327,20 +354,6 @@ kubectl -n delete subscription kong-operator kubectl -n delete csv kong-operator.v2.2.0 ``` -## Tuning the Install - -Re-open the `Kong` CR (or the OperatorHub form) to change any of these install-time options: - -| Field | Default | What it does | -|-------|---------|--------------| -| `global.webhooks.options.certManager.enabled` | `true` | When on, cert-manager issues webhook certificates. Disable only if cert-manager is not installed; the chart will then self-sign. | -| `global.certificateAuthority.options.certManager.enabled` | `true` | When on, cert-manager creates the Operator CA Issuer. The CA signs DataPlane/ControlPlane mutual-TLS certificates. | -| `replicaCount` | `1` | KGO controller replicas. Set `>= 2` in production for leader-election-driven failover. | -| `resources.requests.{cpu,memory}` | `10m / 128Mi` | KGO controller per-Pod requests. Raise when managing many DataPlanes. | -| `resources.limits.{cpu,memory}` | `500m / 256Mi` | KGO controller per-Pod limits. The 256Mi memory limit can OOM on clusters with many DataPlanes; bump to `512Mi+`. | - -Gateway-level options (replicas, images, environment, scheduling for the *Kong Gateway* data plane and *Kong Ingress Controller* control plane themselves) live on the `GatewayConfiguration` resource, not on the `Kong` CR. See step 3 for an example. - ## FAQ ### What is the difference between the "Kong Operator" in OperatorHub and the "Kong Gateway Operator"? @@ -364,7 +377,7 @@ Embedding these inside the `Kong` install CR would collapse three distinct lifec ### Kong Gateway Pods stay in `ImagePullBackOff` -Symptom: after step 4 the Gateway never reaches `Programmed=True`, and `kubectl describe pod` on a DataPlane Pod shows `Failed to pull image "kong/kong-gateway:3.10": rpc error: ...`. +Symptom: after step 3 the Gateway never reaches `Programmed=True`, and `kubectl describe pod` on a DataPlane Pod shows `Failed to pull image "kong/kong-gateway:3.10": rpc error: ...`. Cause: your cluster cannot reach `docker.io` directly. From 3880162e3cb52349bf42a11a07c5858534f81d1c Mon Sep 17 00:00:00 2001 From: luohua13 Date: Tue, 30 Jun 2026 10:15:02 +0000 Subject: [PATCH 3/5] docs(ecosystem/kong): add Gateway API v1.5+ prerequisite and CrashLoop FAQ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .../ecosystem/kong/Kong_Installation_Guide.md | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md b/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md index 2ff85b9a5..35c145fb0 100644 --- a/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md +++ b/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md @@ -28,6 +28,13 @@ Kong is a Kubernetes-native API gateway built around the [Kubernetes Gateway API - An ACP cluster with the **OperatorHub** feature enabled. - **cert-manager installed and Ready in the cluster.** KGO 2.2.0 uses cert-manager to issue its admission/conversion webhook certificates and its internal CA. The default form options assume cert-manager is present; without it the install will fail to create `Issuer`/`Certificate` resources. ACP business clusters ship cert-manager by default. +- **Kubernetes Gateway API CRDs at v1.5 or newer (`standard` channel)** installed cluster-wide. KGO 2.2.0 watches `gateway.networking.k8s.io/v1` `ReferenceGrant`, which graduated to `v1` only in Gateway API v1.5. If your cluster already has Gateway API CRDs from another implementation (Envoy Gateway v1.7, Cilium, etc.) that bundle Gateway API ≤ v1.4, install the newer CRDs explicitly — Helm-installed CRDs are skipped when older versions already exist, so the Kong Operator chart will **not** upgrade them for you: + + ```bash + kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml + ``` + + Verify `referencegrants.gateway.networking.k8s.io` lists `v1` under `spec.versions`. The upgrade is additive and backward-compatible — older controllers continue to read `v1beta1`. See [FAQ](#kgo-pod-crashloops-with-failed-to-wait-for-cache-to-sync) for the symptom this prevents. - A target namespace where you will deploy the `Kong` instance. - Business cluster nodes can access the platform image registry. The Kong Gateway data plane image (`kong/kong-gateway`) must be pullable; on restricted networks use a mirror (see [FAQ](#kong-gateway-pods-stay-in-imagepullbackoff)). - (Optional) The `violet` CLI, downloaded from **App Store > App Onboarding** and matching the target platform version. Only required if the Kong Operator plugin package is not yet uploaded to the target platform. @@ -375,6 +382,32 @@ You install (1) once from OperatorHub. Creating a `Kong` CR triggers (1) to depl Embedding these inside the `Kong` install CR would collapse three distinct lifecycles into one giant object and break the standard tooling (kubectl plugins, GitOps, policy engines) that expects them as separate resources. The `Kong` CR is intentionally limited to install-time concerns. +### KGO pod CrashLoops with "failed to wait for Cache to sync" + +Symptom: the `-kong-operator-controller-manager` Pod restarts every ~5 minutes. Its previous-container log shows: + +``` +failed to wait for gateway caches to sync kind source: *v1.ReferenceGrant: timed out waiting for cache to be synced +"if kind is a CRD, it should be installed before calling Start","kind":"ReferenceGrant.gateway.networking.k8s.io" +"no matches for kind \"ReferenceGrant\" in version \"gateway.networking.k8s.io/v1\"" +``` + +Cause: KGO 2.2.0 watches `gateway.networking.k8s.io/v1` `ReferenceGrant`, which only exists in Gateway API CRDs at **v1.5 or newer**. If the cluster already had older Gateway API CRDs from another implementation (Envoy Gateway v1.7 ships Gateway API v1.4.1, for example), Helm-installed CRDs are skipped on conflict, and the Kong Operator chart leaves the older CRDs in place. KGO then can't find the `v1` group it expects. + +Fix: install the upstream Gateway API v1.5+ standard CRDs (additive, backward-compatible — older controllers keep working on `v1beta1`): + +```bash +kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/standard-install.yaml + +kubectl get crd referencegrants.gateway.networking.k8s.io \ + -o jsonpath='{range .spec.versions[*]}{.name}{"\n"}{end}' +# Expected output includes v1, v1beta1, v1alpha2 + +kubectl -n rollout restart deploy/-kong-operator-controller-manager +``` + +After the restart, the Pod stays Ready=True without further CrashLoops. + ### Kong Gateway Pods stay in `ImagePullBackOff` Symptom: after step 3 the Gateway never reaches `Programmed=True`, and `kubectl describe pod` on a DataPlane Pod shows `Failed to pull image "kong/kong-gateway:3.10": rpc error: ...`. From 8fe91d2b68cca8ae2c220b0c669ce17cbe0b845b Mon Sep 17 00:00:00 2001 From: luohua13 Date: Tue, 30 Jun 2026 10:34:39 +0000 Subject: [PATCH 4/5] docs(ecosystem/kong): three quickstart fixes from live validation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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= 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. --- .../ecosystem/kong/Kong_Installation_Guide.md | 43 ++++++++++++++----- 1 file changed, 33 insertions(+), 10 deletions(-) diff --git a/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md b/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md index 35c145fb0..7a2f67a89 100644 --- a/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md +++ b/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md @@ -168,9 +168,9 @@ kubectl get gatewayclass kong \ Expected result: `True`. KGO is now ready to reconcile Gateways that reference this class. -### 2. Pin the Kong Gateway Data Plane Image (Optional but Recommended) +### 2. Pin the Kong Gateway Data Plane Image and Service Type -By default KGO selects a built-in default Kong Gateway image when it creates a `DataPlane` for a `Gateway`. Pinning the image via `GatewayConfiguration` makes the version explicit and lets you point to an internal registry mirror if your cluster cannot reach `docker.io` directly. +By default KGO creates the `DataPlane`'s ingress Service as `type: LoadBalancer`. On clusters without a LoadBalancer provider (no MetalLB / cloud LB controller) the Service stays `EXTERNAL-IP: ` and the Gateway never reaches `Programmed=True`. `GatewayConfiguration` lets you both pin the data plane image (so you point at an internal mirror on restricted networks) and set the ingress Service type to `NodePort` or `ClusterIP` instead. ```yaml apiVersion: gateway-operator.konghq.com/v1beta1 @@ -180,6 +180,10 @@ metadata: namespace: kong-demo spec: dataPlaneOptions: + network: + services: + ingress: + type: NodePort # ClusterIP also works for in-cluster only access deployment: podTemplateSpec: spec: @@ -198,6 +202,9 @@ spec: > [!TIP] > If your cluster mirrors `docker.io`, replace the image references with the mirrored equivalents — for example `docker-mirrors.alauda.cn/kong/kong-gateway:3.10`. +> [!IMPORTANT] +> Create the `GatewayConfiguration` **before** the `Gateway`. KGO snapshots the configuration when it first creates the `DataPlane` CR for the Gateway; later changes to `GatewayConfiguration` do **not** propagate to existing `DataPlane`s automatically. To apply a change after the fact, `kubectl delete dataplane -n ` — KGO immediately re-creates the DataPlane from the current `GatewayConfiguration`. + ### 3. Create a Gateway A `Gateway` is the request entry point. It references the `GatewayClass` from step 1 and (optionally) the `GatewayConfiguration` from step 2. KGO sees the `Gateway` and dynamically creates a `ControlPlane` + `DataPlane` to serve it. @@ -319,28 +326,44 @@ Expected result: `True`. The route is bound to the Gateway and KGO has pushed th ### 6. Verify with curl -Find the Gateway's in-cluster Service and probe it from a curl pod: +Find the Gateway's in-cluster ingress Service and probe it from a curl pod. KGO emits **two** Services per DataPlane — an `-admin-` Service (port 8444, internal Kong admin API) and an `-ingress-` Service (port 80, the proxy listener). Filter to the ingress one by name; the chart label `gateway-operator.konghq.com/managed-by=dataplane` is set on both and is not specific enough. ```bash -# The DataPlane Service that fronts the Gateway listeners -GATEWAY_SVC=$(kubectl -n ${NAMESPACE} get svc \ - -l gateway-operator.konghq.com/managed-by=dataplane \ - -o jsonpath='{.items[0].metadata.name}') +# Pick the ingress Service (not the admin Service) +GATEWAY_SVC=$(kubectl -n ${NAMESPACE} get svc -o name \ + | grep dataplane-ingress | head -1 | sed 's|service/||') echo "Gateway service: ${GATEWAY_SVC}" kubectl -n ${NAMESPACE} run probe --rm -it --restart=Never \ --image=curlimages/curl:latest \ - -- curl -sS -H 'Host: echo.kong-demo.example.com' \ - http://${GATEWAY_SVC}.${NAMESPACE}.svc:80/ + -- sh -c " + echo '--- valid host -> expect 200 ---' + curl -sS -H 'Host: echo.kong-demo.example.com' http://${GATEWAY_SVC}.${NAMESPACE}.svc:80/ + echo '--- wrong host -> expect 404 ---' + curl -sS -o /dev/null -w 'http %{http_code}\n' -H 'Host: other.example.com' http://${GATEWAY_SVC}.${NAMESPACE}.svc:80/ + " ``` Expected output: ```text +--- valid host -> expect 200 --- hello from echo upstream +--- wrong host -> expect 404 --- +http 404 ``` -Requests to the same Gateway with a Host header that doesn't match the `HTTPRoute.hostnames` return `404` — Kong rejects them as unrouted. +If you set `dataPlaneOptions.network.services.ingress.type: NodePort` in step 2, you can also reach the Gateway from outside the cluster via any node IP and the assigned NodePort: + +```bash +kubectl -n ${NAMESPACE} get svc | grep dataplane-ingress +# Look for the "80:/TCP" column + +NODE_IP=$(kubectl get node -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}') +NODE_PORT=$(kubectl -n ${NAMESPACE} get svc \ + -o jsonpath="{.items[?(@.metadata.name=='${GATEWAY_SVC}')].spec.ports[0].nodePort}") +curl -sS -H 'Host: echo.kong-demo.example.com' http://${NODE_IP}:${NODE_PORT}/ +``` ## Cleanup From 0b6754719c20f1038e5019b8e504b4c870833a2c Mon Sep 17 00:00:00 2001 From: luohua13 Date: Tue, 30 Jun 2026 11:32:28 +0000 Subject: [PATCH 5/5] docs(ecosystem/kong): bundle kong-gateway image, trim prereqs, drop "plugin" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .../ecosystem/kong/Kong_Installation_Guide.md | 50 +++++-------------- 1 file changed, 13 insertions(+), 37 deletions(-) diff --git a/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md b/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md index 7a2f67a89..c3bcc041c 100644 --- a/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md +++ b/docs/en/solutions/ecosystem/kong/Kong_Installation_Guide.md @@ -20,14 +20,13 @@ Kong is a Kubernetes-native API gateway built around the [Kubernetes Gateway API |-----------|--------------------| | Kong Operator (KGO) | 2.2.0 | | Kong Operator chart | 1.3.0 | -| Kong Gateway (data plane, for the quickstart) | 3.10 | -| Kubernetes Gateway API | v1 (standard channel CRDs) | -| cert-manager (required) | 1.13+ | +| Kong Gateway (data plane) | 3.10 (bundled in the operator package; pinned via `GatewayConfiguration`) | +| Kubernetes Gateway API CRDs | **v1.5 or newer (standard channel)** | +| Kubernetes | **1.30 or newer** (Gateway API v1.5 requirement) | ## Prerequisites -- An ACP cluster with the **OperatorHub** feature enabled. -- **cert-manager installed and Ready in the cluster.** KGO 2.2.0 uses cert-manager to issue its admission/conversion webhook certificates and its internal CA. The default form options assume cert-manager is present; without it the install will fail to create `Issuer`/`Certificate` resources. ACP business clusters ship cert-manager by default. +- A target namespace where you will deploy the `Kong` instance. - **Kubernetes Gateway API CRDs at v1.5 or newer (`standard` channel)** installed cluster-wide. KGO 2.2.0 watches `gateway.networking.k8s.io/v1` `ReferenceGrant`, which graduated to `v1` only in Gateway API v1.5. If your cluster already has Gateway API CRDs from another implementation (Envoy Gateway v1.7, Cilium, etc.) that bundle Gateway API ≤ v1.4, install the newer CRDs explicitly — Helm-installed CRDs are skipped when older versions already exist, so the Kong Operator chart will **not** upgrade them for you: ```bash @@ -35,14 +34,12 @@ Kong is a Kubernetes-native API gateway built around the [Kubernetes Gateway API ``` Verify `referencegrants.gateway.networking.k8s.io` lists `v1` under `spec.versions`. The upgrade is additive and backward-compatible — older controllers continue to read `v1beta1`. See [FAQ](#kgo-pod-crashloops-with-failed-to-wait-for-cache-to-sync) for the symptom this prevents. -- A target namespace where you will deploy the `Kong` instance. -- Business cluster nodes can access the platform image registry. The Kong Gateway data plane image (`kong/kong-gateway`) must be pullable; on restricted networks use a mirror (see [FAQ](#kong-gateway-pods-stay-in-imagepullbackoff)). -- (Optional) The `violet` CLI, downloaded from **App Store > App Onboarding** and matching the target platform version. Only required if the Kong Operator plugin package is not yet uploaded to the target platform. +- (Optional) The `violet` CLI, downloaded from **App Store > App Onboarding** and matching the target platform version. Only required if the Kong Operator package is not yet uploaded to the target platform. ## Install the Kong Operator -1. Download the **Kong Operator** plugin from the [Alauda Cloud Console](https://cloud.alauda.io/) Marketplace. -2. If the plugin package has not been uploaded to the target platform, follow the [Upload Packages](https://docs.alauda.io/container_platform/4.2/extend/upload_package.html) guide to upload it to the cluster, or push directly with `violet`: +1. Download the **Kong Operator** package from the [Alauda Cloud Console](https://cloud.alauda.io/) Marketplace. +2. If the package has not been uploaded to the target platform, follow the [Upload Packages](https://docs.alauda.io/container_platform/4.2/extend/upload_package.html) guide to upload it to the cluster, or push directly with `violet`: ```bash violet push \ @@ -50,7 +47,7 @@ Kong is a Kubernetes-native API gateway built around the [Kubernetes Gateway API --clusters \ --platform-username \ --platform-password \ - .tgz + .tgz ``` 3. Sign in to the platform as an administrator. Navigate to **Administrator > Marketplace > OperatorHub**. @@ -170,7 +167,9 @@ Expected result: `True`. KGO is now ready to reconcile Gateways that reference t ### 2. Pin the Kong Gateway Data Plane Image and Service Type -By default KGO creates the `DataPlane`'s ingress Service as `type: LoadBalancer`. On clusters without a LoadBalancer provider (no MetalLB / cloud LB controller) the Service stays `EXTERNAL-IP: ` and the Gateway never reaches `Programmed=True`. `GatewayConfiguration` lets you both pin the data plane image (so you point at an internal mirror on restricted networks) and set the ingress Service type to `NodePort` or `ClusterIP` instead. +By default KGO creates the `DataPlane`'s ingress Service as `type: LoadBalancer`. On clusters without a LoadBalancer provider (no MetalLB / cloud LB controller) the Service stays `EXTERNAL-IP: ` and the Gateway never reaches `Programmed=True`. `GatewayConfiguration` lets you both pin the data plane image and set the ingress Service type to `NodePort` or `ClusterIP` instead. + +The `kong/kong-gateway:3.10` image is bundled with the Kong Operator package — it is synced to the cluster's internal registry and registered in the platform's image whitelist, so the `docker.io/kong/kong-gateway` reference below is rewritten automatically to the internal location. No manual mirroring is needed. ```yaml apiVersion: gateway-operator.konghq.com/v1beta1 @@ -199,9 +198,6 @@ spec: image: kong/kong-operator:2.2.0 ``` -> [!TIP] -> If your cluster mirrors `docker.io`, replace the image references with the mirrored equivalents — for example `docker-mirrors.alauda.cn/kong/kong-gateway:3.10`. - > [!IMPORTANT] > Create the `GatewayConfiguration` **before** the `Gateway`. KGO snapshots the configuration when it first creates the `DataPlane` CR for the Gateway; later changes to `GatewayConfiguration` do **not** propagate to existing `DataPlane`s automatically. To apply a change after the fact, `kubectl delete dataplane -n ` — KGO immediately re-creates the DataPlane from the current `GatewayConfiguration`. @@ -435,29 +431,9 @@ After the restart, the Pod stays Ready=True without further CrashLoops. Symptom: after step 3 the Gateway never reaches `Programmed=True`, and `kubectl describe pod` on a DataPlane Pod shows `Failed to pull image "kong/kong-gateway:3.10": rpc error: ...`. -Cause: your cluster cannot reach `docker.io` directly. - -Fix: set the data plane and control plane images on the `GatewayConfiguration` to your internal mirror, for example: - -```yaml -spec: - dataPlaneOptions: - deployment: - podTemplateSpec: - spec: - containers: - - name: proxy - image: docker-mirrors.alauda.cn/kong/kong-gateway:3.10 - controlPlaneOptions: - deployment: - podTemplateSpec: - spec: - containers: - - name: controller - image: docker-mirrors.alauda.cn/kong/kong-operator:2.2.0 -``` +Cause: this should be rare — the Kong Operator package bundles `kong/kong-gateway:3.10` to the cluster's internal registry, and the platform's image whitelist rewrites `docker.io/kong/kong-gateway` references automatically. If you hit this, it usually means the image whitelist was not provisioned for your namespace yet, or the namespace was created before the Kong Operator was installed. -Re-apply the `GatewayConfiguration`. KGO rolls the DataPlane to the new image. +Fix: confirm the image is on the internal registry, and that your namespace receives the rewrite (the platform tool surface for image whitelists varies by ACP version). As a workaround you can override the image on the `GatewayConfiguration` to a fully-qualified internal path, for example `/3rdparty/kong/kong-gateway:3.10`. Re-apply the `GatewayConfiguration` and `kubectl delete dataplane ` to force KGO to re-create the DataPlane with the new image. ### The `Kong` install fails with "cannot import: invalid ownership metadata"