Skip to content
Kong Docs are moving soon! Our docs are migrating to a new home. You'll be automatically redirected to the new site in the future. In the meantime, view this page on the new site!
Kong Logo | Kong Docs Logo
  • Docs
    • Explore the API Specs
      View all API Specs View all API Specs View all API Specs arrow image
    • Documentation
      API Specs
      Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong AI Gateway
      Multi-LLM AI Gateway for GenAI infrastructure
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Kong Gateway Operator
      Manage your Kong deployments on Kubernetes using YAML Manifests
      Insomnia
      Collaborative API development platform
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      AI's icon
      AI
      Govern, secure, and control AI traffic with multi-LLM AI Gateway plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Ingress Controller
3.0.x
  • Home icon
  • Kong Ingress Controller
  • Reference
  • Custom Resource Definitions API Reference
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Kong AI Gateway
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Kong Gateway Operator
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • unreleased
  • 3.4.x (latest) (LTS)
  • 3.3.x
  • 3.2.x
  • 3.1.x
  • 3.0.x
  • 2.12.x (LTS)
  • 2.11.x
  • 2.10.x
  • 2.9.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • 2.5.x (LTS)
  • Introduction
    • Overview
    • Kubernetes Gateway API
    • Version Support Policy
    • Changelog
  • How KIC Works
    • Architecture
    • Gateway API
    • Ingress
    • Custom Resources
    • Using Annotations
    • Admission Webhook
  • Get Started
    • Install KIC
    • Services and Routes
    • Rate Limiting
    • Proxy Caching
    • Key Authentication
  • KIC in Production
    • Deployment Topologies
      • Overview
      • Gateway Discovery
      • Database Backed
      • Traditional (sidecar)
    • Installation Methods
      • Helm
      • Kong Gateway Operator
    • Cloud Deployment
      • Azure
      • Amazon
      • Google
    • Enterprise License
    • Observability
      • Prometheus Metrics
      • Configuring Prometheus and Grafana
      • Kubernetes Events
    • Upgrading
      • Kong Gateway
      • Ingress Controller
  • Guides
    • Service Configuration
      • HTTP Service
      • TCP Service
      • UDP Service
      • gRPC Service
      • TLS
      • External Service
      • HTTPS Redirects
      • Multiple Backend Services
      • Configuring Gateway API resources across namespaces
    • Request Manipulation
      • Rewriting Hosts and Paths
      • Rewrite Annotation
      • Customizing load-balancing behavior
    • High Availability
      • KIC High Availability
      • Service Health Checks
      • Last Known Good Config
    • Security
      • Kong Vaults
      • Using Workspaces
      • Preserving Client IP
      • Kubernetes Secrets in Plugins
    • Migrate
      • KongIngress to KongUpstreamPolicy
      • Migrating from Ingress to Gateway
      • Credential Type Labels
    • Customize Deployments
      • Images
    • Custom Ingress Class
      • Internal / External Traffic
  • Plugins
    • Custom Plugins
    • Authentication
    • ACL
    • Rate Limiting
    • mTLS
    • OIDC
  • Reference
    • Troubleshooting
    • Version Compatibility
    • Annotations
    • Configuration Options
    • Feature Gates
    • FAQ
      • Plugin Compatibility
      • Kong Router
      • Custom nginx.conf
    • Custom Resource Definitions
    • Resources Requiring Setting Ingress Class
    • Gateway API migration
    • Required Permissions for Installation
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Packages
  • configuration.konghq.com/v1
    • KongClusterPlugin
    • KongConsumer
    • KongIngress
    • KongPlugin
    • ConfigSource
    • KongIngressRoute
    • KongIngressService
    • KongIngressUpstream
    • KongProtocol
    • NamespacedConfigSource
    • NamespacedSecretValueFromSource
    • SecretValueFromSource
  • configuration.konghq.com/v1alpha1
    • IngressClassParameters
    • IngressClassParametersSpec
  • configuration.konghq.com/v1beta1
    • KongConsumerGroup
    • KongUpstreamPolicy
    • TCPIngress
    • UDPIngress
    • HTTPStatus
    • HashInput
    • IngressBackend
    • IngressRule
    • IngressTLS
    • KongUpstreamActiveHealthcheck
    • KongUpstreamHash
    • KongUpstreamHealthcheck
    • KongUpstreamHealthcheckHealthy
    • KongUpstreamHealthcheckUnhealthy
    • KongUpstreamPassiveHealthcheck
    • KongUpstreamPolicySpec
    • TCPIngressSpec
    • UDPIngressRule
    • UDPIngressSpec
