Service annotations

Kong Operator supports a set of konghq.com/* annotations on Kubernetes Service resources. These annotations configure how Kong Gateway communicates with the upstream service — including protocols, timeouts, retries, host headers, and TLS settings.

Annotations are placed on the Service object that is referenced as a backendRef in an HTTPRoute. For example:

apiVersion: v1
kind: Service
metadata:
  name: my-service
  namespace: kong
  annotations:
    konghq.com/connect-timeout: "3000"
    konghq.com/read-timeout: "10000"
    konghq.com/retries: "3"
spec:
  ports:
    - port: 80

Sets the protocol Kong Gateway uses to communicate with the upstream Kubernetes service.

Accepted values:

• http
• https
• grpc
• grpcs
• tcp
• tls

Sample usage:

konghq.com/protocol: "https"

Prepends an HTTP path segment to every request forwarded to the upstream service.

For example, if the annotation is set to /api and the incoming request path is /orders/123, the upstream service receives /api/orders/123.

Sample usage:

konghq.com/path: "/api"

Sets the value of the Host header sent to the upstream service. By default, Kong Gateway sets Host to the IP address of the individual Pod target.

This annotation overrides that default with a static hostname, which is useful when upstream services perform host-based virtual hosting.

Sample usage:

konghq.com/host-header: "internal.example.com"

Sets the TLS client certificate and key pair that Kong Gateway presents to the upstream service when the upstream requires mutual TLS (mTLS) authentication.

The value must be the name of a Kubernetes Secret of type kubernetes.io/tls in the same namespace as the Service.

Sample usage:

konghq.com/client-cert: "my-client-cert-secret"

Attaches a KongUpstreamPolicy resource to the Service, allowing fine-grained control over load balancing behavior such as algorithm selection, consistent hashing, and health checks.

The value is the name of a KongUpstreamPolicy object in the same namespace as the Service. See the KongUpstreamPolicy reference for the full list of configuration fields.

Sample usage:

konghq.com/upstream-policy: "my-upstream-policy"

Sets the timeout for completing a TCP connection to the upstream service, in milliseconds. If the connection cannot be established within this time, Kong Gateway returns an error to the client.

Sample usage:

konghq.com/connect-timeout: "3000"

Sets the timeout for receiving the first byte of an HTTP response from the upstream service after sending the request, in milliseconds.

Sample usage:

konghq.com/read-timeout: "10000"

Sets the timeout for sending data to the upstream service before closing the connection, in milliseconds.

Sample usage:

konghq.com/write-timeout: "10000"

Sets the maximum number of times Kong Gateway retries a failed request to the upstream service. A request is retried if the upstream returns a connection failure or timeout.

Sample usage:

konghq.com/retries: "3"

Enables or disables verification of the upstream service’s TLS certificate when konghq.com/protocol is set to https or grpcs. Accepted values are "true" or "false". Verification is disabled by default.

Sample usage:

konghq.com/tls-verify: "true"

Sets the maximum certificate chain depth when verifying the upstream service’s TLS certificate. If not set, the system default is used.

Sample usage:

konghq.com/tls-verify-depth: "3"