Migrating from KongIngress to annotations and KongUpstreamPolicy

Important: KongIngress Deprecation Notice

The KongIngress custom resource is deprecated as of Kong Ingress Controller 3.5 and will be completely removed in Kong Operator 2.0.0.

Migration is required before upgrading to Kong Operator 2.0.0:

• The proxy and route sections are already deprecated and replaced by dedicated annotations
• The upstream section is being replaced by the new KongUpstreamPolicy resource
• KongIngress is not supported with Gateway API resources (HTTPRoute, TCPRoute, etc.)

Use this guide to migrate your existing KongIngress resources to their modern equivalents.

The KongIngress resource was originally designed to extend the capabilities of the standard Kubernetes Ingress resource. However, as the Kubernetes ecosystem evolved and the Gateway API matured, KongIngress has become redundant and is being phased out in favor of:

• Annotations: For simple proxy and route configurations
• KongUpstreamPolicy: For complex upstream configurations
• Gateway API: For advanced routing and traffic management

The migration approach depends on which sections of KongIngress you’re using.

The upstream section is replaced by the KongUpstreamPolicy resource.

Proxy and route sections (already deprecated) are replaced by dedicated annotations:

The following is an example of how to migrate the proxy and route sections.

If you have a KongIngress like this:

apiVersion: configuration.konghq.com/v1
kind: KongIngress
metadata:
  name: example-kongingress
proxy:
  connect_timeout: 30000
  read_timeout: 60000
  retries: 5
route:
  methods:
  - GET
  - POST
  strip_path: true
  preserve_host: true

Replace it with annotations on your Service or Ingress:

apiVersion: v1
kind: Service
metadata:
  name: example-service
  annotations:
    konghq.com/connect-timeout: "30000"
    konghq.com/read-timeout: "60000"
    konghq.com/retries: "5"
    konghq.com/methods: "GET,POST"
    konghq.com/strip-path: "true"
    konghq.com/preserve-host: "true"
spec:
  # service configuration...

The konghq.com/headers.* annotation uses a special format to set headers. The string after the . in the annotation name is the header name and the annotation value is the header value. For example, to apply x-custom-header-a: example,otherexample and x-custom-header-b: example headers to requests, the KongIngress configuration is:

route:
  headers:
    x-custom-header-a:
    - example
    - otherexample
    x-custom-header-b:
    - example

The equivalent annotation configuration looks like:

konghq.com/headers.x-custom-header-a: example,otherexample
konghq.com/headers.x-custom-header-b: example

You cannot apply multiple instances of the same header annotation to set multiple header values. You must set the CSV format within a single header.

The upstream section of KongIngress resources contains a complex object that does not easily fit in annotations. Version 3.x uses the new KongUpstreamPolicy resource to configure upstream settings. The spec field of KongUpstreamPolicy is similar to the upstream section of KongIngress, with the following differences:

• Field names now use lowerCamelCase instead of snake_case to be consistent with Kubernetes APIs.
• hash_on, hash_fallback, and their related has_on_*, hash_fallback_* fields are now hashOn and hashOnFallback objects. To define the primary hashing strategy, use hashOn with one of its fields filled (e.g. when you want to hash on a header, fill hashOn.header with a header name). Similarly, to define the secondary hashing strategy, use hashOnFallback.

For the exact schema please refer to KongUpstreamPolicy reference.

For example, if you previously used a KongIngress like:

apiVersion: configuration.konghq.com/v1
kind: KongIngress
metadata:
  name: sample-customization
upstream:
  hash_on: header
  hash_on_header: x-lb
  hash_fallback: ip
  algorithm: consistent-hashing

You need to use a KongUpstreamPolicy:

apiVersion: configuration.konghq.com/v1beta1
kind: KongUpstreamPolicy
metadata:
  name: sample-customization
spec:
  hashOn:
    header: x-lb
  hashOnFallback:
    input: ip
  algorithm: consistent-hashing

Apply it to a Service resource with a konghq.com/upstream-policy: sample-customization annotation.