From 8fc5f90966058b2aa04690c52c1b4d5ffef8aff1 Mon Sep 17 00:00:00 2001 From: Kong's Team k8s bot Date: Thu, 19 Dec 2024 17:36:00 +0100 Subject: [PATCH] chore: update docs for KIC 3.4.0 (#8298) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Synchronize auto-generated KIC API reference Signed-off-by: Kong's Team k8s bot * complete release docs Signed-off-by: Mattia Lavacca * Update app/_data/kong_versions.yml Co-authored-by: Patryk Małek --------- Signed-off-by: Kong's Team k8s bot Signed-off-by: Mattia Lavacca Co-authored-by: Mattia Lavacca Co-authored-by: Patryk Małek --- app/_data/kong_versions.yml | 5 +- .../reference/cli-arguments-3.4.x.md | 130 +++ .../reference/custom-resources-3.4.x.md | 908 ++++++++++++++++++ .../reference/version-compatibility.md | 61 +- .../support-policy.md | 1 + 5 files changed, 1076 insertions(+), 29 deletions(-) create mode 100644 app/_src/kubernetes-ingress-controller/reference/cli-arguments-3.4.x.md create mode 100644 app/_src/kubernetes-ingress-controller/reference/custom-resources-3.4.x.md diff --git a/app/_data/kong_versions.yml b/app/_data/kong_versions.yml index 7344343bd94f..1439e6be58ac 100644 --- a/app/_data/kong_versions.yml +++ b/app/_data/kong_versions.yml @@ -304,10 +304,13 @@ - release: "3.3.x" version: "3.3.1" edition: "kubernetes-ingress-controller" - latest: true - release: "3.4.x" version: "3.4.0" edition: "kubernetes-ingress-controller" + latest: true +- release: "3.5.x" + version: "3.5.0" + edition: "kubernetes-ingress-controller" label: unreleased - edition: gateway-operator version: 1.0.3 diff --git a/app/_src/kubernetes-ingress-controller/reference/cli-arguments-3.4.x.md b/app/_src/kubernetes-ingress-controller/reference/cli-arguments-3.4.x.md new file mode 100644 index 000000000000..324e9123e13f --- /dev/null +++ b/app/_src/kubernetes-ingress-controller/reference/cli-arguments-3.4.x.md @@ -0,0 +1,130 @@ +--- +title: CLI Arguments +--- + +Learn about the various settings and configurations of the controller can be tweaked +using CLI flags. + +## Environment variables + +Each flag defined in the table below can also be configured using +an environment variable. The name of the environment variable is `CONTROLLER_` +string followed by the name of flag in uppercase. + +For example, `--ingress-class` can be configured using the following +environment variable: + +``` +CONTROLLER_INGRESS_CLASS=kong-foobar +``` + +It is recommended that all the configuration is done through environment variables +and not CLI flags. + + + + + +## Flags + +| Flag | Type | Description | Default | +| ---- | ---- | ----------- | ------- | +| `--admission-webhook-cert` | `string` | Admission server PEM certificate value. Mutually exclusive with --admission-webhook-cert-file. | | +| `--admission-webhook-cert-file` | `string` | Admission server PEM certificate file path. If both this and the cert value is unset, defaults to /admission-webhook/tls.crt. Mutually exclusive with --admission-webhook-cert. | | +| `--admission-webhook-key` | `string` | Admission server PEM private key value. Mutually exclusive with --admission-webhook-key-file. | | +| `--admission-webhook-key-file` | `string` | Admission server PEM private key file path. If both this and the key value is unset, defaults to /admission-webhook/tls.key. Mutually exclusive with --admission-webhook-key. | | +| `--admission-webhook-listen` | `string` | The address to start admission controller on (ip:port). Setting it to 'off' disables the admission controller. | `off` | +| `--anonymous-reports` | `bool` | Send anonymized usage data to help improve Kong. | `true` | +| `--apiserver-burst` | `int` | The Kubernetes API RateLimiter maximum burst queries per second. | `300` | +| `--apiserver-host` | `string` | The Kubernetes API server URL. If not set, the controller will use cluster config discovery. | | +| `--apiserver-qps` | `int` | The Kubernetes API RateLimiter maximum queries per second. | `100` | +| `--cache-sync-timeout` | `duration` | The time limit set to wait for syncing controllers' caches. Set to 0 to use default from controller-runtime. | `2m0s` | +| `--cluster-domain` | `string` | The cluster domain. This is used e.g. in generating addresses for upstream services. | | +| `--configmap-label-selector` | `string` | Limits the configmaps ingested to those having this label set to "true". | `konghq.com/configmap` | +| `--dump-config` | `bool` | Enable config dumps via web interface host:10256/debug/config. | `false` | +| `--dump-sensitive-config` | `bool` | Include credentials and TLS secrets in configs exposed with --dump-config flag. | `false` | +| `--election-id` | `string` | Election id to use for status update. | `5b374a9e.konghq.com` | +| `--election-namespace` | `string` | Leader election namespace to use when running outside a cluster. | | +| `--emit-kubernetes-events` | `bool` | Emit Kubernetes events for successful configuration applies, translation failures and configuration apply failures on managed objects. | `true` | +| `--enable-controller-gwapi-gateway` | `bool` | Enable the Gateway API Gateway controller. | `true` | +| `--enable-controller-gwapi-grpcroute` | `bool` | Enable the Gateway API GRPCRoute controller. | `true` | +| `--enable-controller-gwapi-httproute` | `bool` | Enable the Gateway API HTTPRoute controller. | `true` | +| `--enable-controller-gwapi-reference-grant` | `bool` | Enable the Gateway API ReferenceGrant controller. | `true` | +| `--enable-controller-ingress-class-networkingv1` | `bool` | Enable the networking.k8s.io/v1 IngressClass controller. | `true` | +| `--enable-controller-ingress-class-parameters` | `bool` | Enable the IngressClassParameters controller. | `true` | +| `--enable-controller-ingress-networkingv1` | `bool` | Enable the networking.k8s.io/v1 Ingress controller. | `true` | +| `--enable-controller-kong-custom-entity` | `bool` | Enable the KongCustomEntity controller. | `true` | +| `--enable-controller-kong-license` | `bool` | Enable the KongLicense controller. | `true` | +| `--enable-controller-kong-service-facade` | `bool` | Enable the KongServiceFacade controller. | `true` | +| `--enable-controller-kong-upstream-policy` | `bool` | Enable the KongUpstreamPolicy controller. | `true` | +| `--enable-controller-kong-vault` | `bool` | Enable the KongVault controller. | `true` | +| `--enable-controller-kongclusterplugin` | `bool` | Enable the KongClusterPlugin controller. | `true` | +| `--enable-controller-kongconsumer` | `bool` | Enable the KongConsumer controller. | `true` | +| `--enable-controller-kongingress` | `bool` | Enable the KongIngress controller. | `true` | +| `--enable-controller-kongplugin` | `bool` | Enable the KongPlugin controller. | `true` | +| `--enable-controller-service` | `bool` | Enable the Service controller. | `true` | +| `--enable-controller-tcpingress` | `bool` | Enable the TCPIngress controller. | `true` | +| `--enable-controller-udpingress` | `bool` | Enable the UDPIngress controller. | `true` | +| `--enable-reverse-sync` | `bool` | Send configuration to Kong even if the configuration checksum has not changed since previous update. | `false` | +| `--feature-gates` | `list of string=bool` | A set of comma separated key=value pairs that describe feature gates for alpha/beta/experimental features. See the Feature Gates documentation for information and available options: https://github.com/Kong/kubernetes-ingress-controller/blob/main/FEATURE_GATES.md. | | +| `--gateway-api-controller-name` | `string` | The controller name to match on Gateway API resources. | `konghq.com/kic-gateway-controller` | +| `--gateway-discovery-dns-strategy` | `dns-strategy` | DNS strategy to use when creating Gateway's Admin API addresses. One of: ip, service, pod. | `"ip"` | +| `--gateway-discovery-readiness-check-interval` | `duration` | Interval of readiness checks on gateway admin API clients for discovery. | `10s` | +| `--gateway-discovery-readiness-check-timeout` | `duration` | Timeout of readiness checks on gateway admin clients. | `5s` | +| `--gateway-to-reconcile` | `namespaced-name` | Gateway namespaced name in "namespace/name" format. Makes KIC reconcile only the specified Gateway. | | +| `--health-probe-bind-address` | `string` | The address the probe endpoint binds to. | `:10254` | +| `--ingress-class` | `string` | Name of the ingress class to route through this controller. | `kong` | +| `--init-cache-sync-duration` | `duration` | The initial delay to wait for Kubernetes object caches to be synced before the initial configuration. | `5s` | +| `--kong-admin-ca-cert` | `string` | PEM-encoded CA certificate to verify Kong's Admin TLS certificate. Mutually exclusive with --kong-admin-ca-cert-file. | | +| `--kong-admin-ca-cert-file` | `string` | Path to PEM-encoded CA certificate file to verify Kong's Admin TLS certificate. Mutually exclusive with --kong-admin-ca-cert. | | +| `--kong-admin-concurrency` | `int` | Max number of concurrent requests sent to Kong's Admin API. | `10` | +| `--kong-admin-filter-tag` | `strings` | Tag(s) in comma-separated format (or specify this flag multiple times). They are used to manage and filter entities in Kong. This setting will be silently ignored if the Kong instance has no tags support. | `[managed-by-ingress-controller]` | +| `--kong-admin-header` | `strings` | Header(s) (key:value) in comma-separated format (or specify this flag multiple times) to add to every Admin API call. | `[]` | +| `--kong-admin-init-retries` | `uint` | Number of attempts that will be made initially on controller startup to connect to the Kong Admin API. | `60` | +| `--kong-admin-init-retry-delay` | `duration` | The time delay between every attempt (on controller startup) to connect to the Kong Admin API. | `1s` | +| `--kong-admin-svc` | `namespaced-name` | Kong Admin API Service namespaced name in "namespace/name" format, to use for Kong Gateway service discovery. | | +| `--kong-admin-svc-port-names` | `strings` | Name(s) of ports on Kong Admin API service in comma-separated format (or specify this flag multiple times) to take into account when doing gateway discovery. | `[admin-tls,kong-admin-tls]` | +| `--kong-admin-tls-client-cert` | `string` | Mutual TLS (mTLS) client certificate for authentication. Mutually exclusive with --kong-admin-tls-client-cert-file. | | +| `--kong-admin-tls-client-cert-file` | `string` | Mutual TLS (mTLS) client certificate file for authentication. Mutually exclusive with --kong-admin-tls-client-cert. | | +| `--kong-admin-tls-client-key` | `string` | Mutual TLS (mTLS) client key for authentication. Mutually exclusive with --kong-admin-tls-client-key-file. | | +| `--kong-admin-tls-client-key-file` | `string` | Mutual TLS (mTLS) client key file for authentication. Mutually exclusive with --kong-admin-tls-client-key. | | +| `--kong-admin-tls-server-name` | `string` | SNI name to use to verify the certificate presented by Kong in TLS. | | +| `--kong-admin-tls-skip-verify` | `bool` | Disable verification of TLS certificate of Kong's Admin endpoint. | `false` | +| `--kong-admin-token` | `string` | The Kong Enterprise RBAC token used by the controller. Mutually exclusive with --kong-admin-token-file. | | +| `--kong-admin-token-file` | `string` | Path to the Kong Enterprise RBAC token file used by the controller. Mutually exclusive with --kong-admin-token. | | +| `--kong-admin-url` | `strings` | Kong Admin URL(s) in comma-separated format (or specify this flag multiple times) to connect to in the format "protocol://address:port". | `[http://localhost:8001]` | +| `--kong-workspace` | `string` | Kong Enterprise workspace to configure. Leave this empty if not using Kong workspaces. | | +| `--konnect-address` | `string` | Base address of Konnect API. | `https://us.kic.api.konghq.com` | +| `--konnect-control-plane-id` | `string` | An ID of a control plane that is to be synchronized with data plane configuration. | | +| `--konnect-disable-consumers-sync` | `bool` | Disable synchronization of consumers with Konnect. | `false` | +| `--konnect-initial-license-polling-period` | `duration` | Polling period to be used before the first license is retrieved. | `1m0s` | +| `--konnect-license-polling-period` | `duration` | Polling period to be used after the first license is retrieved. | `12h0m0s` | +| `--konnect-licensing-enabled` | `bool` | Retrieve licenses from Konnect if available. Overrides licenses provided via the environment. | `false` | +| `--konnect-refresh-node-period` | `duration` | Period of uploading status of KIC and controlled Kong instances. | `1m0s` | +| `--konnect-sync-enabled` | `bool` | Enable synchronization of data plane configuration with a Konnect control plane. | `false` | +| `--konnect-tls-client-cert` | `string` | Konnect TLS client certificate. | | +| `--konnect-tls-client-cert-file` | `string` | Konnect TLS client certificate file path. | | +| `--konnect-tls-client-key` | `string` | Konnect TLS client key. | | +| `--konnect-tls-client-key-file` | `string` | Konnect TLS client key file path. | | +| `--konnect-upload-config-period` | `duration` | Period of uploading Kong configuration. | `30s` | +| `--kubeconfig` | `string` | Path to the kubeconfig file. | | +| `--log-format` | `string` | Format of logs of the controller. Allowed values are text and json. | `text` | +| `--log-level` | `string` | Level of logging for the controller. Allowed values are trace, debug, info, and error. | `info` | +| `--metrics-bind-address` | `string` | The address the metric endpoint binds to. | `:10255` | +| `--profiling` | `bool` | Enable profiling via web interface host:10256/debug/pprof/. | `false` | +| `--proxy-sync-seconds` | `float` | Define the rate (in seconds) in which configuration updates will be applied to the Kong Admin API. | `3` | +| `--proxy-timeout-seconds` | `float` | Sets the timeout (in seconds) for all requests to Kong's Admin API. | `30` | +| `--publish-service` | `namespaced-name` | Service fronting Ingress resources in "namespace/name" format. The controller will update Ingress status information with this Service's endpoints. | | +| `--publish-service-udp` | `namespaced-name` | Service fronting UDP routing resources in "namespace/name" format. The controller will update UDP route status information with this Service's endpoints. If omitted, the same Service will be used for both TCP and UDP routes. | | +| `--publish-status-address` | `strings` | Addresses in comma-separated format (or specify this flag multiple times), for use in lieu of "publish-service" when that Service lacks useful address information (for example, in bare-metal environments). | `[]` | +| `--publish-status-address-udp` | `strings` | Addresses in comma-separated format (or specify this flag multiple times), for use in lieu of "publish-service-udp" when that Service lacks useful address information (for example, in bare-metal environments). | `[]` | +| `--secret-label-selector` | `string` | Limits the secrets ingested to those having this label set to "true". If not specified, all secrets are ingested. | | +| `--skip-ca-certificates` | `bool` | Disable syncing CA certificate syncing (for use with multi-workspace environments). | `false` | +| `--sync-period` | `duration` | Determine the minimum frequency at which watched resources are reconciled. Set to 0 to use default from controller-runtime. | `10h0m0s` | +| `--term-delay` | `duration` | The time delay to sleep before SIGTERM or SIGINT will shut down the ingress controller. | `0s` | +| `--update-status` | `bool` | Indicates if the ingress controller should update the status of resources (e.g. IP/Hostname for v1.Ingress, etc.). | `true` | +| `--update-status-queue-buffer-size` | `int` | Buffer size of the underlying channels used to update the status of resources. | `8192` | +| `--use-last-valid-config-for-fallback` | `bool` | When recovering from config push failures, use the last valid configuration cache to backfill broken objects. It can only be used with the FallbackConfiguration feature gate enabled. | `false` | +| `--watch-namespace` | `strings` | Namespace(s) in comma-separated format (or specify this flag multiple times) to watch for Kubernetes resources. Defaults to all namespaces. | `[]` | + + diff --git a/app/_src/kubernetes-ingress-controller/reference/custom-resources-3.4.x.md b/app/_src/kubernetes-ingress-controller/reference/custom-resources-3.4.x.md new file mode 100644 index 000000000000..514f670ba8cf --- /dev/null +++ b/app/_src/kubernetes-ingress-controller/reference/custom-resources-3.4.x.md @@ -0,0 +1,908 @@ +--- +title: Custom Resource Definitions API Reference +--- + + + + +## Packages +- [configuration.konghq.com/v1](#configurationkonghqcomv1) +- [configuration.konghq.com/v1alpha1](#configurationkonghqcomv1alpha1) +- [configuration.konghq.com/v1beta1](#configurationkonghqcomv1beta1) + + +## configuration.konghq.com/v1 + +Package v1 contains API Schema definitions for the konghq.com v1 API group. + +- [KongClusterPlugin](#kongclusterplugin) +- [KongConsumer](#kongconsumer) +- [KongIngress](#kongingress) +- [KongPlugin](#kongplugin) +### KongClusterPlugin + + +KongClusterPlugin is the Schema for the kongclusterplugins API. + +{% include md/kic/crd-ref/kong_cluster_plugin_description.md kong_version=page.kong_version %} + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `configuration.konghq.com/v1` +| `kind` _string_ | `KongClusterPlugin` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | 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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io)_ | 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](#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. | +| `configPatches` _[NamespacedConfigPatch](#namespacedconfigpatch) array_ | ConfigPatches represents JSON patches to the configuration of the plugin. Each item means a JSON patch to add something in the configuration, where path is specified in `path` and value is in `valueFrom` referencing a key in a secret. When Config is specified, patches will be applied to the configuration in Config. Otherwise, patches will be applied to an empty object. | +| `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](#kongprotocol) array_ | Protocols configures plugin to run on requests received on specific protocols. | +| `ordering` _[PluginOrdering](#pluginordering)_ | Ordering overrides the normal plugin execution order. It's only available on Kong Enterprise. `` is a request processing phase (for example, `access` or `body_filter`) and `` 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. + +{% include md/kic/crd-ref/kong_consumer_description.md kong_version=page.kong_version %} + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `configuration.konghq.com/v1` +| `kind` _string_ | `KongConsumer` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | 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. | +| `spec` _[KongConsumerSpec](#kongconsumerspec)_ | | + + + +### KongIngress + + +KongIngress is the Schema for the kongingresses API. + +{% include md/kic/crd-ref/kong_ingress_description.md kong_version=page.kong_version %} + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `configuration.konghq.com/v1` +| `kind` _string_ | `KongIngress` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `upstream` _[KongIngressUpstream](#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](#kongingressservice)_ | Proxy defines additional connection options for the routes to be configured in the Kong Gateway, e.g. `connection_timeout`, `retries`, etc. | +| `route` _[KongIngressRoute](#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. + +{% include md/kic/crd-ref/kong_plugin_description.md kong_version=page.kong_version %} + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `configuration.konghq.com/v1` +| `kind` _string_ | `KongPlugin` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | 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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io)_ | 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](#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. | +| `configPatches` _[ConfigPatch](#configpatch) array_ | ConfigPatches represents JSON patches to the configuration of the plugin. Each item means a JSON patch to add something in the configuration, where path is specified in `path` and value is in `valueFrom` referencing a key in a secret. When Config is specified, patches will be applied to the configuration in Config. Otherwise, patches will be applied to an empty object. | +| `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](#kongprotocol) array_ | Protocols configures plugin to run on requests received on specific protocols. | +| `ordering` _[PluginOrdering](#pluginordering)_ | Ordering overrides the normal plugin execution order. It's only available on Kong Enterprise. `` is a request processing phase (for example, `access` or `body_filter`) and `` 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. | + + + +### Types + +In this section you will find types that the CRDs rely on. + + + + +#### ConfigPatch + + +ConfigPatch is a JSON patch (RFC6902) to add values from Secret to the generated configuration. +It is an equivalent of the following patch: +`{"op": "add", "path": {.Path}, "value": {.ComputedValueFrom}}`. + + + +| Field | Description | +| --- | --- | +| `path` _string_ | Path is the JSON-Pointer value (RFC6901) that references a location within the target configuration. | +| `valueFrom` _[ConfigSource](#configsource)_ | ValueFrom is the reference to a key of a secret where the patched value comes from. | + + +_Appears in:_ +- [KongPlugin](#kongplugin) + +#### ConfigSource + + +ConfigSource is a wrapper around SecretValueFromSource. + + + +| Field | Description | +| --- | --- | +| `secretKeyRef` _[SecretValueFromSource](#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:_ +- [ConfigPatch](#configpatch) +- [KongPlugin](#kongplugin) + + + +#### KongConsumerSpec + + +KongConsumerSpec defines the specification of the KongConsumer. + + + +| Field | Description | +| --- | --- | +| `controlPlaneRef` _[ControlPlaneRef](#controlplaneref)_ | ControlPlaneRef is a reference to a ControlPlane this Consumer is associated with. | +| `tags` _[Tags](#tags)_ | Tags is an optional set of tags applied to the consumer. | + + +_Appears in:_ +- [KongConsumer](#kongconsumer) + + + +#### 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](#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](#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](#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](#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](#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](#kongclusterplugin) +- [KongIngressRoute](#kongingressroute) +- [KongPlugin](#kongplugin) + +#### NamespacedConfigPatch + + +NamespacedConfigPatch is a JSON patch to add values from secrets to KongClusterPlugin +to the generated configuration of plugin in Kong. + + + +| Field | Description | +| --- | --- | +| `path` _string_ | Path is the JSON path to add the patch. | +| `valueFrom` _[NamespacedConfigSource](#namespacedconfigsource)_ | ValueFrom is the reference to a key of a secret where the patched value comes from. | + + +_Appears in:_ +- [KongClusterPlugin](#kongclusterplugin) + +#### NamespacedConfigSource + + +NamespacedConfigSource is a wrapper around NamespacedSecretValueFromSource. + + + +| Field | Description | +| --- | --- | +| `secretKeyRef` _[NamespacedSecretValueFromSource](#namespacedsecretvaluefromsource)_ | Specifies a name, a namespace, and a key of a secret to refer to. | + + +_Appears in:_ +- [KongClusterPlugin](#kongclusterplugin) +- [NamespacedConfigPatch](#namespacedconfigpatch) + +#### 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](#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](#configsource) + + +## configuration.konghq.com/v1alpha1 + +Package v1alpha1 contains API Schema definitions for the configuration.konghq.com v1alpha1 API group. + +- [IngressClassParameters](#ingressclassparameters) +- [KongCustomEntity](#kongcustomentity) +- [KongLicense](#konglicense) +- [KongVault](#kongvault) +### IngressClassParameters + + +IngressClassParameters is the Schema for the IngressClassParameters API. + +{% include md/kic/crd-ref/ingress_class_parameters_description.md kong_version=page.kong_version %} + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `configuration.konghq.com/v1alpha1` +| `kind` _string_ | `IngressClassParameters` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[IngressClassParametersSpec](#ingressclassparametersspec)_ | Spec is the IngressClassParameters specification. | + + + + + + + + + + +### KongCustomEntity + + +KongCustomEntity defines a "custom" Kong entity that KIC cannot support the entity type directly. + +{% include md/kic/crd-ref/kong_custom_entity_description.md kong_version=page.kong_version %} + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `configuration.konghq.com/v1alpha1` +| `kind` _string_ | `KongCustomEntity` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[KongCustomEntitySpec](#kongcustomentityspec)_ | | + + + + + + +### KongLicense + + +KongLicense stores a Kong enterprise license to apply to managed Kong gateway instances. + +{% include md/kic/crd-ref/kong_license_description.md kong_version=page.kong_version %} + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `configuration.konghq.com/v1alpha1` +| `kind` _string_ | `KongLicense` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `rawLicenseString` _string_ | RawLicenseString is a string with the raw content of the license. | +| `enabled` _boolean_ | Enabled is set to true to let controllers (like KIC or KGO) to reconcile it. Default value is true to apply the license by default. | + + + + + + + + + +### KongVault + + +KongVault is the schema for kongvaults API which defines a custom Kong vault. +A Kong vault is a storage to store sensitive data, where the values can be referenced in configuration of plugins. +See: https://docs.konghq.com/gateway/latest/kong-enterprise/secrets-management/ + +{% include md/kic/crd-ref/kong_vault_description.md kong_version=page.kong_version %} + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `configuration.konghq.com/v1alpha1` +| `kind` _string_ | `KongVault` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[KongVaultSpec](#kongvaultspec)_ | | + + + +### Types + +In this section you will find types that the CRDs rely on. +#### ControllerReference + + +ControllerReference is a reference to a controller that reconciles the KongLicense. + + + +| Field | Description | +| --- | --- | +| `group` _[Group](#group)_ | Group is the group of referent. It should be empty if the referent is in "core" group (like pod). | +| `kind` _[Kind](#kind)_ | Kind is the kind of the referent. By default the nil kind means kind Pod. | +| `namespace` _[Namespace](#namespace)_ | Namespace is the namespace of the referent. It should be empty if the referent is cluster scoped. | +| `name` _[ObjectName](#objectname)_ | Name is the name of the referent. | + + +_Appears in:_ +- [KongLicenseControllerStatus](#konglicensecontrollerstatus) + +#### IngressClassParametersSpec + + +IngressClassParametersSpec defines the desired state of IngressClassParameters. + + + +| 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](#ingressclassparameters) + +#### KongCustomEntitySpec + + +KongCustomEntitySpec defines the specification of the KongCustomEntity. + + + +| Field | Description | +| --- | --- | +| `type` _string_ | EntityType is the type of the Kong entity. The type is used in generating declarative configuration. | +| `fields` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io)_ | Fields defines the fields of the Kong entity itself. | +| `controllerName` _string_ | ControllerName specifies the controller that should reconcile it, like ingress class. | +| `parentRef` _[ObjectReference](#objectreference)_ | ParentRef references the kubernetes resource it attached to when its scope is "attached". Currently only KongPlugin/KongClusterPlugin allowed. This will make the custom entity to be attached to the entity(service/route/consumer) where the plugin is attached. | + + +_Appears in:_ +- [KongCustomEntity](#kongcustomentity) + + + +#### KongVaultSpec + + +KongVaultSpec defines specification of a custom Kong vault. + + + +| Field | Description | +| --- | --- | +| `backend` _string_ | Backend is the type of the backend storing the secrets in the vault. The supported backends of Kong is listed here: https://docs.konghq.com/gateway/latest/kong-enterprise/secrets-management/backends/ | +| `prefix` _string_ | Prefix is the prefix of vault URI for referencing values in the vault. It is immutable after created. | +| `description` _string_ | Description is the additional information about the vault. | +| `config` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io)_ | Config is the configuration of the vault. Varies for different backends. | +| `tags` _[Tags](#tags)_ | Tags are the tags associated to the vault for grouping and filtering. | +| `controlPlaneRef` _[ControlPlaneRef](#controlplaneref)_ | ControlPlaneRef is a reference to a Konnect ControlPlane this KongVault is associated with. | + + +_Appears in:_ +- [KongVault](#kongvault) + + + +#### ObjectName +_Underlying type:_ `string` + +ObjectName refers to the name of a Kubernetes object. +Object names can have a variety of forms, including RFC1123 subdomains, +RFC 1123 labels, or RFC 1035 labels. + + + + + +_Appears in:_ +- [ControllerReference](#controllerreference) + +#### ObjectReference + + +ObjectReference defines reference of a kubernetes object. + + + +| Field | Description | +| --- | --- | +| `group` _string_ | Group defines the API group of the referred object. | +| `kind` _string_ | Kind defines the kind of the referred object. | +| `namespace` _string_ | Empty namespace means the same namespace of the owning object. | +| `name` _string_ | Name defines the name of the referred object. | + + +_Appears in:_ +- [KongCustomEntitySpec](#kongcustomentityspec) + + +## configuration.konghq.com/v1beta1 + +Package v1beta1 contains API Schema definitions for the configuration.konghq.com v1beta1 API group. + +- [KongConsumerGroup](#kongconsumergroup) +- [KongUpstreamPolicy](#kongupstreampolicy) +- [TCPIngress](#tcpingress) +- [UDPIngress](#udpingress) +### KongConsumerGroup + + +KongConsumerGroup is the Schema for the kongconsumergroups API. + +{% include md/kic/crd-ref/kong_consumer_group_description.md kong_version=page.kong_version %} + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `configuration.konghq.com/v1beta1` +| `kind` _string_ | `KongConsumerGroup` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[KongConsumerGroupSpec](#kongconsumergroupspec)_ | | + + + +### 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 (https://docs.konghq.com/gateway/latest/admin-api/#upstream-object), +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: `, where `` 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. + +{% include md/kic/crd-ref/kong_upstream_policy_description.md kong_version=page.kong_version %} + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `configuration.konghq.com/v1beta1` +| `kind` _string_ | `KongUpstreamPolicy` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[KongUpstreamPolicySpec](#kongupstreampolicyspec)_ | Spec contains the configuration of the Kong upstream. | + + + +### TCPIngress + + +TCPIngress is the Schema for the tcpingresses API. + +{% include md/kic/crd-ref/tcp_ingress_description.md kong_version=page.kong_version %} + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `configuration.konghq.com/v1beta1` +| `kind` _string_ | `TCPIngress` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[TCPIngressSpec](#tcpingressspec)_ | Spec is the TCPIngress specification. | + + + +### UDPIngress + + +UDPIngress is the Schema for the udpingresses API. + +{% include md/kic/crd-ref/udp_ingress_description.md kong_version=page.kong_version %} + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `configuration.konghq.com/v1beta1` +| `kind` _string_ | `UDPIngress` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[UDPIngressSpec](#udpingressspec)_ | Spec is the UDPIngress specification. | + + + +### Types + +In this section you will find types that the CRDs rely on. +#### HTTPStatus +_Underlying type:_ `integer` + +HTTPStatus is an HTTP status code. + + + + + +_Appears in:_ +- [KongUpstreamHealthcheckHealthy](#kongupstreamhealthcheckhealthy) +- [KongUpstreamHealthcheckUnhealthy](#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](#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](#ingressrule) +- [UDPIngressRule](#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](#ingressbackend)_ | Backend defines the referenced service endpoint to which the traffic will be forwarded to. | + + +_Appears in:_ +- [TCPIngressSpec](#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](#tcpingressspec) + +#### KongConsumerGroupSpec + + +KongConsumerGroupSpec defines the desired state of KongConsumerGroup. + + + +| Field | Description | +| --- | --- | +| `name` _string_ | Name is the name of the ConsumerGroup in Kong. | +| `controlPlaneRef` _[ControlPlaneRef](#controlplaneref)_ | ControlPlaneRef is a reference to a ControlPlane this ConsumerGroup is associated with. | +| `tags` _[Tags](#tags)_ | Tags is an optional set of tags applied to the ConsumerGroup. | + + +_Appears in:_ +- [KongConsumerGroup](#kongconsumergroup) + + + +#### 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](#kongupstreamhealthcheckhealthy)_ | Healthy configures thresholds and HTTP status codes to mark targets healthy for an upstream. | +| `unhealthy` _[KongUpstreamHealthcheckUnhealthy](#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](#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](#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](#kongupstreampolicyspec) + +#### KongUpstreamHealthcheck + + +KongUpstreamHealthcheck represents a health-check config of an Upstream in Kong. + + + +| Field | Description | +| --- | --- | +| `active` _[KongUpstreamActiveHealthcheck](#kongupstreamactivehealthcheck)_ | Active configures active health check probing. | +| `passive` _[KongUpstreamPassiveHealthcheck](#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](#kongupstreampolicyspec) + +#### KongUpstreamHealthcheckHealthy + + +KongUpstreamHealthcheckHealthy configures thresholds and HTTP status codes to mark targets healthy for an upstream. + + + +| Field | Description | +| --- | --- | +| `httpStatuses` _[HTTPStatus](#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](#kongupstreamactivehealthcheck) +- [KongUpstreamPassiveHealthcheck](#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](#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](#kongupstreamactivehealthcheck) +- [KongUpstreamPassiveHealthcheck](#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](#kongupstreamhealthcheckhealthy)_ | Healthy configures thresholds and HTTP status codes to mark targets healthy for an upstream. | +| `unhealthy` _[KongUpstreamHealthcheckUnhealthy](#kongupstreamhealthcheckunhealthy)_ | Unhealthy configures thresholds and HTTP status codes to mark targets unhealthy. | + + +_Appears in:_ +- [KongUpstreamHealthcheck](#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](#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](#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](#kongupstreamhealthcheck)_ | Healthchecks defines the health check configurations in Kong. | + + +_Appears in:_ +- [KongUpstreamPolicy](#kongupstreampolicy) + +#### TCPIngressSpec + + +TCPIngressSpec defines the desired state of TCPIngress. + + + +| Field | Description | +| --- | --- | +| `rules` _[IngressRule](#ingressrule) array_ | A list of rules used to configure the Ingress. | +| `tls` _[IngressTLS](#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](#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](#ingressbackend)_ | Backend defines the Kubernetes service which accepts traffic from the listening Port defined above. | + + +_Appears in:_ +- [UDPIngressSpec](#udpingressspec) + +#### UDPIngressSpec + + +UDPIngressSpec defines the desired state of UDPIngress. + + + +| Field | Description | +| --- | --- | +| `rules` _[UDPIngressRule](#udpingressrule) array_ | A list of rules used to configure the Ingress. | + + +_Appears in:_ +- [UDPIngress](#udpingress) + + + + diff --git a/app/_src/kubernetes-ingress-controller/reference/version-compatibility.md b/app/_src/kubernetes-ingress-controller/reference/version-compatibility.md index 73b2704d6155..1a3a27d8013a 100644 --- a/app/_src/kubernetes-ingress-controller/reference/version-compatibility.md +++ b/app/_src/kubernetes-ingress-controller/reference/version-compatibility.md @@ -9,23 +9,25 @@ those versions' documentation. ## Kong -| {{site.kic_product_name}} | 2.12.x | 3.0.x | 3.1.x | 3.2.x | 3.3.x | -|:--------------------------|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:| -| Kong 2.8.x | | | | | | -| Kong 3.4.x | | | | | | -| Kong 3.6.x | | | | | | -| Kong 3.7.x | | | | | | -| Kong 3.8.x | | | | | | +| {{site.kic_product_name}} | 2.12.x | 3.0.x | 3.1.x | 3.2.x | 3.3.x | 3.4.x +|:--------------------------|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:| +| Kong 2.8.x | | | | | | | +| Kong 3.4.x | | | | | | | +| Kong 3.6.x | | | | | | | +| Kong 3.7.x | | | | | | | +| Kong 3.8.x | | | | | | | +| Kong 3.9.x | | | | | | | ## {{site.ee_product_name}} -| {{site.kic_product_name}} | 2.12.x | 3.0.x | 3.1.x | 3.2.x | 3.3.x | -|:-------------------------------|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:| -| {{site.ee_product_name}} 2.8.x | | | | | | -| {{site.ee_product_name}} 3.4.x | | | | | | -| {{site.ee_product_name}} 3.6.x | | | | | | -| {{site.ee_product_name}} 3.7.x | | | | | | -| {{site.ee_product_name}} 3.8.x | | | | | | +| {{site.kic_product_name}} | 2.12.x | 3.0.x | 3.1.x | 3.2.x | 3.3.x | 3.4.x | +|:-------------------------------|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:| +| {{site.ee_product_name}} 2.8.x | | | | | | | +| {{site.ee_product_name}} 3.4.x | | | | | | | +| {{site.ee_product_name}} 3.6.x | | | | | | | +| {{site.ee_product_name}} 3.7.x | | | | | | | +| {{site.ee_product_name}} 3.8.x | | | | | | | +| {{site.ee_product_name}} 3.9.x | | | | | | | ## Kubernetes @@ -34,13 +36,14 @@ those versions' documentation. The following table presents the general compatibility of {{site.kic_product_name}} with specific Kubernetes versions. Users should expect all the combinations marked with to work and to be supported. -| {{site.kic_product_name}} | 2.12.x | 3.0.x | 3.1.x | 3.2.x | 3.3.x | -|:--------------------------|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:| -| Kubernetes 1.27 | | | | | | -| Kubernetes 1.28 | | | | | | -| Kubernetes 1.29 | | | | | | -| Kubernetes 1.30 | | | | | | -| Kubernetes 1.31 | | | | | | +| {{site.kic_product_name}} | 2.12.x | 3.0.x | 3.1.x | 3.2.x | 3.3.x | 3.4.x | +|:--------------------------|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:| +| Kubernetes 1.27 | | | | | | | +| Kubernetes 1.28 | | | | | | | +| Kubernetes 1.29 | | | | | | | +| Kubernetes 1.30 | | | | | | | +| Kubernetes 1.31 | | | | | | | +| Kubernetes 1.32 | | | | | | | ### Gateway API @@ -49,13 +52,14 @@ with specific Kubernetes minor versions. As {{site.kic_product_name}} implements project, which defines [its own compatibility declarations][gateway-api-supported-versions], the expected compatibility of Gateway API features might be limited to those. -| {{site.kic_product_name}} | 2.12.x | 3.0.x | 3.1.x | 3.2.x | 3.3.x | -|:--------------------------|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:| -| Kubernetes 1.27 | | | | | | -| Kubernetes 1.28 | | | | | | -| Kubernetes 1.29 | | | | | | -| Kubernetes 1.30 | | | | | | -| Kubernetes 1.31 | | | | | | +| {{site.kic_product_name}} | 2.12.x | 3.0.x | 3.1.x | 3.2.x | 3.3.x | 3.4.x | +|:--------------------------|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:|:---------------------------:| +| Kubernetes 1.27 | | | | | | | +| Kubernetes 1.28 | | | | | | | +| Kubernetes 1.29 | | | | | | | +| Kubernetes 1.30 | | | | | | | +| Kubernetes 1.31 | | | | | | | +| Kubernetes 1.32 | | | | | | | For specific Gateway API resources support, please refer to the [Gateway API Support][gateway-api-support] page. @@ -74,6 +78,7 @@ For each {{site.kic_product_name}} release, tests are run to verify this documen | Istio 1.21 | | | | | | | Istio 1.22 | | | | | | | Istio 1.23 | | | | | | +| Istio 1.24 | | | | | | [istio]:https://istio.io [istio-guide]:/kubernetes-ingress-controller/{{page.release}}/guides/getting-started-istio/ diff --git a/app/_src/kubernetes-ingress-controller/support-policy.md b/app/_src/kubernetes-ingress-controller/support-policy.md index 47a989a1510c..ce9520a17d97 100644 --- a/app/_src/kubernetes-ingress-controller/support-policy.md +++ b/app/_src/kubernetes-ingress-controller/support-policy.md @@ -27,6 +27,7 @@ LTS versions of {{site.kic_product_name}} are supported for 3 years after releas | Version | Release Date | End of Support | |------------|----------------|----------------| +| **3.4.x** | **2024-12-18** | **2027-12-18** | | 3.3.x | 2024-08-26 | 2025-08-26 | | 3.2.x | 2024-06-12 | 2025-06-12 | | 3.1.x | 2024-02-07 | 2025-02-07 |