Skip to content
Kong Docs are moving soon! Our docs are migrating to a new home. You'll be automatically redirected to the new site in the future. In the meantime, view this page on the new site!
|
1.3.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

gateway-operator.konghq.com/v1alpha1

Package v1alpha1 contains API Schema definitions for the operator v1alpha1 API group

AIGateway is a network Gateway enabling access and management for AI & Machine Learning models such as Large Language Models (LLM).

The underlying technology for the AIGateway is the Kong Gateway configured with a variety of plugins which provide the the AI featureset.

This is a list of the plugins, which are available in Kong Gateway v3.6.x+:

  • ai-proxy (https://github.com/kong/kong/tree/master/kong/plugins/ai-proxy)
  • ai-request-transformer (https://github.com/kong/kong/tree/master/kong/plugins/ai-request-transformer)
  • ai-response-transformers (https://github.com/kong/kong/tree/master/kong/plugins/ai-response-transformer)
  • ai-prompt-template (https://github.com/kong/kong/tree/master/kong/plugins/ai-prompt-template)
  • ai-prompt-guard-plugin (https://github.com/kong/kong/tree/master/kong/plugins/ai-prompt-guard)
  • ai-prompt-decorator-plugin (https://github.com/kong/kong/tree/master/kong/plugins/ai-prompt-decorator)

    So effectively the AIGateway resource provides a bespoke Gateway resource (which it owns and manages) with the gateway, consumers and plugin configurations automated and configurable via Kubernetes APIs.

    The current iteration only supports the proxy itself, but the API is being built with room for future growth in several dimensions. For instance:

  • Supporting auxiliary functions (e.g. decorator, guard, templater, token-rate-limit)
  • Supporting request/response transformers
  • Supporting more than just LLMs (e.g. CCNs, GANs, e.t.c.)
  • Supporting more hosting options for LLMs (e.g. self hosted)
  • Supporting more AI cloud providers
  • Supporting more AI cloud provider features

    The validation rules throughout are set up to ensure at least one cloud-provider-based LLM is specified, but in the future when we have more model types and more hosting options for those types so we may want to look into using CEL validation to ensure that at least one model configuration is provided. We may also want to use CEL to validate things like identifier unique-ness, e.t.c.

    See: https://kubernetes.io/docs/reference/using-api/cel/
Field Description
apiVersion string gateway-operator.konghq.com/v1alpha1
kind string AIGateway
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec AIGatewaySpec Spec is the desired state of the AIGateway.
status AIGatewayStatus Status is the observed state of the AIGateway.

DataPlaneMetricsExtension

DataPlaneMetricsExtension holds the configuration for the DataPlane metrics extension. It can be attached to a ControlPlane using its spec.extensions. When attached it will make the ControlPlane configure its DataPlane with the specified metrics configuration. Additionally, it will also make the operator expose DataPlane’s metrics enriched with metadata required for in-cluster Kubernetes autoscaling.

NOTE: This is an enterprise feature. In order to use it you need to use the EE version of Kong Gateway Operator with a valid license.

Field Description
apiVersion string gateway-operator.konghq.com/v1alpha1
kind string DataPlaneMetricsExtension
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec DataPlaneMetricsExtensionSpec  
status DataPlaneMetricsExtensionStatus  

Types

In this section you will find types that the CRDs rely on.

AICloudProvider

AICloudProvider is the organization that provides API access to Large Language Models (LLMs).

Field Description
name AICloudProviderName Name is the unique name of an LLM provider.

Appears in:

AICloudProviderAPITokenRef

AICloudProviderAPITokenRef is an reference to another object which contains the API token for an AI cloud provider.

Field Description
name string Name is the name of the reference object.
namespace string Namespace is the namespace of the reference object.

If not specified, it will be assumed to be the same namespace as the object which references it.
kind string Kind is the API object kind

If not specified, it will be assumed to be “Secret”. If a Secret is used as the Kind, the secret must contain a single key-value pair where the value is the secret API token. The key can be named anything, as long as there’s only one entry, but by convention it should be “apiToken”.

Appears in:

AICloudProviderName

Underlying type: string

AICloudProviderName indicates the unique name of a supported AI cloud provider.

Appears in:

AIGatewayConsumerRef

AIGatewayConsumerRef indicates the Secret resource containing the credentials for the Kong consumer.

Field Description
name string Name is the name of the reference object.
namespace string Namespace is the namespace of the reference object.

Appears in:

AIGatewayEndpoint

AIGatewayEndpoint is a network endpoint for accessing an AIGateway.

Field Description
network EndpointNetworkAccessHint NetworkAccessHint is a hint to the user about what kind of network access is expected for the reachability of this endpoint.
url string URL is the URL to access the endpoint from the network indicated by the NetworkAccessHint.
models string array AvailableModels is a list of the identifiers of all the AI models that are accessible from this endpoint.
consumer AIGatewayConsumerRef Consumer is a reference to the Secret that contains the credentials for the Kong consumer that is allowed to access this endpoint.
conditions Condition array Conditions describe the current conditions of the AIGatewayEndpoint.

Known condition types are:

- “Provisioning” - “EndpointReady”

Appears in:

AIGatewaySpec

AIGatewaySpec defines the desired state of an AIGateway.

Field Description
gatewayClassName string GatewayClassName is the name of the GatewayClass which is responsible for the AIGateway.
largeLanguageModels LargeLanguageModels LargeLanguageModels is a list of Large Language Models (LLMs) to be managed by the AI Gateway.

This is a required field because we only support LLMs at the moment. In future iterations we may support other model types.
cloudProviderCredentials AICloudProviderAPITokenRef CloudProviderCredentials is a reference to an object (e.g. a Kubernetes Secret) which contains the credentials needed to access the APIs of cloud providers.

This is the global configuration that will be used by DEFAULT for all model configurations. A secret configured this way MAY include any number of key-value pairs equal to the number of providers you have, but used this way the keys MUST be named according to their providers (e.g. “openai”, “azure”, “cohere”, e.t.c.). For example:

apiVersion: v1 kind: Secret metadata: name: devteam-ai-cloud-providers type: Opaque data: openai: ******* azure: ******* cohere: *********

See AICloudProviderName for a list of known and valid cloud providers.

Note that the keys are NOT case-sensitive (e.g. “OpenAI”, “openai”, and “openAI” are all valid and considered the same keys) but if there are duplicates endpoints failures conditions will be emitted and endpoints will not be configured until the duplicates are resolved.

This is currently considered required, but in future iterations will be optional as we do things like enable configuring credentials at the model level.

Appears in:

AIGatewayStatus

AIGatewayStatus defines the observed state of AIGateway.

Field Description
endpoints AIGatewayEndpoint array Endpoints are collections of the URL, credentials and metadata needed in order to access models served by the AIGateway for inference.
conditions Condition array Conditions describe the current conditions of the AIGateway.

Known condition types are:

- “Accepted” - “Provisioning” - “EndpointsReady”

Appears in:

CloudHostedLargeLanguageModel

CloudHostedLargeLanguageModel is the configuration for Large Language Models (LLM) hosted by a known and supported AI cloud provider (e.g. OpenAI, Cohere, Azure, e.t.c.).

Field Description
identifier string Identifier is the unique name which identifies the LLM. This will be used as part of the requests made to an AIGateway endpoint. For instance: if you provided the identifier “devteam-gpt-access”, then you would access this model via “https://${endpoint}/devteam-gpt-access” and supply it with your consumer credentials to authenticate requests.
model string Model is the model name of the LLM (e.g. gpt-3.5-turbo, phi-2, e.t.c.).

If not specified, whatever the cloud provider specifies as the default model will be used.
promptType LLMPromptType PromptType is the type of prompt to be used for inference requests to the LLM (e.g. “chat”, “completions”).

If “chat” is specified, prompts sent by the user will be interactive, contextual and stateful. The LLM will dynamically answer questions and simulate a dialogue, while also keeping track of the conversation to provide contextually relevant responses.

If “completions” is specified, prompts sent by the user will be stateless and “one-shot”. The LLM will provide a single response to the prompt, without any context from previous prompts.

If not specified, “completions” will be used as the default.
defaultPrompts LLMPrompt array DefaultPrompts is a list of prompts that should be provided to the LLM by default. This is generally used to influence inference behavior, for instance by providing a “system” role prompt that instructs the LLM to take on a certain persona.
defaultPromptParams LLMPromptParams DefaultPromptParams configures the parameters which will be sent with any and every inference request.

If this is set, there is currently no way to override these parameters at the individual prompt level. This is an expected feature from later releases of our AI plugins.
aiCloudProvider AICloudProvider AICloudProvider defines the cloud provider that will fulfill the LLM requests for this CloudHostedLargeLanguageModel

Appears in:

DataPlaneMetricsExtensionSpec

DataPlaneMetricsExtensionSpec defines the spec for the DataPlaneMetricsExtension.

Field Description
serviceSelector ServiceSelector ServiceSelector holds the service selector specifying the services for which metrics should be collected.
config MetricsConfig Config holds the configuration for the DataPlane metrics.

Appears in:

DataPlaneMetricsExtensionStatus

DataPlaneMetricsExtensionStatus defines the status of the DataPlaneMetricsExtension.

Field Description
controlPlaneRef NamespacedRef ControlPlaneRef is a reference to the ControlPlane that this is associated with. This field is set by the operator when this extension is associated with a ControlPlane through its extensions spec. There can only be one ControlPlane associated with a given DataPlaneMetricsExtension. When this is unset it means that the association has been removed.

Appears in:

EndpointNetworkAccessHint

Underlying type: string

EndpointNetworkAccessHint provides a human readable indication of what kind of network access is expected for a Gateway.

This isn’t meant to reflect knowledge of any specific network by name, which is why it includes “hint” in the name. It’s meant to be a hint to the user such as “internet-accessible”, “internal-only”.

Appears in:

ExtensionRef

ExtensionRef corresponds to another resource in the Kubernetes cluster which defines extended behavior for a resource (e.g. ControlPlane).

Field Description
group string Group is the group of the extension resource.
kind string Kind is kind of the extension resource.
name string Name is the name of the referred resource.
namespace string Namespace is the namespace of the referred resource.

For namespace-scoped resources if no Namespace is provided then the namespace of the parent object MUST be used.

This field MUST not be set when referring to cluster-scoped resources.

Appears in:

LLMPrompt

LLMPrompt is a text prompt that includes parameters, a role and content.

This is intended for situations like when you need to provide roles in a prompt to an LLM in order to influence its behavior and responses.

For example, you might want to provide a “system” role and tell the LLM something like “you are a helpful assistant who responds in the style of Sherlock Holmes”.

Field Description
content string Content is the prompt text sent for inference.
role LLMPromptRole Role indicates the role of the prompt. This is used to identify the prompt’s purpose, such as “system” or “user” and can influence the behavior of the LLM.

If not specified, “user” will be used as the default.

Appears in:

LLMPromptParams

LLMPromptParams contains parameters that can be used to control the behavior of a large language model (LLM) when generating text based on a prompt.

Field Description
temperature string Temperature controls the randomness of predictions by scaling the logits before applying softmax. A lower temperature (e.g., 0.0 to 0.7) makes the model more confident in its predictions, leading to more repetitive and deterministic outputs. A higher temperature (e.g., 0.8 to 1.0) increases randomness, generating more diverse and creative outputs. At very high temperatures, the outputs may become nonsensical or highly unpredictable.
maxTokens integer Max Tokens specifies the maximum length of the model’s output in terms of the number of tokens (words or pieces of words). This parameter limits the output’s size, ensuring the model generates content within a manageable scope. A token can be a word or part of a word, depending on the model’s tokenizer.
topK integer TopK sampling is a technique where the model’s prediction is limited to the K most likely next tokens at each step of the generation process. The probability distribution is truncated to these top K tokens, and the next token is randomly sampled from this subset. This method helps in reducing the chance of selecting highly improbable tokens, making the text more coherent. A smaller K leads to more predictable text, while a larger K allows for more diversity but with an increased risk of incoherence.
topP string TopP (also known as nucleus sampling) is an alternative to top K sampling. Instead of selecting the top K tokens, top P sampling chooses from the smallest set of tokens whose cumulative probability exceeds the threshold P. This method dynamically adjusts the number of tokens considered at each step, depending on their probability distribution. It helps in maintaining diversity while also avoiding very unlikely tokens. A higher P value increases diversity but can lead to less coherence, whereas a lower P value makes the model’s outputs more focused and coherent.

Appears in:

LLMPromptRole

Underlying type: string

LLMPromptRole indicates the role of a prompt for a large language model (LLM).

Appears in:

LLMPromptType

Underlying type: string

LLMPromptType indicates the type of prompt to be used for a large language model (LLM).

Appears in:

LargeLanguageModels

LargeLanguageModels is a list of Large Language Models (LLM) hosted in various ways (cloud hosted, self hosted, e.t.c.) which the AIGateway should serve and manage traffic for.

Field Description
cloudHosted CloudHostedLargeLanguageModel array CloudHosted configures LLMs hosted and served by cloud providers.

This is currently a required field, requiring at least one cloud-hosted LLM be specified, however in future iterations we may add other hosting options such as self-hosted LLMs as separate fields.

Appears in:

MetricsConfig

MetricsConfig holds the configuration for the DataPlane metrics.

Field Description
latency boolean Latency indicates whether latency metrics are enabled for the DataPlane. This translates into deployed instances having latency_metrics option set on the Prometheus plugin.
bandwidth boolean Bandwidth indicates whether bandwidth metrics are enabled for the DataPlane. This translates into deployed instances having bandwidth_metrics option set on the Prometheus plugin.
upstreamHealth boolean UpstreamHealth indicates whether upstream health metrics are enabled for the DataPlane. This translates into deployed instances having upstream_health_metrics option set on the Prometheus plugin.
statusCode boolean StatusCode indicates whether status code metrics are enabled for the DataPlane. This translates into deployed instances having status_code_metrics option set on the Prometheus plugin.

Appears in:

NamespacedRef

NamespacedRef is a reference to a namespaced resource.

Field Description
name string Name is the name of the referred resource.
namespace string Namespace is the namespace of the referred resource.

For namespace-scoped resources if no Namespace is provided then the namespace of the parent object MUST be used.

This field MUST not be set when referring to cluster-scoped resources.

Appears in:

ServiceSelector

ServiceSelector holds the service selector specification.

Field Description
matchNames ServiceSelectorEntry array MatchNames holds the list of Services names to match.

Appears in:

ServiceSelectorEntry

ServiceSelectorEntry holds the name of a service to match.

Field Description
name string Name is the name of the service to match.

Appears in:

gateway-operator.konghq.com/v1beta1

Package v1beta1 contains API Schema definitions for the gateway-operator.konghq.com v1beta1 API group

ControlPlane is the Schema for the controlplanes API

Field Description
apiVersion string gateway-operator.konghq.com/v1beta1
kind string ControlPlane
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec ControlPlaneSpec  
status ControlPlaneStatus  

DataPlane

DataPlane is the Schema for the dataplanes API

Field Description
apiVersion string gateway-operator.konghq.com/v1beta1
kind string DataPlane
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec DataPlaneSpec  
status DataPlaneStatus  

GatewayConfiguration

GatewayConfiguration is the Schema for the gatewayconfigurations API

Field Description
apiVersion string gateway-operator.konghq.com/v1beta1
kind string GatewayConfiguration
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec GatewayConfigurationSpec  
status GatewayConfigurationStatus  

Types

In this section you will find types that the CRDs rely on.

Address

Address describes an address which can be either an IP address or a hostname.

Field Description
type AddressType Type of the address.
value string Value of the address. The validity of the values will depend on the type and support by the controller.

Examples: 1.2.3.4, 128::1, my-ip-address.
sourceType AddressSourceType Source type of the address.

Appears in:

AddressSourceType

Underlying type: string

AddressSourceType defines the type of source this address represents.

Can be one of:

  • PublicLoadBalancer
  • PrivateLoadBalancer
  • PublicIP
  • PrivateIP

Appears in:

AddressType

Underlying type: string

AddressType defines how a network address is represented as a text string.

Can be one of:

  • IPAddress
  • Hostname

Appears in:

BlueGreenStrategy

BlueGreenStrategy defines the Blue Green deployment strategy.

Field Description
promotion Promotion Promotion defines how the operator handles promotion of resources.
resources RolloutResources Resources controls what happens to operator managed resources during or after a rollout.

Appears in:

ControlPlaneDeploymentOptions

ControlPlaneDeploymentOptions is a shared type used on objects to indicate that their configuration results in a Deployment which is managed by the Operator and includes options for managing Deployments such as the the number of replicas or pod options like container image and resource requirements. version, as well as Env variable overrides.

Field Description
replicas integer Replicas describes the number of desired pods. This is a pointer to distinguish between explicit zero and not specified. This only affects the DataPlane deployments for now, for more details on ControlPlane scaling please see https://github.com/Kong/gateway-operator/issues/736.
podTemplateSpec PodTemplateSpec PodTemplateSpec defines PodTemplateSpec for Deployment’s pods.

Appears in:

ControlPlaneOptions

ControlPlaneOptions indicates the specific information needed to deploy and connect a ControlPlane to a DataPlane object.

Field Description
deployment ControlPlaneDeploymentOptions  
dataplane string DataPlanes refers to the named DataPlane objects which this ControlPlane is responsible for. Currently they must be in the same namespace as the DataPlane.
extensions ExtensionRef array Extensions provide additional or replacement features for the ControlPlane resources to influence or enhance functionality.

Appears in:

ControlPlaneSpec

ControlPlaneSpec defines the desired state of ControlPlane

Field Description
deployment ControlPlaneDeploymentOptions  
dataplane string DataPlanes refers to the named DataPlane objects which this ControlPlane is responsible for. Currently they must be in the same namespace as the DataPlane.
extensions ExtensionRef array Extensions provide additional or replacement features for the ControlPlane resources to influence or enhance functionality.
gatewayClass ObjectName GatewayClass indicates the Gateway resources which this ControlPlane should be responsible for configuring routes for (e.g. HTTPRoute, TCPRoute, UDPRoute, TLSRoute, e.t.c.).

Required for the ControlPlane to have any effect: at least one Gateway must be present for configuration to be pushed to the data-plane and only Gateway resources can be used to identify data-plane entities.
ingressClass string IngressClass enables support for the older Ingress resource and indicates which Ingress resources this ControlPlane should be responsible for.

Routing configured this way will be applied to the Gateway resources indicated by GatewayClass.

If omitted, Ingress resources will not be supported by the ControlPlane.

Appears in:

ControlPlaneStatus

ControlPlaneStatus defines the observed state of ControlPlane

Field Description
conditions Condition array Conditions describe the current conditions of the Gateway.

Appears in:

DataPlaneDeploymentOptions

DataPlaneDeploymentOptions specifies options for the Deployments (as in the Kubernetes resource “Deployment”) which are created and managed for the DataPlane resource.

Field Description
rollout Rollout Rollout describes a custom rollout strategy.
replicas integer Replicas describes the number of desired pods. This is a pointer to distinguish between explicit zero and not specified. This is effectively shorthand for setting a scaling minimum and maximum to the same value. This field and the scaling field are mutually exclusive: You can only configure one or the other.
scaling Scaling Scaling defines the scaling options for the deployment.
podTemplateSpec PodTemplateSpec PodTemplateSpec defines PodTemplateSpec for Deployment’s pods. It’s being applied on top of the generated Deployments using StrategicMergePatch.

Appears in:

DataPlaneNetworkOptions

DataPlaneNetworkOptions defines network related options for a DataPlane.

Field Description
services DataPlaneServices Services indicates the configuration of Kubernetes Services needed for the topology of various forms of traffic (including ingress, e.t.c.) to and from the DataPlane.
konnectCertificate KonnectCertificateOptions KonnectCA is the certificate authority that the operator uses to provision client certificates the DataPlane will use to authenticate itself to the Konnect API. Requires Enterprise.

Appears in:

DataPlaneOptions

DataPlaneOptions defines the information specifically needed to deploy the DataPlane.

Field Description
deployment DataPlaneDeploymentOptions  
network DataPlaneNetworkOptions  

Appears in:

DataPlaneRolloutStatus

DataPlaneRolloutStatus describes the DataPlane rollout status.

Field Description
services DataPlaneRolloutStatusServices Services contain the information about the services which are available through which user can access the preview deployment.
deployment DataPlaneRolloutStatusDeployment Deployment contains the information about the preview deployment.
conditions Condition array Conditions contains the status conditions about the rollout.

Appears in:

DataPlaneRolloutStatusDeployment

DataPlaneRolloutStatusDeployment is a rollout status field which contains fields specific for Deployments during the rollout.

Field Description
selector string Selector is a stable label selector value assigned to a DataPlane rollout status which is used throughout the rollout as a deterministic labels selector for Services and Deployments.

Appears in:

DataPlaneRolloutStatusServices

DataPlaneRolloutStatusServices describes the status of the services during DataPlane rollout.

Field Description
ingress RolloutStatusService Ingress contains the name and the address of the preview service for ingress. Using this service users can send requests that will hit the preview deployment.
adminAPI RolloutStatusService AdminAPI contains the name and the address of the preview service for Admin API. Using this service users can send requests to configure the DataPlane’s preview deployment.

Appears in:

DataPlaneServiceOptions

DataPlaneServiceOptions contains Services related DataPlane configuration.

Field Description
ports DataPlaneServicePort array Ports defines the list of ports that are exposed by the service. The ports field allows defining the name, port and targetPort of the underlying service ports, while the protocol is defaulted to TCP, as it is the only protocol currently supported.
type ServiceType Type determines how the Service is exposed. Defaults to LoadBalancer.

Valid options are LoadBalancer and ClusterIP.

ClusterIP allocates a cluster-internal IP address for load-balancing to endpoints.

LoadBalancer builds on NodePort and creates an external load-balancer (if supported in the current cloud) which routes to the same endpoints as the clusterIP.

More info: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types
annotations object (keys:string, values:string) Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects.

More info: http://kubernetes.io/docs/user-guide/annotations
externalTrafficPolicy ServiceExternalTrafficPolicy ExternalTrafficPolicy describes how nodes distribute service traffic they receive on one of the Service’s “externally-facing” addresses (NodePorts, ExternalIPs, and LoadBalancer IPs). If set to “Local”, the proxy will configure the service in a way that assumes that external load balancers will take care of balancing the service traffic between nodes, and so each node will deliver traffic only to the node-local endpoints of the service, without masquerading the client source IP. (Traffic mistakenly sent to a node with no endpoints will be dropped.) The default value, “Cluster”, uses the standard behavior of routing to all endpoints evenly (possibly modified by topology and other features). Note that traffic sent to an External IP or LoadBalancer IP from within the cluster will always get “Cluster” semantics, but clients sending to a NodePort from within the cluster may need to take traffic policy into account when picking a node.

More info: https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip

Appears in:

DataPlaneServicePort

DataPlaneServicePort contains information on service’s port.

Field Description
name string The name of this port within the service. This must be a DNS_LABEL. All ports within a ServiceSpec must have unique names. When considering the endpoints for a Service, this must match the ‘name’ field in the EndpointPort. Optional if only one ServicePort is defined on this service.
port integer The port that will be exposed by this service.
targetPort IntOrString Number or name of the port to access on the pods targeted by the service. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. If this is a string, it will be looked up as a named port in the target Pod’s container ports. If this is not specified, the value of the ‘port’ field is used (an identity map). This field is ignored for services with clusterIP=None, and should be omitted or set equal to the ‘port’ field. More info: https://kubernetes.io/docs/concepts/services-networking/service/#defining-a-service

Appears in:

DataPlaneServices

DataPlaneServices contains Services related DataPlane configuration, shared with the GatewayConfiguration.

Field Description
ingress DataPlaneServiceOptions Ingress is the Kubernetes Service that will be used to expose ingress traffic for the DataPlane. Here you can determine whether the DataPlane will be exposed outside the cluster (e.g. using a LoadBalancer type Services) or only internally (e.g. ClusterIP), and inject any additional annotations you need on the service (for instance, if you need to influence a cloud provider LoadBalancer configuration).

Appears in:

DataPlaneSpec

DataPlaneSpec defines the desired state of DataPlane

Field Description
deployment DataPlaneDeploymentOptions  
network DataPlaneNetworkOptions  

Appears in:

DataPlaneStatus

DataPlaneStatus defines the observed state of DataPlane

Field Description
conditions Condition array Conditions describe the status of the DataPlane.
service string Service indicates the Service that exposes the DataPlane’s configured routes
addresses Address array Addresses lists the addresses that have actually been bound to the DataPlane.
selector string Selector contains a unique DataPlane identifier used as a deterministic label selector that is used throughout its dependent resources. This is used e.g. as a label selector for DataPlane’s Services and Deployments.
readyReplicas integer ReadyReplicas indicates how many replicas have reported to be ready.
replicas integer Replicas indicates how many replicas have been set for the DataPlane.
rollout DataPlaneRolloutStatus RolloutStatus contains information about the rollout. It is set only if a rollout strategy was configured in the spec.

Appears in:

DeploymentOptions

DeploymentOptions is a shared type used on objects to indicate that their configuration results in a Deployment which is managed by the Operator and includes options for managing Deployments such as the number of replicas or pod options like container image and resource requirements. version, as well as Env variable overrides.

Field Description
replicas integer Replicas describes the number of desired pods. This is a pointer to distinguish between explicit zero and not specified. This is effectively shorthand for setting a scaling minimum and maximum to the same value. This field and the scaling field are mutually exclusive: You can only configure one or the other.
scaling Scaling Scaling defines the scaling options for the deployment.
podTemplateSpec PodTemplateSpec PodTemplateSpec defines PodTemplateSpec for Deployment’s pods. It’s being applied on top of the generated Deployments using StrategicMergePatch.

Appears in:

GatewayConfigDataPlaneNetworkOptions

GatewayConfigDataPlaneNetworkOptions defines network related options for a DataPlane.

Field Description
services GatewayConfigDataPlaneServices Services indicates the configuration of Kubernetes Services needed for the topology of various forms of traffic (including ingress, etc.) to and from the DataPlane.

Appears in:

GatewayConfigDataPlaneOptions

GatewayConfigDataPlaneOptions indicates the specific information needed to configure and deploy a DataPlane object.

Field Description
deployment DataPlaneDeploymentOptions  
network GatewayConfigDataPlaneNetworkOptions  

Appears in:

GatewayConfigDataPlaneServices

GatewayConfigDataPlaneServices contains Services related DataPlane configuration.

Field Description
ingress GatewayConfigServiceOptions Ingress is the Kubernetes Service that will be used to expose ingress traffic for the DataPlane. Here you can determine whether the DataPlane will be exposed outside the cluster (e.g. using a LoadBalancer type Services) or only internally (e.g. ClusterIP), and inject any additional annotations you need on the service (for instance, if you need to influence a cloud provider LoadBalancer configuration).

Appears in:

GatewayConfigServiceOptions

GatewayConfigServiceOptions is used to includes options to customize the ingress service, such as the annotations.

Field Description
type ServiceType Type determines how the Service is exposed. Defaults to LoadBalancer.

Valid options are LoadBalancer and ClusterIP.

ClusterIP allocates a cluster-internal IP address for load-balancing to endpoints.

LoadBalancer builds on NodePort and creates an external load-balancer (if supported in the current cloud) which routes to the same endpoints as the clusterIP.

More info: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types
annotations object (keys:string, values:string) Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects.

More info: http://kubernetes.io/docs/user-guide/annotations
externalTrafficPolicy ServiceExternalTrafficPolicy ExternalTrafficPolicy describes how nodes distribute service traffic they receive on one of the Service’s “externally-facing” addresses (NodePorts, ExternalIPs, and LoadBalancer IPs). If set to “Local”, the proxy will configure the service in a way that assumes that external load balancers will take care of balancing the service traffic between nodes, and so each node will deliver traffic only to the node-local endpoints of the service, without masquerading the client source IP. (Traffic mistakenly sent to a node with no endpoints will be dropped.) The default value, “Cluster”, uses the standard behavior of routing to all endpoints evenly (possibly modified by topology and other features). Note that traffic sent to an External IP or LoadBalancer IP from within the cluster will always get “Cluster” semantics, but clients sending to a NodePort from within the cluster may need to take traffic policy into account when picking a node.

More info: https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip

Appears in:

GatewayConfigurationSpec

GatewayConfigurationSpec defines the desired state of GatewayConfiguration

Field Description
dataPlaneOptions GatewayConfigDataPlaneOptions DataPlaneOptions is the specification for configuration overrides for DataPlane resources that will be created for the Gateway.
controlPlaneOptions ControlPlaneOptions ControlPlaneOptions is the specification for configuration overrides for ControlPlane resources that will be created for the Gateway.

Appears in:

GatewayConfigurationStatus

GatewayConfigurationStatus defines the observed state of GatewayConfiguration

Field Description
conditions Condition array Conditions describe the current conditions of the GatewayConfigurationStatus.

Appears in:

HorizontalScaling

HorizontalScaling defines horizontal scaling options for the deployment. It holds all the options from the HorizontalPodAutoscalerSpec besides the ScaleTargetRef which is being controlled by the Operator.

Field Description
minReplicas integer minReplicas is the lower limit for the number of replicas to which the autoscaler can scale down. It defaults to 1 pod. minReplicas is allowed to be 0 if the alpha feature gate HPAScaleToZero is enabled and at least one Object or External metric is configured. Scaling is active as long as at least one metric value is available.
maxReplicas integer maxReplicas is the upper limit for the number of replicas to which the autoscaler can scale up. It cannot be less that minReplicas.
metrics MetricSpec array metrics contains the specifications for which to use to calculate the desired replica count (the maximum replica count across all metrics will be used). The desired replica count is calculated multiplying the ratio between the target value and the current value by the current number of pods. Ergo, metrics used must decrease as the pod count is increased, and vice-versa. See the individual metric source types for more information about how each type of metric must respond. If not set, the default metric will be set to 80% average CPU utilization.
behavior HorizontalPodAutoscalerBehavior behavior configures the scaling behavior of the target in both Up and Down directions (scaleUp and scaleDown fields respectively). If not set, the default HPAScalingRules for scale up and scale down are used.

Appears in:

KonnectCertificateOptions

KonnectCertificateOptions indicates how the operator should manage the certificates that managed entities will use to interact with Konnect.

Field Description
issuer NamespacedName Issuer is the cert-manager Issuer or ClusterIssuer the operator will use to request certificates. When Namespace is set, the operator will retrieve the Issuer with that Name in that Namespace. When Namespace is omitted, the operator will retrieve the ClusterIssuer with that name.

Appears in:

NamespacedName

NamespacedName is a resource identified by name and optional namespace.

Field Description
namespace string  
name string  

Appears in:

Promotion

Promotion is a type that contains fields that define how the operator handles promotion of resources during a blue/green rollout.

Field Description
strategy PromotionStrategy Strategy indicates how you want the operator to handle the promotion of the preview (green) resources (Deployments and Services) after all workflows and tests succeed, OR if you even want it to break before performing the promotion to allow manual inspection.

Appears in:

PromotionStrategy

Underlying type: string

PromotionStrategy is the type of promotion strategy consts.

Allowed values:

  • BreakBeforePromotion is a promotion strategy which will ensure all new resources are ready and then break, to enable manual inspection. The user must indicate manually when they want the promotion to continue. That can be done by annotating the DataPlane object with "gateway-operator.konghq.com/promote-when-ready": "true".

Appears in:

Rollout

Rollout defines options for rollouts.

Field Description
strategy RolloutStrategy Strategy contains the deployment strategy for rollout.

Appears in:

RolloutResourcePlan

RolloutResourcePlan is a type that holds rollout resource plan related fields which control how the operator handles resources during and after a rollout.

Field Description
deployment RolloutResourcePlanDeployment Deployment describes how the operator manages Deployments during and after a rollout.

Appears in:

RolloutResourcePlanDeployment

Underlying type: string

RolloutResourcePlanDeployment is the type that holds the resource plan for managing the Deployment objects during and after a rollout.

Allowed values:

  • ScaleDownOnPromotionScaleUpOnRollout is a rollout resource plan for Deployment which makes the operator scale down the Deployment to 0 when the rollout is not initiated by a spec change and then to scale it up when the rollout is initiated (the owner resource like a DataPlane is patched or updated).

Appears in:

RolloutResources

RolloutResources is the type which contains the fields which control how the operator manages the resources it manages during or after the rollout concludes.

Field Description
plan RolloutResourcePlan Plan defines the resource plan for managing resources during and after a rollout.

Appears in:

RolloutStatusService

RolloutStatusService is a struct which contains status information about services that are exposed as part of the rollout.

Field Description
name string Name indicates the name of the service.
addresses Address array Addresses contains the addresses of a Service.

Appears in:

RolloutStrategy

RolloutStrategy holds the rollout strategy options.

Field Description
blueGreen BlueGreenStrategy BlueGreen holds the options specific for Blue Green Deployments.

Appears in:

Scaling

Scaling defines the scaling options for the deployment.

Field Description
horizontal HorizontalScaling HorizontalScaling defines horizontal scaling options for the deployment.

Appears in:

ServiceOptions

ServiceOptions is used to includes options to customize the ingress service, such as the annotations.

Field Description
type ServiceType Type determines how the Service is exposed. Defaults to LoadBalancer.

Valid options are LoadBalancer and ClusterIP.

ClusterIP allocates a cluster-internal IP address for load-balancing to endpoints.

LoadBalancer builds on NodePort and creates an external load-balancer (if supported in the current cloud) which routes to the same endpoints as the clusterIP.

More info: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types
annotations object (keys:string, values:string) Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects.

More info: http://kubernetes.io/docs/user-guide/annotations
externalTrafficPolicy ServiceExternalTrafficPolicy ExternalTrafficPolicy describes how nodes distribute service traffic they receive on one of the Service’s “externally-facing” addresses (NodePorts, ExternalIPs, and LoadBalancer IPs). If set to “Local”, the proxy will configure the service in a way that assumes that external load balancers will take care of balancing the service traffic between nodes, and so each node will deliver traffic only to the node-local endpoints of the service, without masquerading the client source IP. (Traffic mistakenly sent to a node with no endpoints will be dropped.) The default value, “Cluster”, uses the standard behavior of routing to all endpoints evenly (possibly modified by topology and other features). Note that traffic sent to an External IP or LoadBalancer IP from within the cluster will always get “Cluster” semantics, but clients sending to a NodePort from within the cluster may need to take traffic policy into account when picking a node.

More info: https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip

Appears in: