diff --git a/Makefile b/Makefile index 0ee9da656..5a6122278 100644 --- a/Makefile +++ b/Makefile @@ -181,7 +181,7 @@ verify.generators: verify.repo generate verify.diff APIS_DIR ?= apis .PHONY: generate -generate: controller-gen generate.apis generate.clientsets generate.rbacs generate.gateway-api-urls generate.docs generate.k8sio-gomod-replace generate.testcases-registration generate.kic-webhook-config +generate: controller-gen generate.apis generate.clientsets generate.rbacs generate.gateway-api-urls generate.docs generate.k8sio-gomod-replace generate.testcases-registration generate.kic-webhook-config generate.cli-arguments-docs .PHONY: generate.apis generate.apis: @@ -220,6 +220,10 @@ generate.testcases-registration: generate.kic-webhook-config: kic-webhook-config-generator $(KIC_WEBHOOKCONFIG_GENERATOR) +.PHONY: generate.cli-arguments-docs +generate.cli-arguments-docs: + go run ./scripts/cli-arguments-docs-gen/main.go > ./docs/cli-arguments.md + # ------------------------------------------------------------------------------ # Files generation checks # ------------------------------------------------------------------------------ diff --git a/docs/api-reference.md b/docs/api-reference.md new file mode 100644 index 000000000..64f6bc5c4 --- /dev/null +++ b/docs/api-reference.md @@ -0,0 +1,1292 @@ + + +## Packages +- [gateway-operator.konghq.com/v1alpha1](#gateway-operatorkonghqcomv1alpha1) +- [gateway-operator.konghq.com/v1beta1](#gateway-operatorkonghqcomv1beta1) + + +## gateway-operator.konghq.com/v1alpha1 + +Package v1alpha1 contains API Schema definitions for the operator v1alpha1 API group + +- [AIGateway](#aigateway) +- [DataPlaneMetricsExtension](#dataplanemetricsextension) + +### AIGateway + + + +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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[AIGatewaySpec](#aigatewayspec)_ | Spec is the desired state of the AIGateway. | +| `status` _[AIGatewayStatus](#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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[DataPlaneMetricsExtensionSpec](#dataplanemetricsextensionspec)_ | | +| `status` _[DataPlaneMetricsExtensionStatus](#dataplanemetricsextensionstatus)_ | | + + + + +### AICloudProvider + + + +AICloudProvider is the organization that provides API access to Large Language +Models (LLMs). + + + +| Field | Description | +| --- | --- | +| `name` _[AICloudProviderName](#aicloudprovidername)_ | Name is the unique name of an LLM provider. | + + +_Appears in:_ +- [CloudHostedLargeLanguageModel](#cloudhostedlargelanguagemodel) + +### 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:_ +- [AIGatewaySpec](#aigatewayspec) + +### AICloudProviderName + +_Underlying type:_ `string` + +AICloudProviderName indicates the unique name of a supported AI cloud +provider. + + + + + +_Appears in:_ +- [AICloudProvider](#aicloudprovider) + +### 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) + +### AIGatewayEndpoint + + + +AIGatewayEndpoint is a network endpoint for accessing an AIGateway. + + + +| Field | Description | +| --- | --- | +| `network` _[EndpointNetworkAccessHint](#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](#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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#condition-v1-meta) array_ | Conditions describe the current conditions of the AIGatewayEndpoint.





Known condition types are:





- "Provisioning"

