Migrating from Kong Gateway Operator 1.6.x to Kong Operator 2.0.0

Kong Operator (KO) 2.0.0 represents a major version upgrade from Kong Gateway Operator (KGO) 1.6.x, introducing significant architectural improvements, enhanced Kubernetes-native features, and breaking changes that require careful migration planning.

Before starting the migration, ensure you:

1. Backup your current configuration

2. Verify current operator version:

   helm list -n kong-system
   

   Copied!
3. Check for deprecated konnectID field (if using KonnectExtensions):

   kubectl get konnectextensions --all-namespaces -o yaml | grep -A 5 -B 5 konnectID
   

   Copied!

   Important: If this command returns any results, you must migrate these KonnectExtensions before upgrading. Follow the KonnectExtension Migration Guide first.

4. Access to Kubernetes cluster with admin privileges

5. Verify cert-manager is installed (required for conversion webhooks):

   Note: Kong Operator 2.0.0 uses conversion webhooks that require TLS certificates managed by cert-manager. If cert-manager is not installed, follow the cert-manager installation guide before proceeding. If you do not use cert-manager, the Helm chart will install certificates for you and you will be responsible for managing their lifecycle.

The upgrade process requires several manual steps due to breaking changes in certificate management and CRD structure. Follow these steps carefully:

Step 1: Uninstall the Existing KGO Release

First, uninstall the current Kong Gateway Operator release:

helm uninstall kgo -n kong-system

Step 2: Label the Secret

To ensure the Kong Operator can properly reconcile the Secrets in your cluster, they need to be labeled with konghq.com/secret=true.

This allows efficient listing of Secrets and prevents ingesting those that are irrelevant from Kong configuration standpoint.

This includes the CA certificate secret. To label it as described above it you can run the following command:

kubectl label secrets -n kong-system kong-operator-ca konghq.com/secret=true

Step 3: Install Kong Operator 2.0.0

Install the new Kong Operator using Helm:

helm repo update kong
helm upgrade --install kong-operator kong/kong-operator \
  -n kong-system \
  --create-namespace \
  --take-ownership \
  --set env.ENABLE_CONTROLLER_KONNECT=true \
  --set ko-crds.enabled=true \
  --set global.webhooks.conversion.enabled=true \
  --set global.webhooks.options.certManager.enabled=true

Note: The --take-ownership flag is required if CRDs or other resources were previously installed or managed by another tool (such as kubectl or a previous Helm release). This ensures Helm can properly manage and upgrade those resources as part of the new release. Only set global.conversionWebhook.certManager.enabled to true if you are using cert-manager to manage the lifecycle of your webhook certificates.

Step 4: Verify the installation

Verify that Kong Operator 2.0.0 is running correctly.

1. Check the Kong Operator deployment:

   kubectl get pod -n kong-system
   

   Copied!
2. Check Kong Operator logs:

    kubectl logs -n kong-system -l app=kong-operator-kong-operator
   

   Copied!