Update CRD descriptions

api/v1alpha2/authorizers.go

@@ -4,30 +4,29 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
-// Authorizer defines an external authorization provider configuration.
+// Defines an external authorization provider's configuration.
 // The defined authorizer can be referenced by name in an AuthorizationPolicy
 // with action CUSTOM to enforce requests to be authorized by the external authorization service.
 type Authorizer struct {
-	// A unique name identifying the extension authorization provider.
+	// Specifies a unique name identifying the authorization provider.
 	// +kubebuilder:validation:Required
 	Name string `json:"name"`
 
-	// Specifies the service that implements the Envoy ext_authz HTTP authorization service.
-	// The format is "[Namespace/]Hostname".
-	// The specification of "Namespace" is required only when it is insufficient to unambiguously resolve a service in the service registry.
-	// The "Hostname" is a fully qualified host name of a service defined by the Kubernetes service or ServiceEntry.
-	// The recommended format is "[Namespace/]Hostname".
+	// Specifies the service that implements the Envoy `ext_authz` HTTP authorization service.
+	// The recommended format is `[Namespace/]Hostname`.
+	// Specify the namespace if it is required to unambiguously resolve a service in the service registry. 
+	// The host name refers to the fully qualified host name of a service defined by either a Kubernetes Service or a ServiceEntry.
 	Service string `json:"service"`
 
-	// Specifies the port of the service.
+	// Specifies the port of the Service.
 	// +kubebuilder:validation:Required
 	Port uint32 `json:"port"`
 
-	// Specifies headers to be included, added or forwarded during authorization.
+	// Specifies the headers included, added, or forwarded during authorization.
 	Headers *Headers `json:"headers,omitempty"`
 
-	// Specifies the prefix which will be included in the request sent to the authorization service.
-	// The prefix might be constructed with special characters (e.g., "/test?original_path=").
+	// Specifies the prefix which included in the request sent to the authorization service.
+	// The prefix might be constructed with special characters (for example, `/test?original_path=`).
 	// +kubebuilder:validation:Optional
 	PathPrefix *string `json:"pathPrefix,omitempty"`
 
@@ -36,52 +35,54 @@ type Authorizer struct {
 	Timeout *metav1.Duration `json:"timeout,omitempty"`
 }
 
-// Exact, prefix and suffix matches are supported (similar to the authorization policy rule syntax except the presence match
-// https://istio.io/latest/docs/reference/config/security/authorization-policy/#Rule):
-// - Exact match: "abc" will match on value "abc".
-// - Prefix match: "abc*" will match on value "abc" and "abcd".
-// - Suffix match: "*abc" will match on value "abc" and "xabc".
-
+// Specifies headers included, added, or forwarded during authorization.
+// Exact, prefix, and suffix matches are supported, similar to the syntax used in AuthorizationPolicy rules (excluding the presence match):
+// - Exact match: `abc` matches the value `abc`.
+// - Prefix match: `abc*` matches the values `abc` and `abcd`.
+// - Suffix match: `*abc` matches the values `abc` and `xabc`.
 type Headers struct {
-	// Defines headers to be included or added in check authorization request.
+	// Defines the headers to be included or added in check authorization request.
 	InCheck *InCheck `json:"inCheck,omitempty"`
 
-	// Defines headers to be forwarded to the upstream (to the backend service).
+	// Defines the headers to be forwarded to the upstream (to the backend service).
 	ToUpstream *ToUpstream `json:"toUpstream,omitempty"`
 
-	// Defines headers to be forwarded to the downstream (the client).
+	// Defines the headers to be forwarded to the downstream (the client).
 	ToDownstream *ToDownstream `json:"toDownstream,omitempty"`
 }
 
+// Defines the headers to be included or added in check authorization request.
 type InCheck struct {
-	// List of client request headers that should be included in the authorization request sent to the authorization service.
-	// Note that in addition to the headers specified here, the following headers are included by default:
-	// 1. *Host*, *Method*, *Path* and *Content-Length* are automatically sent.
-	// 2. *Content-Length* will be set to 0, and the request will not have a message body. However, the authorization request can include the buffered client request body (controlled by include_request_body_in_check setting), consequently the value of Content-Length of the authorization request reflects the size of its payload size.
+	// Lists client request headers included in the authorization request sent to the authorization service.
+	// In addition to the headers specified here, the following headers are included by default:
+	// - *Host*, *Method*, *Path*, and *Content-Length* are automatically sent.
+	// - *Content-Length* is set to `0`, and the request does have a message body. However, the authorization request can include the buffered client request body (controlled by the **include_request_body_in_check** setting), consequently the **Content-Length** value of the authorization request reflects its payload size.
 	Include []string `json:"include,omitempty"`
 
-	// Set of additional fixed headers that should be included in the authorization request sent to the authorization service.
-	// The Key is the header name and value is the header value.
-	// Note that client request of the same key or headers specified in `Include` will be overridden.
+	// Specifies a set of additional fixed headers that included in the authorization request sent to the authorization service.
+	// The key is the header name and value is the header value.
+	// Client request of the same key or headers specified in `Include` are overridden.
 	Add map[string]string `json:"add,omitempty"`
 }
 
+// Defines the headers to be forwarded to the upstream (to the backend service).	
 type ToUpstream struct {
-	// List of headers from the authorization service that should be added or overridden in the original request and forwarded to the upstream when the authorization check result is allowed (HTTP code 200).
-	// If not specified, the original request will not be modified and forwarded to backend as-is.
-	// Note, any existing headers will be overridden.
+	// Lists headers from the authorization service added or overridden in the original request and forwarded to the upstream when the authorization check result is allowed (HTTP code `200`).
+	// If not specified, the original request is forwarded to the backend unmodified.
+	// Any existing headers are overridden.
 	OnAllow []string `json:"onAllow,omitempty"`
 }
 
+// Defines the headers to be forwarded to the downstream (the client).
 type ToDownstream struct {
-	// List of headers from the authorization service that should be forwarded to downstream when the authorization check result is allowed (HTTP code 200).
-	// If not specified, the original response will not be modified and forwarded to downstream as-is.
-	// Note, any existing headers will be overridden.
+	// Lists headers from the authorization service forwarded to downstream when the authorization check result is allowed (HTTP code `200`).
+	// If not specified, the original request is forwarded to the backend unmodified.
+	// Any existing headers are overridden.
 	OnAllow []string `json:"onAllow,omitempty"`
 
-	// List of headers from the authorization service that should be forwarded to downstream when the authorization check result is not allowed (HTTP code other than 200).
-	// If not specified, all the authorization response headers, except *Authority (Host)* will be in the response to the downstream.
-	// When a header is included in this list, *Path*, *Status*, *Content-Length*, *WWWAuthenticate* and *Location* are automatically added.
-	// Note, the body from the authorization service is always included in the response to downstream.
+	// Lists headers from the authorization service forwarded to downstream when the authorization check result is not allowed (HTTP code is other than `200`).
+	// If not specified, all the authorization response headers, except *Authority (Host)*, are included in the response to the downstream.
+	// When a header is included in this list, the following headers are automatically added: *Path*, *Status*, *Content-Length*, *WWWAuthenticate*, and *Location*.
+	// The body from the authorization service is always included in the response to downstream.
 	OnDeny []string `json:"onDeny,omitempty"`
-}
+}

api/v1alpha2/istio_structs.go

@@ -5,9 +5,8 @@ import (
 	"k8s.io/apimachinery/pkg/util/intstr"
 )
 
+// Configures the Istio installation.
 // +kubebuilder:validation:Optional
-
-// Config is the configuration for the Istio installation.
 type Config struct {
 	// Defines the number of trusted proxies deployed in front of the Istio gateway proxy.
 	// +kubebuilder:validation:Minimum=0
@@ -17,8 +16,8 @@ type Config struct {
 	// Defines a list of external authorization providers.
 	Authorizers []*Authorizer `json:"authorizers,omitempty"`
 
-	// Defines the external traffic policy for the Istio Ingress Gateway Service. Valid configurations are "Local" or "Cluster". The external traffic policy set to "Local" preserves the client IP in the request, but also introduces the risk of unbalanced traffic distribution.
-	// WARNING: Switching `externalTrafficPolicy` may result in a temporal increase in request delay. Make sure that this is acceptable.
+	// Defines the external traffic policy for the Istio Ingress Gateway Service. Valid configurations are `"Local"` or `"Cluster"`. The external traffic policy set to `"Local"` preserves the client IP in the request, but also introduces the risk of unbalanced traffic distribution.
+	// WARNING: Switching **externalTrafficPolicy** may result in a temporal increase in request delay. Make sure that this is acceptable.
 	// +kubebuilder:validation:Optional
 	// +kubebuilder:validation:Enum=Local;Cluster
 	GatewayExternalTrafficPolicy *string `json:"gatewayExternalTrafficPolicy,omitempty"`
@@ -28,114 +27,129 @@ type Config struct {
 	Telemetry Telemetry `json:"telemetry,omitempty"`
 }
 
+// Configures Istio components.
 type Components struct {
-	// Pilot defines component configuration for Istiod
+	// Configures the Istio Pilot component.
 	Pilot *IstioComponent `json:"pilot,omitempty"`
-	// IngressGateway defines component configurations for Istio Ingress Gateway
+	// Configures the Istio Ingress Gateway component.
 	IngressGateway *IstioComponent `json:"ingressGateway,omitempty"`
-	// Cni defines component configuration for Istio CNI DaemonSet
+	// Configures the Istio CNI DaemonSet component.
 	Cni *CniComponent `json:"cni,omitempty"`
-	// Proxy defines component configuration for Istio proxy sidecar
+	// Configures the Istio sidecar proxy component.
 	Proxy *ProxyComponent `json:"proxy,omitempty"`
+	// Configures the Istio Egress Gateway component.
 	// +kubebuilder:validation:Optional
 	EgressGateway *EgressGateway `json:"egressGateway,omitempty"`
 }
 
-// KubernetesResourcesConfig is a subset of https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/#KubernetesResourcesSpec
+// Defines Kubernetes-level configuration options for Istio components. It's a subset of [KubernetesResourcesSpec](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/#KubernetesResourcesSpec).
 type KubernetesResourcesConfig struct {
-	// HPASpec defines configuration for HorizontalPodAutoscaler: https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/
+	// Configures the [HorizontalPodAutoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/).
 	// +kubebuilder:validation:Optional
 	HPASpec *HPASpec `json:"hpaSpec,omitempty"`
-	// Strategy defines configuration for rolling updates: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#rolling-update-deployment
+	// Defines the rolling updates strategy. See [Rolling Update Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#rolling-update-deployment).
 	// +kubebuilder:validation:Optional
 	Strategy *Strategy `json:"strategy,omitempty"`
-	// Resources define Kubernetes resources configuration: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+	// Defines Kubernetes resources' configuration. See [Resource Management for Pods and Containers](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/).
 	// +kubebuilder:validation:Optional
 	Resources *Resources `json:"resources,omitempty"`
 }
 
-// ProxyComponent defines configuration for Istio proxies.
+// Configures the Istio sidecar proxy component.
 type ProxyComponent struct {
+	// **ProxyK8sConfig** is a subset of [KubernetesResourcesSpec](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/#KubernetesResourcesSpec).
 	// +kubebuilder:validation:Required
 	K8S *ProxyK8sConfig `json:"k8s"`
 }
 
-// ProxyK8sConfig is a subset of https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/#KubernetesResourcesSpec
+// **ProxyK8sConfig** is a subset of [KubernetesResourcesSpec](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/#KubernetesResourcesSpec).
 type ProxyK8sConfig struct {
+	// Defines Kubernetes resources' configuration. See [Resource Management for Pods and Containers](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/).
 	Resources *Resources `json:"resources,omitempty"`
 }
 
-// CniComponent defines configuration for CNI Istio component.
+// Configures the Istio CNI DaemonSet component.
 type CniComponent struct {
-	// CniK8sConfig is a subset of https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/#KubernetesResourcesSpec
+	// Configures the Istio CNI DaemonSet component. It is a subset of [KubernetesResourcesSpec](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/#KubernetesResourcesSpec).
 	// +kubebuilder:validation:Required
 	K8S *CniK8sConfig `json:"k8s"`
 }
 
+// Configures the Istio CNI DaemonSet component. It is a subset of [KubernetesResourcesSpec](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/#KubernetesResourcesSpec).
 type CniK8sConfig struct {
-	// Affinity defines the Pod scheduling affinity constraints: https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity
+	// Defines the Pod scheduling affinity constraints. See [Affinity and anti-affinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity).
 	// +kubebuilder:validation:Optional
 	Affinity *corev1.Affinity `json:"affinity,omitempty"`
-	// Resources define Kubernetes resources configuration: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+	// Defines Kubernetes resources' configuration. See [Resource Management for Pods and Containers](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/).
 	// +kubebuilder:validation:Optional
 	Resources *Resources `json:"resources,omitempty"`
 }
 
-// HPASpec defines configuration for HorizontalPodAutoscaler.
+// Configures the [HorizontalPodAutoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/).
 type HPASpec struct {
+	// Defines the minimum number of replicas for the HorizontalPodAutoscaler.
 	// +kubebuilder:validation:Minimum=0
 	// +kubebuilder:validation:Maximum=2147483647
 	MaxReplicas *int32 `json:"maxReplicas,omitempty"`
 
+	// Defines the maximum number of replicas for the HorizontalPodAutoscaler.
 	// +kubebuilder:validation:Minimum=0
 	// +kubebuilder:validation:Maximum=2147483647
 	MinReplicas *int32 `json:"minReplicas,omitempty"`
 }
 
-// IstioComponent defines configuration for generic Istio component (ingress gateway, istiod).
+// Defines the configuration for the generic Istio components, that is, Istio Ingress gateway and istiod.
 type IstioComponent struct {
+	// Defines the Kubernetes resources' configuration for Istio components. It's a subset of [KubernetesResourcesSpec](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/#KubernetesResourcesSpec).
 	// +kubebuilder:validation:Required
 	K8s *KubernetesResourcesConfig `json:"k8s"`
 }
 
-// Strategy defines rolling update strategy.
+// Defines the rolling updates strategy. See [Rolling Update Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#rolling-update-deployment).
 type Strategy struct {
+	// Defines the configuration for rolling updates. See [Rolling Update Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#rolling-update-deployment).
 	// +kubebuilder:validation:Required
 	RollingUpdate *RollingUpdate `json:"rollingUpdate"`
 }
 
-// RollingUpdate defines configuration for rolling updates: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#rolling-update-deployment
+// Defines the configuration for rolling updates. See [Rolling Update Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#rolling-update-deployment).
 type RollingUpdate struct {
+	// Specifies the maximum number of Pods that can be unavailable during the update process. See [Max Surge](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#max-surge).
 	// +kubebuilder:validation:XIntOrString
 	// +kubebuilder:validation:Pattern=`^[0-9]+%?$`
 	// +kubebuilder:validation:XValidation:rule="(type(self) == int ? self >= 0 && self <= 2147483647: self.size() >= 0)",message="must not be negative, more than 2147483647 or an empty string"
 	MaxSurge *intstr.IntOrString `json:"maxSurge"       protobuf:"bytes,2,opt,name=maxSurge"`
+	// Specifies the maximum number of Pods that can be created over the desired number of Pods. See [Max Unavailable](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#max-unavailable)
 	// +kubebuilder:validation:XIntOrString
 	// +kubebuilder:validation:Pattern="^((100|[0-9]{1,2})%|[0-9]+)$"
 	// +kubebuilder:validation:XValidation:rule="(type(self) == int ? self >= 0 && self <= 2147483647: self.size() >= 0)",message="must not be negative, more than 2147483647 or an empty string"
 	MaxUnavailable *intstr.IntOrString `json:"maxUnavailable" protobuf:"bytes,1,opt,name=maxUnavailable"`
 }
 
-// Resources define Kubernetes resources configuration: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+// Defines Kubernetes resources' configuration. See [Resource Management for Pods and Containers](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/).
 type Resources struct {
+	// The maximum amount of resources a container is allowed to use.
 	Limits   *ResourceClaims `json:"limits,omitempty"`
+	// The minimum amount of resources ( such as CPU and memory) a container needs to run.
 	Requests *ResourceClaims `json:"requests,omitempty"`
 }
 
+// Defines CPU and memory resource requirements for Kubernetes containers and Pods. See [Resource Management for Pods and Containers](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/).
 type ResourceClaims struct {
+	// Specifies CPU resource allocation (requests or limits)
 	// +kubebuilder:validation:Pattern=`^([0-9]+m?|[0-9]\.[0-9]{1,3})$`
 	CPU *string `json:"cpu,omitempty"`
-
+	// Specifies memory resource allocation (requests or limits).
 	// +kubebuilder:validation:Pattern=`^[0-9]+(((\.[0-9]+)?(E|P|T|G|M|k|Ei|Pi|Ti|Gi|Mi|Ki|m)?)|(e[0-9]+))$`
 	Memory *string `json:"memory,omitempty"`
 }
 
-// EgressGateway defines configuration for Istio egressGateway.
+// Configures the Istio Egress Gateway component.
 type EgressGateway struct {
-	// Defines the Kubernetes resources configuration for Istio egress gateway.
+	// Defines the Kubernetes resources' configuration for Istio Egress Gateway. It's a subset of [KubernetesResourcesSpec](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/#KubernetesResourcesSpec).
 	// +kubebuilder:validation:Optional
 	K8s *KubernetesResourcesConfig `json:"k8s"`
-	// Enables or disables the Istio egress gateway.
+	// Enables or disables Istio Egress Gateway.
 	// +kubebuilder:validation:Optional
 	Enabled *bool `json:"enabled,omitempty"`
-}
+}