You are browsing documentation for an older version. See the latest documentation here.

Custom Resource Definitions API Reference

Packages

  • configuration.konghq.com/v1
  • configuration.konghq.com/v1alpha1
  • configuration.konghq.com/v1beta1

configuration.konghq.com/v1

Package v1 contains API Schema definitions for the konghq.com v1 API group.

  • KongClusterPlugin
  • KongConsumer
  • KongIngress
  • KongPlugin

KongClusterPlugin

KongClusterPlugin is the Schema for the kongclusterplugins API.

The only differences between KongPlugin and KongClusterPlugin are that KongClusterPlugin is a Kubernetes cluster-level resource instead of a namespaced resource, and can be applied as a global plugin using global label.

Field Description
apiVersion string configuration.konghq.com/v1
kind string KongClusterPlugin
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
consumerRef string ConsumerRef is a reference to a particular consumer.
disabled boolean Disabled set if the plugin is disabled or not.
config JSON Config contains the plugin configuration. It’s a list of keys and values required to configure the plugin. Please read the documentation of the plugin being configured to set values in here. For any plugin in Kong, anything that goes in the config JSON key in the Admin API request, goes into this property. Only one of config or configFrom may be used in a KongClusterPlugin, not both at once.
configFrom NamespacedConfigSource ConfigFrom references a secret containing the plugin configuration. This should be used when the plugin configuration contains sensitive information, such as AWS credentials in the Lambda plugin or the client secret in the OIDC plugin. Only one of config or configFrom may be used in a KongClusterPlugin, not both at once.
plugin string PluginName is the name of the plugin to which to apply the config.
run_on string RunOn configures the plugin to run on the first or the second or both nodes in case of a service mesh deployment.
protocols KongProtocol array Protocols configures plugin to run on requests received on specific protocols.
ordering PluginOrdering Ordering overrides the normal plugin execution order. It’s only available on Kong Enterprise. <phase> is a request processing phase (for example, access or body_filter) and <plugin> is the name of the plugin that will run before or after the KongPlugin. For example, a KongPlugin with plugin: rate-limiting and before.access: ["key-auth"] will create a rate limiting plugin that limits requests before they are authenticated.
instance_name string InstanceName is an optional custom name to identify an instance of the plugin. This is useful when running the same plugin in multiple contexts, for example, on multiple services.

KongConsumer

KongConsumer is the Schema for the kongconsumers API.

When this resource is created, a corresponding consumer entity will be created in Kong. While KongConsumer exists in a specific Kubernetes namespace, KongConsumers from all namespaces are combined into a single Kong configuration, and no KongConsumers with the same kubernetes.io/ingress.class may share the same Username or CustomID value.

Field Description
apiVersion string configuration.konghq.com/v1
kind string KongConsumer
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
username string Username is a Kong cluster-unique username of the consumer.
custom_id string CustomID is a Kong cluster-unique existing ID for the consumer - useful for mapping Kong with users in your existing database.
credentials string array Credentials are references to secrets containing a credential to be provisioned in Kong.
consumerGroups string array ConsumerGroups are references to consumer groups (that consumer wants to be part of) provisioned in Kong.

KongIngress

KongIngress is the Schema for the kongingresses API.

It serves as an “extension” to Ingress resource. It is not meant as a replacement to the Ingress resource in Kubernetes. The Ingress resource spec in Kubernetes can define routing policies based on HTTP Host header and paths. While this is sufficient in most cases, sometimes, users may want more control over routing at the Ingress level. Once a KongIngress resource is created, it needs to be associated with an Ingress or Service resource using the konghq.com/override annotation.

KongIngress is not supported on Gateway APIs resources, such as HTTPRoute and TCPRoute. These resources must use annotations.

As of version 2.8, KongIngress sections other than upstream are deprecated. All settings in the proxy and route sections are now available with dedicated annotations, and these annotations will become the only means of configuring those settings in a future release. For example, if you had set proxy.connect_timeout: 30000 in a KongIngress and applied an konghq.com/override annotation for that KongIngress to a Service, you will need to instead apply a konghq.com/connect-timeout: 30000 annotation to the Service.

Plans are to replace the upstream section of KongIngress with a new resource, but this is still in development and upstream is not yet officially deprecated.

Field Description
apiVersion string configuration.konghq.com/v1
kind string KongIngress
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
upstream KongIngressUpstream Upstream represents a virtual hostname and can be used to loadbalance incoming requests over multiple targets (e.g. Kubernetes Services can be a target, OR Endpoints can be targets).
proxy KongIngressService Proxy defines additional connection options for the routes to be configured in the Kong Gateway, e.g. connection_timeout, retries, etc.
route KongIngressRoute Route define rules to match client requests. Each Route is associated with a Service, and a Service may have multiple Routes associated to it.

KongPlugin

KongPlugin is the Schema for the kongplugins API.

Plugins can be associated with the Ingress, Service, HTTPRoute, KongConsumer or KongConsumerGroup object in Kubernetes using konghq.com/plugins annotation.

Field Description
apiVersion string configuration.konghq.com/v1
kind string KongPlugin
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
consumerRef string ConsumerRef is a reference to a particular consumer.
disabled boolean Disabled set if the plugin is disabled or not.
config JSON Config contains the plugin configuration. It’s a list of keys and values required to configure the plugin. Please read the documentation of the plugin being configured to set values in here. For any plugin in Kong, anything that goes in the config JSON key in the Admin API request, goes into this property. Only one of config or configFrom may be used in a KongPlugin, not both at once.
configFrom ConfigSource ConfigFrom references a secret containing the plugin configuration. This should be used when the plugin configuration contains sensitive information, such as AWS credentials in the Lambda plugin or the client secret in the OIDC plugin. Only one of config or configFrom may be used in a KongPlugin, not both at once.
plugin string PluginName is the name of the plugin to which to apply the config.
run_on string RunOn configures the plugin to run on the first or the second or both nodes in case of a service mesh deployment.
protocols KongProtocol array Protocols configures plugin to run on requests received on specific protocols.
ordering PluginOrdering Ordering overrides the normal plugin execution order. It’s only available on Kong Enterprise. <phase> is a request processing phase (for example, access or body_filter) and <plugin> is the name of the plugin that will run before or after the KongPlugin. For example, a KongPlugin with plugin: rate-limiting and before.access: ["key-auth"] will create a rate limiting plugin that limits requests before they are authenticated.
instance_name string InstanceName is an optional custom name to identify an instance of the plugin. This is useful when running the same plugin in multiple contexts, for example, on multiple services.

ConfigSource

ConfigSource is a wrapper around SecretValueFromSource.

Field Description
secretKeyRef SecretValueFromSource Specifies a name and a key of a secret to refer to. The namespace is implicitly set to the one of referring object.

Appears in:

  • KongPlugin

KongIngressRoute

KongIngressRoute contains KongIngress route configuration. It contains the subset of go-kong.kong.Route fields supported by kongstate.Route.overrideByKongIngress. Deprecated: use Ingress’ annotations instead.

Field Description
methods string array Methods is a list of HTTP methods that match this Route. Deprecated: use Ingress’ “konghq.com/methods” annotation instead.
headers object (keys:string, values:string array) Headers contains one or more lists of values indexed by header name that will cause this Route to match if present in the request. The Host header cannot be used with this attribute. Deprecated: use Ingress’ “konghq.com/headers” annotation instead.
protocols KongProtocol array Protocols is an array of the protocols this Route should allow. Deprecated: use Ingress’ “konghq.com/protocols” annotation instead.
regex_priority integer RegexPriority is a number used to choose which route resolves a given request when several routes match it using regexes simultaneously. Deprecated: use Ingress’ “konghq.com/regex-priority” annotation instead.
strip_path boolean StripPath sets When matching a Route via one of the paths strip the matching prefix from the upstream request URL. Deprecated: use Ingress’ “konghq.com/strip-path” annotation instead.
preserve_host boolean PreserveHost sets When matching a Route via one of the hosts domain names, use the request Host header in the upstream request headers. If set to false, the upstream Host header will be that of the Service’s host. Deprecated: use Ingress’ “konghq.com/preserve-host” annotation instead.
https_redirect_status_code integer HTTPSRedirectStatusCode is the status code Kong responds with when all properties of a Route match except the protocol. Deprecated: use Ingress’ “ingress.kubernetes.io/force-ssl-redirect” or “konghq.com/https-redirect-status-code” annotations instead.
path_handling string PathHandling controls how the Service path, Route path and requested path are combined when sending a request to the upstream. Deprecated: use Ingress’ “konghq.com/path-handling” annotation instead.
snis string array SNIs is a list of SNIs that match this Route when using stream routing. Deprecated: use Ingress’ “konghq.com/snis” annotation instead.
request_buffering boolean RequestBuffering sets whether to enable request body buffering or not. Deprecated: use Ingress’ “konghq.com/request-buffering” annotation instead.
response_buffering boolean ResponseBuffering sets whether to enable response body buffering or not. Deprecated: use Ingress’ “konghq.com/response-buffering” annotation instead.

Appears in:

  • KongIngress

KongIngressService

KongIngressService contains KongIngress service configuration. It contains the subset of go-kong.kong.Service fields supported by kongstate.Service.overrideByKongIngress. Deprecated: use Service’s annotations instead.

Field Description
protocol string The protocol used to communicate with the upstream. Deprecated: use Service’s “konghq.com/protocol” annotation instead.
path string (optional) The path to be used in requests to the upstream server. Deprecated: use Service’s “konghq.com/path” annotation instead.
retries integer The number of retries to execute upon failure to proxy. Deprecated: use Service’s “konghq.com/retries” annotation instead.
connect_timeout integer The timeout in milliseconds for establishing a connection to the upstream server. Deprecated: use Service’s “konghq.com/connect-timeout” annotation instead.
read_timeout integer The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. Deprecated: use Service’s “konghq.com/read-timeout” annotation instead.
write_timeout integer The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. Deprecated: use Service’s “konghq.com/write-timeout” annotation instead.

Appears in:

  • KongIngress

KongIngressUpstream

KongIngressUpstream contains KongIngress upstream configuration. It contains the subset of go-kong.kong.Upstream fields supported by kongstate.Upstream.overrideByKongIngress.

Field Description
host_header string HostHeader is The hostname to be used as Host header when proxying requests through Kong.
algorithm string Algorithm is the load balancing algorithm to use. Accepted values are: “round-robin”, “consistent-hashing”, “least-connections”, “latency”.
slots integer Slots is the number of slots in the load balancer algorithm.
healthchecks Healthcheck Healthchecks defines the health check configurations in Kong.
hash_on string HashOn defines what to use as hashing input. Accepted values are: “none”, “consumer”, “ip”, “header”, “cookie”, “path”, “query_arg”, “uri_capture”.
hash_fallback string HashFallback defines What to use as hashing input if the primary hash_on does not return a hash. Accepted values are: “none”, “consumer”, “ip”, “header”, “cookie”.
hash_on_header string HashOnHeader defines the header name to take the value from as hash input. Only required when “hash_on” is set to “header”.
hash_fallback_header string HashFallbackHeader is the header name to take the value from as hash input. Only required when “hash_fallback” is set to “header”.
hash_on_cookie string The cookie name to take the value from as hash input. Only required when “hash_on” or “hash_fallback” is set to “cookie”.
hash_on_cookie_path string The cookie path to set in the response headers. Only required when “hash_on” or “hash_fallback” is set to “cookie”.
hash_on_query_arg string HashOnQueryArg is the query string parameter whose value is the hash input when “hash_on” is set to “query_arg”.
hash_fallback_query_arg string HashFallbackQueryArg is the “hash_fallback” version of HashOnQueryArg.
hash_on_uri_capture string HashOnURICapture is the name of the capture group whose value is the hash input when “hash_on” is set to “uri_capture”.
hash_fallback_uri_capture string HashFallbackURICapture is the “hash_fallback” version of HashOnURICapture.

Appears in:

  • KongIngress

KongProtocol

Underlying type: string

KongProtocol is a valid Kong protocol. This alias is necessary to deal with https://github.com/kubernetes-sigs/controller-tools/issues/342

Appears in:

  • KongClusterPlugin
  • KongIngressRoute
  • KongPlugin

NamespacedConfigSource

NamespacedConfigSource is a wrapper around NamespacedSecretValueFromSource.

Field Description
secretKeyRef NamespacedSecretValueFromSource Specifies a name, a namespace, and a key of a secret to refer to.

Appears in:

  • KongClusterPlugin

NamespacedSecretValueFromSource

NamespacedSecretValueFromSource represents the source of a secret value specifying the secret namespace.

Field Description
namespace string The namespace containing the secret.
name string The secret containing the key.
key string The key containing the value.

Appears in:

  • NamespacedConfigSource

SecretValueFromSource

SecretValueFromSource represents the source of a secret value.

Field Description
name string The secret containing the key.
key string The key containing the value.

Appears in:

  • ConfigSource

configuration.konghq.com/v1alpha1

Package v1alpha1 contains API Schema definitions for the configuration.konghq.com v1alpha1 API group.

  • IngressClassParameters

IngressClassParameters

IngressClassParameters is the Schema for the IngressClassParameters API.

Field Description
apiVersion string configuration.konghq.com/v1alpha1
kind string IngressClassParameters
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec IngressClassParametersSpec Spec is the IngressClassParameters specification.

IngressClassParametersSpec

Field Description
serviceUpstream boolean Offload load-balancing to kube-proxy or sidecar.
enableLegacyRegexDetection boolean EnableLegacyRegexDetection automatically detects if ImplementationSpecific Ingress paths are regular expression paths using the legacy 2.x heuristic. The controller adds the “~” prefix to those paths if the Kong version is 3.0 or higher.

Appears in:

  • IngressClassParameters

configuration.konghq.com/v1beta1

Package v1beta1 contains API Schema definitions for the configuration.konghq.com v1beta1 API group.

  • KongConsumerGroup
  • KongUpstreamPolicy
  • TCPIngress
  • UDPIngress

KongConsumerGroup

KongConsumerGroup is the Schema for the kongconsumergroups API.

KongConsumerGroup resources create consumer group resources.

Field Description
apiVersion string configuration.konghq.com/v1beta1
kind string KongConsumerGroup
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.

KongUpstreamPolicy

KongUpstreamPolicy allows configuring algorithm that should be used for load balancing traffic between Kong Upstream’s Targets. It also allows configuring health checks for Kong Upstream’s Targets.

Its configuration is similar to Kong Upstream object (/gateway/api/admin-ee/latest/#/operations/list-upstream/), and it is applied to Kong Upstream objects created by the controller.

It can be attached to Services. To attach it to a Service, it has to be annotated with konghq.com/upstream-policy: <name>, where <name> is the name of the KongUpstreamPolicy object in the same namespace as the Service.

When attached to a Service, it will affect all Kong Upstreams created for the Service.

When attached to a Service used in a Gateway API Route rule with multiple BackendRefs, all of its Services MUST be configured with the same KongUpstreamPolicy. Otherwise, the controller will *ignore the KongUpstreamPolicy.

Note: KongUpstreamPolicy doesn’t implement Gateway API’s GEP-713 strictly. In particular, it doesn’t use the TargetRef for attaching to Services and Gateway API *Routes - annotations are used instead. This is to allow reusing the same KongUpstreamPolicy for multiple Services and Gateway API *Routes.

See migrate KongIngress to KongUpstreamPolicy and customizing load balancing.

Field Description
apiVersion string configuration.konghq.com/v1beta1
kind string KongUpstreamPolicy
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec KongUpstreamPolicySpec Spec contains the configuration of the Kong upstream.

TCPIngress

TCPIngress is the Schema for the tcpingresses API.

The Ingress resource in Kubernetes is HTTP-only. This custom resource is modeled similar to the Ingress resource, but for TCP and TLS SNI based routing purposes.

Field Description
apiVersion string configuration.konghq.com/v1beta1
kind string TCPIngress
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec TCPIngressSpec Spec is the TCPIngress specification.

UDPIngress

UDPIngress is the Schema for the udpingresses API.

It makes it possible to route traffic to your UDP services using Kong (for example, DNS or Game Servers). For each rule provided in the spec, the Kong proxy environment must be updated to listen to UDP on that port as well.

Field Description
apiVersion string configuration.konghq.com/v1beta1
kind string UDPIngress
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec UDPIngressSpec Spec is the UDPIngress specification.

HTTPStatus

Underlying type: integer

HTTPStatus is an HTTP status code.

Appears in:

  • KongUpstreamHealthcheckHealthy
  • KongUpstreamHealthcheckUnhealthy

HashInput

Underlying type: string

HashInput is the input for consistent-hashing load balancing algorithm. Can be one of: “ip”, “consumer”, “path”.

Appears in:

  • KongUpstreamHash

IngressBackend

IngressBackend describes all endpoints for a given service and port.

Field Description
serviceName string Specifies the name of the referenced service.
servicePort integer Specifies the port of the referenced service.

Appears in:

  • IngressRule
  • UDPIngressRule

IngressRule

IngressRule represents a rule to apply against incoming requests. Matching is performed based on an (optional) SNI and port.

Field Description
host string Host is the fully qualified domain name of a network host, as defined by RFC 3986. If a Host is not specified, then port-based TCP routing is performed. Kong doesn’t care about the content of the TCP stream in this case. If a Host is specified, the protocol must be TLS over TCP. A plain-text TCP request cannot be routed based on Host. It can only be routed based on Port.
port integer Port is the port on which to accept TCP or TLS over TCP sessions and route. It is a required field. If a Host is not specified, the requested are routed based only on Port.
backend IngressBackend Backend defines the referenced service endpoint to which the traffic will be forwarded to.

Appears in:

  • TCPIngressSpec

IngressTLS

IngressTLS describes the transport layer security.

Field Description
hosts string array Hosts are a list of hosts included in the TLS certificate. The values in this list must match the name/s used in the tlsSecret. Defaults to the wildcard host setting for the loadbalancer controller fulfilling this Ingress, if left unspecified.
secretName string SecretName is the name of the secret used to terminate SSL traffic.

Appears in:

  • TCPIngressSpec

KongUpstreamActiveHealthcheck

KongUpstreamActiveHealthcheck configures active health check probing.

Field Description
type string Type determines whether to perform active health checks using HTTP or HTTPS, or just attempt a TCP connection. Accepted values are “http”, “https”, “tcp”, “grpc”, “grpcs”.
concurrency integer Concurrency is the number of targets to check concurrently.
healthy KongUpstreamHealthcheckHealthy Healthy configures thresholds and HTTP status codes to mark targets healthy for an upstream.
unhealthy KongUpstreamHealthcheckUnhealthy Unhealthy configures thresholds and HTTP status codes to mark targets unhealthy for an upstream.
httpPath string HTTPPath is the path to use in GET HTTP request to run as a probe.
httpsSni string HTTPSSNI is the SNI to use in GET HTTPS request to run as a probe.
httpsVerifyCertificate boolean HTTPSVerifyCertificate is a boolean value that indicates if the certificate should be verified.
timeout integer Timeout is the probe timeout in seconds.
headers object (keys:string, values:string array) Headers is a list of HTTP headers to add to the probe request.

Appears in:

  • KongUpstreamHealthcheck

KongUpstreamHash

KongUpstreamHash defines how to calculate hash for consistent-hashing load balancing algorithm. Only one of the fields must be set.

Field Description
input HashInput Input allows using one of the predefined inputs (ip, consumer, path). For other parametrized inputs, use one of the fields below.
header string Header is the name of the header to use as hash input.
cookie string Cookie is the name of the cookie to use as hash input.
cookiePath string CookiePath is cookie path to set in the response headers.
queryArg string QueryArg is the name of the query argument to use as hash input.
uriCapture string URICapture is the name of the URI capture group to use as hash input.

Appears in:

  • KongUpstreamPolicySpec

KongUpstreamHealthcheck

KongUpstreamHealthcheck represents a health-check config of an Upstream in Kong.

Field Description
active KongUpstreamActiveHealthcheck Active configures active health check probing.
passive KongUpstreamPassiveHealthcheck Passive configures passive health check probing.
threshold integer Threshold is the minimum percentage of the upstream’s targets’ weight that must be available for the whole upstream to be considered healthy.

Appears in:

  • KongUpstreamPolicySpec

KongUpstreamHealthcheckHealthy

KongUpstreamHealthcheckHealthy configures thresholds and HTTP status codes to mark targets healthy for an upstream.

Field Description
httpStatuses HTTPStatus array HTTPStatuses is a list of HTTP status codes that Kong considers a success.
interval integer Interval is the interval between active health checks for an upstream in seconds when in a healthy state.
successes integer Successes is the number of successes to consider a target healthy.

Appears in:

  • KongUpstreamActiveHealthcheck
  • KongUpstreamPassiveHealthcheck

KongUpstreamHealthcheckUnhealthy

KongUpstreamHealthcheckUnhealthy configures thresholds and HTTP status codes to mark targets unhealthy.

Field Description
httpFailures integer HTTPFailures is the number of failures to consider a target unhealthy.
httpStatuses HTTPStatus array HTTPStatuses is a list of HTTP status codes that Kong considers a failure.
tcpFailures integer TCPFailures is the number of TCP failures in a row to consider a target unhealthy.
timeouts integer Timeouts is the number of timeouts in a row to consider a target unhealthy.
interval integer Interval is the interval between active health checks for an upstream in seconds when in an unhealthy state.

Appears in:

  • KongUpstreamActiveHealthcheck
  • KongUpstreamPassiveHealthcheck

KongUpstreamPassiveHealthcheck

KongUpstreamPassiveHealthcheck configures passive checks around passive health checks.

Field Description
type string Type determines whether to perform passive health checks interpreting HTTP/HTTPS statuses, or just check for TCP connection success. Accepted values are “http”, “https”, “tcp”, “grpc”, “grpcs”.
healthy KongUpstreamHealthcheckHealthy Healthy configures thresholds and HTTP status codes to mark targets healthy for an upstream.
unhealthy KongUpstreamHealthcheckUnhealthy Unhealthy configures thresholds and HTTP status codes to mark targets unhealthy.

Appears in:

  • KongUpstreamHealthcheck

KongUpstreamPolicySpec

KongUpstreamPolicySpec contains the specification for KongUpstreamPolicy.

Field Description
algorithm string Algorithm is the load balancing algorithm to use. Accepted values are: “round-robin”, “consistent-hashing”, “least-connections”, “latency”.
slots integer Slots is the number of slots in the load balancer algorithm. If not set, the default value in Kong for the algorithm is used.
hashOn KongUpstreamHash HashOn defines how to calculate hash for consistent-hashing load balancing algorithm. Algorithm must be set to “consistent-hashing” for this field to have effect.
hashOnFallback KongUpstreamHash HashOnFallback defines how to calculate hash for consistent-hashing load balancing algorithm if the primary hash function fails. Algorithm must be set to “consistent-hashing” for this field to have effect.
healthchecks KongUpstreamHealthcheck Healthchecks defines the health check configurations in Kong.

Appears in:

  • KongUpstreamPolicy

TCPIngressSpec

TCPIngressSpec defines the desired state of TCPIngress.

Field Description
rules IngressRule array A list of rules used to configure the Ingress.
tls IngressTLS array TLS configuration. This is similar to the tls section in the Ingress resource in networking.v1beta1 group. The mapping of SNIs to TLS cert-key pair defined here will be used for HTTP Ingress rules as well. Once can define the mapping in this resource or the original Ingress resource, both have the same effect.

Appears in:

  • TCPIngress

UDPIngressRule

UDPIngressRule represents a rule to apply against incoming requests wherein no Host matching is available for request routing, only the port is used to match requests.

Field Description
port integer Port indicates the port for the Kong proxy to accept incoming traffic on, which will then be routed to the service Backend.
backend IngressBackend Backend defines the Kubernetes service which accepts traffic from the listening Port defined above.

Appears in:

  • UDPIngressSpec

UDPIngressSpec

UDPIngressSpec defines the desired state of UDPIngress.

Field Description
rules UDPIngressRule array A list of rules used to configure the Ingress.

Appears in:

  • UDPIngress
Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    Powering the API world

    Increase developer productivity, security, and performance at scale with the unified platform for API management, service mesh, and ingress controller.

    • Products
      • Kong Konnect
      • Kong Gateway Enterprise
      • Kong Gateway
      • Kong Mesh
      • Kong Ingress Controller
      • Kong Insomnia
      • Product Updates
      • Get Started
    • Documentation
      • Kong Konnect Docs
      • Kong Gateway Docs
      • Kong Mesh Docs
      • Kong Insomnia Docs
      • Kong Konnect Plugin Hub
    • Open Source
      • Kong Gateway
      • Kuma
      • Insomnia
      • Kong Community
    • Company
      • About Kong
      • Customers
      • Careers
      • Press
      • Events
      • Contact
  • Terms• Privacy• Trust and Compliance
© Kong Inc. 2025