Skip to content
|
Kong Ingress Controller
3.0.x
github-edit-pageEdit this page
report-issueReport an issue
You are browsing documentation for an older version. See the latest documentation here.

Custom Resource Definitions API Reference

Packages

configuration.konghq.com/v1

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

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:

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:

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:

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:

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:

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:

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:

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:

configuration.konghq.com/v1alpha1

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

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:

configuration.konghq.com/v1beta1

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

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/#/Upstreams/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:

HashInput

Underlying type: string

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

Appears in:

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

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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 defines the desired state of UDPIngress.

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

Appears in: