Skip to content
2023 API Summit Hackathon: Experiment with AI for APIs (August 28 - September 27) Learn More →
|
search
Kong Ingress Controller
2.8.x
github-edit-pageEdit this page
report-issueReport an issue
You are browsing documentation for an outdated 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.

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.

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 or Service 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.

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/override-protocols” 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. 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.
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

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.

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.

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:

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: