Upgrade Kong Operator

Kong Operator is installed and upgraded exclusively with the kong/kong-operator Helm chart. This page covers what to know before you upgrade; for the step-by-step procedure, see Upgrade Kong Operator with Helm.

The most important thing to know is that Helm installs Custom Resource Definitions (CRDs) on the first install, but it never updates them afterwards. Any upgrade that ships new CRD fields requires you to apply the CRDs manually before you upgrade the release. Skipping this is the most common cause of a broken upgrade.

Kong Operator follows Semantic Versioning:

• Patch and minor releases (for example 2.0.0 → 2.0.1 or 2.0 → 2.1) never contain breaking changes. Support for deprecated features is kept, and the chart prints a warning during helm install/status/upgrade when your configuration uses something obsolete.
• Major releases (for example 1.x → 2.0) may require manual intervention.

Any change that needs manual action is called out in the changelog and the chart’s UPGRADE.md. If a version isn’t listed in UPGRADE.md, it needs no version-specific steps.

1. Read the changelog for every version between your current version and the target, and check UPGRADE.md for version-specific steps.
2. Read the chart changelog for every chart version between your current version and the one including the Kong Operator version bump.
3. Check version compatibility with your Kubernetes and Gateway API versions.

4. Back up your resources. Your Gateway, GatewayConfiguration, DataPlane, ControlPlane, and KonnectExtension resources are the source of truth. Export them so you can restore if needed:

   kubectl get gateway,gatewayconfiguration,dataplane,controlplane,konnectextension \
     -A -o yaml > operator-backup.yaml

   Copied!

Migrating between major versions may need extra work. See the dedicated guides for Kong Ingress Controller to Kong Operator and 1.6.x to 2.0.0.

Migrating from Kong Gateway Operator (kong/gateway-operator chart)

Older installs used the kong/gateway-operator chart with a release name like kgo. The chart is now kong/kong-operator. Because Helm doesn’t manage CRD updates across this move, apply the current CRDs with server-side apply before switching charts:

kustomize build github.com/kong/kong-operator/config/crd/gateway-operator | kubectl apply --server-side -f -

Upgrading from 2.0 to 2.1

Kong Operator 2.1 enables Combine HTTP routes by default, which automatically reduces the number of Services that share the same backendRef. During the 2.0 → 2.1 upgrade, expect a couple of seconds of downtime for affected Services as they are merged.

To keep the old behavior, set the following in your GatewayConfiguration before upgrading:

spec:
  controlPlaneOptions:
    translation:
      combinedServicesFromDifferentHTTPRoutes: disabled