- "EndpointReady" | + + +_Appears in:_ +- [AIGatewayStatus](#aigatewaystatus) + +### 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)_ | 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](#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:_ +- [AIGateway](#aigateway) + +### AIGatewayStatus + + + +AIGatewayStatus defines the observed state of AIGateway. + + + +| Field | Description | +| --- | --- | +| `endpoints` _[AIGatewayEndpoint](#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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#condition-v1-meta) array_ | Conditions describe the current conditions of the AIGateway.





Known condition types are:





- "Accepted"

- "Provisioning"

- "EndpointsReady" | + + +_Appears in:_ +- [AIGateway](#aigateway) + +### 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](#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](#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](#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)_ | AICloudProvider defines the cloud provider that will fulfill the LLM

requests for this CloudHostedLargeLanguageModel | + + +_Appears in:_ +- [LargeLanguageModels](#largelanguagemodels) + +### DataPlaneMetricsExtensionSpec + + + +DataPlaneMetricsExtensionSpec defines the spec for the DataPlaneMetricsExtension. + + + +| Field | Description | +| --- | --- | +| `serviceSelector` _[ServiceSelector](#serviceselector)_ | ServiceSelector holds the service selector specifying the services

for which metrics should be collected. | +| `config` _[MetricsConfig](#metricsconfig)_ | Config holds the configuration for the DataPlane metrics. | + + +_Appears in:_ +- [DataPlaneMetricsExtension](#dataplanemetricsextension) + +### DataPlaneMetricsExtensionStatus + + + +DataPlaneMetricsExtensionStatus defines the status of the DataPlaneMetricsExtension. + + + +| Field | Description | +| --- | --- | +| `controlPlaneRef` _[NamespacedRef](#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:_ +- [DataPlaneMetricsExtension](#dataplanemetricsextension) + +### 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:_ +- [AIGatewayEndpoint](#aigatewayendpoint) + +### 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:_ +- [ControlPlaneOptions](#controlplaneoptions) +- [ControlPlaneSpec](#controlplanespec) + +### 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](#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:_ +- [CloudHostedLargeLanguageModel](#cloudhostedlargelanguagemodel) + +### 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:_ +- [CloudHostedLargeLanguageModel](#cloudhostedlargelanguagemodel) + +### LLMPromptRole + +_Underlying type:_ `string` + +LLMPromptRole indicates the role of a prompt for a large language model (LLM). + + + + + +_Appears in:_ +- [LLMPrompt](#llmprompt) + +### LLMPromptType + +_Underlying type:_ `string` + +LLMPromptType indicates the type of prompt to be used for a large +language model (LLM). + + + + + +_Appears in:_ +- [CloudHostedLargeLanguageModel](#cloudhostedlargelanguagemodel) + +### 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](#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:_ +- [AIGatewaySpec](#aigatewayspec) + +### 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:_ +- [DataPlaneMetricsExtensionSpec](#dataplanemetricsextensionspec) + +### 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:_ +- [DataPlaneMetricsExtensionStatus](#dataplanemetricsextensionstatus) +- [ExtensionRef](#extensionref) + +### ServiceSelector + + + +ServiceSelector holds the service selector specification. + + + +| Field | Description | +| --- | --- | +| `matchNames` _[ServiceSelectorEntry](#serviceselectorentry) array_ | MatchNames holds the list of Services names to match. | + + +_Appears in:_ +- [DataPlaneMetricsExtensionSpec](#dataplanemetricsextensionspec) + +### 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:_ +- [ServiceSelector](#serviceselector) + + +## gateway-operator.konghq.com/v1beta1 + +Package v1beta1 contains API Schema definitions for the gateway-operator.konghq.com v1beta1 API group + +- [ControlPlane](#controlplane) +- [DataPlane](#dataplane) +- [GatewayConfiguration](#gatewayconfiguration) + +### ControlPlane + + + +ControlPlane is the Schema for the controlplanes API + + + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `gateway-operator.konghq.com/v1beta1` +| `kind` _string_ | `ControlPlane` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[ControlPlaneSpec](#controlplanespec)_ | | +| `status` _[ControlPlaneStatus](#controlplanestatus)_ | | + + + + +### DataPlane + + + +DataPlane is the Schema for the dataplanes API + + + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `gateway-operator.konghq.com/v1beta1` +| `kind` _string_ | `DataPlane` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[DataPlaneSpec](#dataplanespec)_ | | +| `status` _[DataPlaneStatus](#dataplanestatus)_ | | + + + + +### GatewayConfiguration + + + +GatewayConfiguration is the Schema for the gatewayconfigurations API + + + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `gateway-operator.konghq.com/v1beta1` +| `kind` _string_ | `GatewayConfiguration` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[GatewayConfigurationSpec](#gatewayconfigurationspec)_ | | +| `status` _[GatewayConfigurationStatus](#gatewayconfigurationstatus)_ | | + + + + +### Address + + + +Address describes an address which can be either an IP address or a hostname. + + + +| Field | Description | +| --- | --- | +| `type` _[AddressType](#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](#addresssourcetype)_ | Source type of the address. | + + +_Appears in:_ +- [DataPlaneStatus](#dataplanestatus) +- [RolloutStatusService](#rolloutstatusservice) + +### AddressSourceType + +_Underlying type:_ `string` + +AddressSourceType defines the type of source this address represents. + + +Can be one of: + + + +* `PublicLoadBalancer` + +* `PrivateLoadBalancer` + +* `PublicIP` + +* `PrivateIP` + + + + + +_Appears in:_ +- [Address](#address) + +### AddressType + +_Underlying type:_ `string` + +AddressType defines how a network address is represented as a text string. + + +Can be one of: + + + +* `IPAddress` + +* `Hostname` + + + + + +_Appears in:_ +- [Address](#address) + +### BlueGreenStrategy + + + +BlueGreenStrategy defines the Blue Green deployment strategy. + + + +| Field | Description | +| --- | --- | +| `promotion` _[Promotion](#promotion)_ | Promotion defines how the operator handles promotion of resources. | +| `resources` _[RolloutResources](#rolloutresources)_ | Resources controls what happens to operator managed resources during or

after a rollout. | + + +_Appears in:_ +- [RolloutStrategy](#rolloutstrategy) + +### 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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#podtemplatespec-v1-core)_ | PodTemplateSpec defines PodTemplateSpec for Deployment's pods. | + + +_Appears in:_ +- [ControlPlaneOptions](#controlplaneoptions) +- [ControlPlaneSpec](#controlplanespec) + +### ControlPlaneOptions + + + +ControlPlaneOptions indicates the specific information needed to +deploy and connect a ControlPlane to a DataPlane object. + + + +| Field | Description | +| --- | --- | +| `deployment` _[ControlPlaneDeploymentOptions](#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](#extensionref) array_ | Extensions provide additional or replacement features for the ControlPlane

resources to influence or enhance functionality. | + + +_Appears in:_ +- [ControlPlaneSpec](#controlplanespec) +- [GatewayConfigurationSpec](#gatewayconfigurationspec) + +### ControlPlaneSpec + + + +ControlPlaneSpec defines the desired state of ControlPlane + + + +| Field | Description | +| --- | --- | +| `deployment` _[ControlPlaneDeploymentOptions](#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](#extensionref) array_ | Extensions provide additional or replacement features for the ControlPlane

resources to influence or enhance functionality. | +| `gatewayClass` _[ObjectName](#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:_ +- [ControlPlane](#controlplane) + +### ControlPlaneStatus + + + +ControlPlaneStatus defines the observed state of ControlPlane + + + +| Field | Description | +| --- | --- | +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#condition-v1-meta) array_ | Conditions describe the current conditions of the Gateway. | + + +_Appears in:_ +- [ControlPlane](#controlplane) + +### 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)_ | 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)_ | Scaling defines the scaling options for the deployment. | +| `podTemplateSpec` _[PodTemplateSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#podtemplatespec-v1-core)_ | PodTemplateSpec defines PodTemplateSpec for Deployment's pods.

It's being applied on top of the generated Deployments using

[StrategicMergePatch](https://pkg.go.dev/k8s.io/apimachinery/pkg/util/strategicpatch#StrategicMergePatch). | + + +_Appears in:_ +- [DataPlaneOptions](#dataplaneoptions) +- [DataPlaneSpec](#dataplanespec) +- [GatewayConfigDataPlaneOptions](#gatewayconfigdataplaneoptions) + +### DataPlaneNetworkOptions + + + +DataPlaneNetworkOptions defines network related options for a DataPlane. + + + +| Field | Description | +| --- | --- | +| `services` _[DataPlaneServices](#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](#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) +- [DataPlaneSpec](#dataplanespec) + +### DataPlaneOptions + + + +DataPlaneOptions defines the information specifically needed to +deploy the DataPlane. + + + +| Field | Description | +| --- | --- | +| `deployment` _[DataPlaneDeploymentOptions](#dataplanedeploymentoptions)_ | | +| `network` _[DataPlaneNetworkOptions](#dataplanenetworkoptions)_ | | + + +_Appears in:_ +- [DataPlaneSpec](#dataplanespec) + +### DataPlaneRolloutStatus + + + +DataPlaneRolloutStatus describes the DataPlane rollout status. + + + +| Field | Description | +| --- | --- | +| `services` _[DataPlaneRolloutStatusServices](#dataplanerolloutstatusservices)_ | Services contain the information about the services which are available

through which user can access the preview deployment. | +| `deployment` _[DataPlaneRolloutStatusDeployment](#dataplanerolloutstatusdeployment)_ | Deployment contains the information about the preview deployment. | +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#condition-v1-meta) array_ | Conditions contains the status conditions about the rollout. | + + +_Appears in:_ +- [DataPlaneStatus](#dataplanestatus) + +### 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:_ +- [DataPlaneRolloutStatus](#dataplanerolloutstatus) + +### DataPlaneRolloutStatusServices + + + +DataPlaneRolloutStatusServices describes the status of the services during +DataPlane rollout. + + + +| Field | Description | +| --- | --- | +| `ingress` _[RolloutStatusService](#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](#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:_ +- [DataPlaneRolloutStatus](#dataplanerolloutstatus) + +### DataPlaneServiceOptions + + + +DataPlaneServiceOptions contains Services related DataPlane configuration. + + + +| Field | Description | +| --- | --- | +| `ports` _[DataPlaneServicePort](#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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#servicetype-v1-core)_ | 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 | + + +_Appears in:_ +- [DataPlaneServices](#dataplaneservices) + +### 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](#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:_ +- [DataPlaneServiceOptions](#dataplaneserviceoptions) + +### DataPlaneServices + + + +DataPlaneServices contains Services related DataPlane configuration, shared with the GatewayConfiguration. + + + +| Field | Description | +| --- | --- | +| `ingress` _[DataPlaneServiceOptions](#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:_ +- [DataPlaneNetworkOptions](#dataplanenetworkoptions) + +### DataPlaneSpec + + + +DataPlaneSpec defines the desired state of DataPlane + + + +| Field | Description | +| --- | --- | +| `deployment` _[DataPlaneDeploymentOptions](#dataplanedeploymentoptions)_ | | +| `network` _[DataPlaneNetworkOptions](#dataplanenetworkoptions)_ | | + + +_Appears in:_ +- [DataPlane](#dataplane) + +### DataPlaneStatus + + + +DataPlaneStatus defines the observed state of DataPlane + + + +| Field | Description | +| --- | --- | +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#condition-v1-meta) array_ | Conditions describe the status of the DataPlane. | +| `service` _string_ | Service indicates the Service that exposes the DataPlane's configured routes | +| `addresses` _[Address](#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](#dataplanerolloutstatus)_ | RolloutStatus contains information about the rollout.

It is set only if a rollout strategy was configured in the spec. | + + +_Appears in:_ +- [DataPlane](#dataplane) + +### 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)_ | Scaling defines the scaling options for the deployment. | +| `podTemplateSpec` _[PodTemplateSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#podtemplatespec-v1-core)_ | PodTemplateSpec defines PodTemplateSpec for Deployment's pods.

It's being applied on top of the generated Deployments using

[StrategicMergePatch](https://pkg.go.dev/k8s.io/apimachinery/pkg/util/strategicpatch#StrategicMergePatch). | + + +_Appears in:_ +- [DataPlaneDeploymentOptions](#dataplanedeploymentoptions) + +### GatewayConfigDataPlaneNetworkOptions + + + +GatewayConfigDataPlaneNetworkOptions defines network related options for a DataPlane. + + + +| Field | Description | +| --- | --- | +| `services` _[GatewayConfigDataPlaneServices](#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) + +### GatewayConfigDataPlaneOptions + + + +GatewayConfigDataPlaneOptions indicates the specific information needed to +configure and deploy a DataPlane object. + + + +| Field | Description | +| --- | --- | +| `deployment` _[DataPlaneDeploymentOptions](#dataplanedeploymentoptions)_ | | +| `network` _[GatewayConfigDataPlaneNetworkOptions](#gatewayconfigdataplanenetworkoptions)_ | | + + +_Appears in:_ +- [GatewayConfigurationSpec](#gatewayconfigurationspec) + +### GatewayConfigDataPlaneServices + + + +GatewayConfigDataPlaneServices contains Services related DataPlane configuration. + + + +| Field | Description | +| --- | --- | +| `ingress` _[GatewayConfigServiceOptions](#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:_ +- [GatewayConfigDataPlaneNetworkOptions](#gatewayconfigdataplanenetworkoptions) + +### GatewayConfigServiceOptions + + + +GatewayConfigServiceOptions is used to includes options to customize the ingress service, +such as the annotations. + + + +| Field | Description | +| --- | --- | +| `type` _[ServiceType](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#servicetype-v1-core)_ | 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 | + + +_Appears in:_ +- [GatewayConfigDataPlaneServices](#gatewayconfigdataplaneservices) + +### GatewayConfigurationSpec + + + +GatewayConfigurationSpec defines the desired state of GatewayConfiguration + + + +| Field | Description | +| --- | --- | +| `dataPlaneOptions` _[GatewayConfigDataPlaneOptions](#gatewayconfigdataplaneoptions)_ | DataPlaneOptions is the specification for configuration

overrides for DataPlane resources that will be created for the Gateway. | +| `controlPlaneOptions` _[ControlPlaneOptions](#controlplaneoptions)_ | ControlPlaneOptions is the specification for configuration

overrides for ControlPlane resources that will be created for the Gateway. | + + +_Appears in:_ +- [GatewayConfiguration](#gatewayconfiguration) + +### GatewayConfigurationStatus + + + +GatewayConfigurationStatus defines the observed state of GatewayConfiguration + + + +| Field | Description | +| --- | --- | +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#condition-v1-meta) array_ | Conditions describe the current conditions of the GatewayConfigurationStatus. | + + +_Appears in:_ +- [GatewayConfiguration](#gatewayconfiguration) + + + +### 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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#metricspec-v2-autoscaling) 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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#horizontalpodautoscalerbehavior-v2-autoscaling)_ | 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:_ +- [Scaling](#scaling) + +### KonnectCertificateOptions + + + +KonnectCertificateOptions indicates how the operator should manage the certificates that managed entities will use +to interact with Konnect. + + + +| Field | Description | +| --- | --- | +| `issuer` _[NamespacedName](#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:_ +- [DataPlaneNetworkOptions](#dataplanenetworkoptions) + +### NamespacedName + + + +NamespacedName is a resource identified by name and optional namespace. + + + +| Field | Description | +| --- | --- | +| `namespace` _string_ | | +| `name` _string_ | | + + +_Appears in:_ +- [KonnectCertificateOptions](#konnectcertificateoptions) + +### 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](#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:_ +- [BlueGreenStrategy](#bluegreenstrategy) + +### 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:_ +- [Promotion](#promotion) + +### Rollout + + + +Rollout defines options for rollouts. + + + +| Field | Description | +| --- | --- | +| `strategy` _[RolloutStrategy](#rolloutstrategy)_ | Strategy contains the deployment strategy for rollout. | + + +_Appears in:_ +- [DataPlaneDeploymentOptions](#dataplanedeploymentoptions) + +### 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](#rolloutresourceplandeployment)_ | Deployment describes how the operator manages Deployments during and after a rollout. | + + +_Appears in:_ +- [RolloutResources](#rolloutresources) + +### 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:_ +- [RolloutResourcePlan](#rolloutresourceplan) + +### 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](#rolloutresourceplan)_ | Plan defines the resource plan for managing resources during and after a rollout. | + + +_Appears in:_ +- [BlueGreenStrategy](#bluegreenstrategy) + +### 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](#address) array_ | Addresses contains the addresses of a Service. | + + +_Appears in:_ +- [DataPlaneRolloutStatusServices](#dataplanerolloutstatusservices) + +### RolloutStrategy + + + +RolloutStrategy holds the rollout strategy options. + + + +| Field | Description | +| --- | --- | +| `blueGreen` _[BlueGreenStrategy](#bluegreenstrategy)_ | BlueGreen holds the options specific for Blue Green Deployments. | + + +_Appears in:_ +- [Rollout](#rollout) + +### Scaling + + + +Scaling defines the scaling options for the deployment. + + + +| Field | Description | +| --- | --- | +| `horizontal` _[HorizontalScaling](#horizontalscaling)_ | HorizontalScaling defines horizontal scaling options for the deployment. | + + +_Appears in:_ +- [DataPlaneDeploymentOptions](#dataplanedeploymentoptions) +- [DeploymentOptions](#deploymentoptions) + +### ServiceOptions + + + +ServiceOptions is used to includes options to customize the ingress service, +such as the annotations. + + + +| Field | Description | +| --- | --- | +| `type` _[ServiceType](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#servicetype-v1-core)_ | 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 | + + +_Appears in:_ +- [DataPlaneServiceOptions](#dataplaneserviceoptions) +- [GatewayConfigServiceOptions](#gatewayconfigserviceoptions) + diff --git a/docs/cli-arguments.md b/docs/cli-arguments.md new file mode 100644 index 000000000..44f4ddd86 --- /dev/null +++ b/docs/cli-arguments.md @@ -0,0 +1,22 @@ + + +## Flags + +| Flag | Type | Description | Default | +| ---- | ---- | ----------- | ------- | +| `--anonymous-reports` | `bool` | Send anonymized usage data to help improve Kong. | `true` | +| `--apiserver-host` | `string` | The Kubernetes API server URL. If not set, the operator will use cluster config discovery. | `` | +| `--cluster-ca-secret` | `string` | Name of the Secret containing the cluster CA certificate. | `kong-operator-ca` | +| `--cluster-ca-secret-namespace` | `string` | Name of the namespace for Secret containing the cluster CA certificate. | `` | +| `--controller-name` | `string` | Controller name to use if other than the default, only needed for multi-tenancy. | `` | +| `--enable-controller-aigateway` | `bool` | Enable the AIGateway controller. (Experimental). | `false` | +| `--enable-controller-controlplane` | `bool` | Enable the ControlPlane controller. | `true` | +| `--enable-controller-dataplane` | `bool` | Enable the DataPlane controller. | `true` | +| `--enable-controller-dataplane-bluegreen` | `bool` | Enable the DataPlane BlueGreen controller. Mutually exclusive with DataPlane controller. | `true` | +| `--enable-controller-gateway` | `bool` | Enable the Gateway controller. | `true` | +| `--enable-validating-webhook` | `bool` | Enable the validating webhook. | `true` | +| `--health-probe-bind-address` | `string` | The address the probe endpoint binds to. | `:8081` | +| `--kubeconfig` | `string` | Path to the kubeconfig file. | `` | +| `--metrics-bind-address` | `string` | The address the metric endpoint binds to. | `:8080` | +| `--no-leader-election` | `bool` | Disable leader election for controller manager. Disabling this will not ensure there is only one active controller manager. | `false` | +| `--version` | `bool` | Print version information. | `false` | diff --git a/modules/cli/cli.go b/modules/cli/cli.go index 12aedefc9..114a6dfc6 100644 --- a/modules/cli/cli.go +++ b/modules/cli/cli.go @@ -19,7 +19,7 @@ func New() *CLI { var cfg manager.Config var deferCfg flagsForFurtherEvaluation - flagSet.BoolVar(&cfg.AnonymousReports, "anonymous-reports", true, "Send anonymized usage data to help improve Kong") + flagSet.BoolVar(&cfg.AnonymousReports, "anonymous-reports", true, "Send anonymized usage data to help improve Kong.") flagSet.StringVar(&cfg.APIServerPath, "apiserver-host", "", "The Kubernetes API server URL. If not set, the operator will use cluster config discovery.") flagSet.StringVar(&cfg.KubeconfigPath, "kubeconfig", "", "Path to the kubeconfig file.") @@ -28,9 +28,9 @@ func New() *CLI { flagSet.BoolVar(&deferCfg.DisableLeaderElection, "no-leader-election", false, "Disable leader election for controller manager. Disabling this will not ensure there is only one active controller manager.") - flagSet.StringVar(&cfg.ControllerName, "controller-name", "", "a controller name to use if other than the default, only needed for multi-tenancy") - flagSet.StringVar(&cfg.ClusterCASecretName, "cluster-ca-secret", "kong-operator-ca", "name of the Secret containing the cluster CA certificate") - flagSet.StringVar(&deferCfg.ClusterCASecretNamespace, "cluster-ca-secret-namespace", "", "name of the namespace for Secret containing the cluster CA certificate") + flagSet.StringVar(&cfg.ControllerName, "controller-name", "", "Controller name to use if other than the default, only needed for multi-tenancy.") + flagSet.StringVar(&cfg.ClusterCASecretName, "cluster-ca-secret", "kong-operator-ca", "Name of the Secret containing the cluster CA certificate.") + flagSet.StringVar(&deferCfg.ClusterCASecretNamespace, "cluster-ca-secret-namespace", "", "Name of the namespace for Secret containing the cluster CA certificate.") // controllers for standard APIs and features flagSet.BoolVar(&cfg.GatewayControllerEnabled, "enable-controller-gateway", true, "Enable the Gateway controller.") @@ -39,12 +39,12 @@ func New() *CLI { flagSet.BoolVar(&cfg.DataPlaneBlueGreenControllerEnabled, "enable-controller-dataplane-bluegreen", true, "Enable the DataPlane BlueGreen controller. Mutually exclusive with DataPlane controller.") // controllers for specialized APIs and features - flagSet.BoolVar(&cfg.AIGatewayControllerEnabled, "enable-controller-aigateway", false, "Enable the AIGateway controller. (Experimental)") + flagSet.BoolVar(&cfg.AIGatewayControllerEnabled, "enable-controller-aigateway", false, "Enable the AIGateway controller. (Experimental).") // webhook and validation options flagSet.BoolVar(&deferCfg.ValidatingWebhookEnabled, "enable-validating-webhook", true, "Enable the validating webhook.") - flagSet.BoolVar(&deferCfg.Version, "version", false, "Print version information") + flagSet.BoolVar(&deferCfg.Version, "version", false, "Print version information.") return &CLI{ flagSet: flagSet, diff --git a/scripts/cli-arguments-docs-gen/main.go b/scripts/cli-arguments-docs-gen/main.go new file mode 100644 index 000000000..6da2db215 --- /dev/null +++ b/scripts/cli-arguments-docs-gen/main.go @@ -0,0 +1,70 @@ +package main + +import ( + "flag" + "fmt" + "strings" + + "github.com/kong/gateway-operator/modules/cli" +) + +// This program generates markdown documentation for KGO executable's flags. +// It is based on KIC's +// https://github.com/Kong/kubernetes-ingress-controller/tree/513db87cbf94ce66207f74365b502e8cde841357/scripts/cli-arguments-docs-gen. +func main() { + c := cli.New() + flags := c.FlagSet() + + markdown := strings.Builder{} + markdown.WriteString("\n\n") + markdown.WriteString("## Flags\n\n") + markdown.WriteString("| Flag | Type | Description | Default |\n") + markdown.WriteString("| ---- | ---- | ----------- | ------- |\n") + + flags.VisitAll(func(flag *flag.Flag) { + name := fmt.Sprintf("`--%s`", flag.Name) + typ := fmt.Sprintf("`%s`", getTypeForHuman(flag)) + + description := flag.Usage + + // In case of panic adjust in KIC code the description of the flag. + // Make sure the first letter is capitalized. + if first := description[0]; first >= 'a' && first <= 'z' { + panic(fmt.Sprintf("flag's: %s description must start with a capital letter: %s", flag.Name, description)) + } + // Make sure the last character is a period. + if !strings.HasSuffix(description, ".") { + panic(fmt.Sprintf("flag's: %s description must end with a period: %s", flag.Name, description)) + } + + defaultValue := fmt.Sprintf("`%s`", flag.DefValue) + + markdown.WriteString(fmt.Sprintf("| %s | %s | %s | %s |\n", name, typ, description, defaultValue)) + }) + + fmt.Print(markdown.String()) +} + +// getTypeForHuman returns a human-friendly type name for the given flag that +// is compatible with native way of printing types in --help output. +// +// Panics if the type is unknown - this way it validates whether type is human readable. +func getTypeForHuman(f *flag.Flag) string { + type boolvalue interface { + IsBoolFlag() bool + } + type stringvalue interface { + Set(val string) error + Get() any + String() string + } + + switch typ := f.Value.(type) { + case boolvalue: + return "bool" + case stringvalue: + return "string" + default: + panic(fmt.Sprintf("unknown type %q", typ)) + } +} diff --git a/scripts/cli-arguments-docs-gen/post-process-for-konghq.sh b/scripts/cli-arguments-docs-gen/post-process-for-konghq.sh new file mode 100755 index 000000000..91942490c --- /dev/null +++ b/scripts/cli-arguments-docs-gen/post-process-for-konghq.sh @@ -0,0 +1,52 @@ +#!/bin/bash + +# This script adapts auto-generated cli-arguments.md to the requirements of +# docs.konghq.com: +# - adds a title section +# - adds a section explaining how environment variables are mapped onto flags +# - turns vale linter off for the generated part + +set -o errexit +set -o nounset +set -o pipefail + +SCRIPT_ROOT="$(dirname "${BASH_SOURCE[0]}")/../.." +CRD_REF_DOC="${SCRIPT_ROOT}/docs/cli-arguments.md" +POST_PROCESSED_DOC="${CRD_REF_DOC}.bak" + +# Add a title and turn the vale linter off +echo '--- +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 `GATEWAY_OPERATOR_` +string followed by the name of flag in uppercase. + +For example, `--enable-gateway-controller` can be configured using the following +environment variable: + +``` +GATEWAY_OPERATOR_ENABLE_GATEWAY_CONTROLLER=false +``` + +It is recommended that all the configuration is done through environment variables +and not CLI flags. + + +' > "${POST_PROCESSED_DOC}" + +# Add the generated doc content +cat "${CRD_REF_DOC}" >> "${POST_PROCESSED_DOC}" + +# Turn the linter back on. Add a newline first, otherwise parsing breaks. +echo "" >> "${POST_PROCESSED_DOC}" +echo "" >> "${POST_PROCESSED_DOC}" + +# Replace the original file with the post-processed one +mv "${POST_PROCESSED_DOC}" "${CRD_REF_DOC}"