[Kong Operator][docs]

Kong Operator is a [Kubernetes Operator][operator-concept] that can manage your Kong Ingress Controller, Kong Gateway Data Planes, or both together when running on Kubernetes.

With Kong Operator, users can:

• Deploy and configure Kong Gateway services.
• Customise deployments using PodTemplateSpec to:

• Upgrade Data Planes using a [rolling restart][docs_upgrade_rolling] or [blue/green deployments][docs_upgrade_bg].
• Configure [auto scaling on Data Planes][docs_autoscaling].

Current Features

The following features are considered supported:

• Kong Gateway Deployment & Configuration Management using the [Gateway API][gwapi]
• Creation of [Kong Gateways][konggw] using the DataPlane API
• [Kong Gateways][konggw] upgrades, downgrades and autoscaling
• Creation of [Kong Ingress Controller][kic] instances using the ControlPlane API
• Hybrid Mode Attachment using the DataPlane API
• Configuration and management of AIGateways (experimental feature)

API stability

The operator provides 2 APIs:

• YAML / manifests API which users use to apply their manifests against Kubernetes clusters.
• Go API through types exported under api/

This project:

• Follows [Kubernetes API versioning][k8s_api_versioning] for the YAML API.

• Tries to not break users implementing against operator's Go API but does not

[k8s_api_versioning]: https://kubernetes.io/docs/reference/using-api/#api-versioning

Quick Start and documentation

If you are eager to start with the operator, you can visit the quick start [section][docsqs] of the documentation. Alternatively, the complete [docs][docs] provide a full and detailed description of how to thoroughly use this project.

Container images

Release images

Release builds can be found on Docker Hub in [kong/kong-operator repository][dockerhub-ko].

At the moment we're providing images for:

• Linux amd64
• Linux arm64

UBI-based images

For Red Hat certification and OpenShift, the operator can be built on top of UBI 9 minimal:

make docker.build.ubi

This is a separate target: make docker.build keeps producing the default distroless image. The UBI image runs as a non-root user, carries the labels required by preflight, and includes license files under /licenses.

To build the amd64 and arm64 variants with buildx:

docker buildx build --target ubi \
  --platform linux/amd64,linux/arm64 \
  --build-arg GOPATH=/go \
  --build-arg GOCACHE=/root/.cache/go-build \
  -t <registry>/<image>:<tag> --push .

main branch builds

Nightly pre-release builds of the main branch are available from the [kong/nightly-kong-operator repository][dockerhub-ko-nightly] hosted on Docker Hub.

[dockerhub-ko-nightly]: https://hub.docker.com/r/kong/nightly-kong-operator

Development

Prerequisites

In order to build the operator you'll have to have Go installed on your machine. In order to do so, follow the instructions on its website[go-dev-site].

Build process

Building the operator should be as simple as running:

make build

This Makefile target will take care of everything from generating client side code, generating Kubernetes manifests, downloading the dependencies and the tools used in the build process and finally, it will build the binary.

After this step has finished successfully you should see the operator's binary bin/manager.

You can also run it directly via make run which will run the operator on your machine against the cluster that you have configured via your KUBECONFIG.

Adding new CRDs

Whenever you add a new CRD:

• Ensure that it is included in project's PROJECT file. This is necessary for creation of

• Annotate the CRD and any new type it depends on with the right markers to make sure it will be included

When you modify CRDs in config/crd/kong-operator/, run make verify.crd-breaking-changes to compare them against the base branch before opening or updating a PR. Override the comparison source with CRD_BREAKING_CHANGES_BASE_SHA or CRD_BREAKING_CHANGES_BASE_REF if you need to target a different baseline.

[community-operators]: https://github.com/k8s-operatorhub/community-operators/

Install the nightly build

Every night a new container image is built from the main development branch.

It can be installed using the helm chart from the main repo:

helm upgrade --install kong-operator \
  kong/kong-operator \
  -n kong-system \
  --create-namespace \
  --set image.tag=nightly \
  --set image.repository=kong/nightly-kong-operator \
  --set env.ENABLE_CONTROLLER_KONNECT=true

[!NOTE]

When using the nightly tag the operator version assumed is the one of the Chart.appversion, which is set to the latest release.

If a specific version is required (e.g., to enable version-gated features) you can specify it by adding the --set image.effectiveSemver= argument.

Using the unreleased helm chart version

If you want to use the unreleased version of the operator helm chart, you can use the OCI nightly build of the chart:

helm upgrade --install kong-operator \
  --devel \
  oci://registry-1.docker.io/kong/nightly-kong-operator-chart \
  -n kong-system \
  --create-namespace \
  --set image.tag=nightly \
  --set image.repository=kong/nightly-kong-operator

Seeking Help

Please search through the posts on the [discussions page][disc] as it's likely that another user has run into the same problem. If you don't find an answer, please feel free to post a question.

If you've found a bug, please [open an issue][issues].

For a feature request, please open an issue using the feature request template.

You can also talk to the developers behind Kong in the [#kong][slack] channel on the Kubernetes Slack server.

Community Meetings

You can join bi-weekly meetups hosted by [Kong][kong] to ask questions, provide feedback, or just to listen and hang out.

See the [Online Meetups Page][kong-meet] to sign up and receive meeting invites and [Zoom][zoom] links.

[kong]:https://konghq.com [konggw]:https://github.com/kong/kong [kic]:https://github.com/kong/kubernetes-ingress-controller [gwapi]:https://github.com/kubernetes-sigs/gateway-api [go-dev-site]: https://go.dev/ [disc]:https://github.com/kong/kong-operator/discussions [issues]:https://github.com/kong/kong-operator/issues [slack]:https://kubernetes.slack.com/messages/kong [kong-meet]:https://konghq.com/online-meetups/ [zoom]:https://zoom.us [docs]:https://developer.konghq.com/operator/ [docsqs]:https://developer.konghq.com/operator/dataplanes/get-started/kic/install/ [operator-concept]:https://kubernetes.io/docs/concepts/extend-kubernetes/operator/