Update CRD descriptions

Makefile

@@ -302,7 +302,9 @@ generate-crd-docs: bin/crd-ref-docs ## Generate CRD reference docs
 	--config=crd-ref-docs/config.yaml \
 	--templates-dir=crd-ref-docs/templates \
 	--max-depth=25
-	# Replace Optional: \{\} and Required: \{\} with Optional and Required
 	sed -i'' -e 's/Optional: \\{\\}/Optional/g' docs/user/04-00-istio-custom-resource.md
 	sed -i'' -e 's/Required: \\{\\}/Required/g' docs/user/04-00-istio-custom-resource.md
-	rm docs/user/04-00-istio-custom-resource.md-e
+	sed -i'' -e 's/XIntOrString: \\{\\}/XIntOrString/g' docs/user/04-00-istio-custom-resource.md
+	sed -i'' -e '1N;$$!N;/\n.*ReasonWithMessage/!P;D' docs/user/04-00-istio-custom-resource.md
+	sed -i'' -e '/ReasonWithMessage/d' docs/user/04-00-istio-custom-resource.md
+	rm -f docs/user/04-00-istio-custom-resource.md-e

api/v1alpha2/authorizers.go

@@ -4,30 +4,30 @@ 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.
+	// +kubebuilder:validation:Optional
 	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 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 +36,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 doesn't 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 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/experimental.go

@@ -1,6 +1,9 @@
 package v1alpha2
 
+// Defines experimental features.
 type Experimental struct {
+	// Defines experimental features for Istio Pilot.
+	// +kubebuilder:validation:Optional
 	PilotFeatures `json:"pilot"`
 
 	// Enables dual-stack support.
@@ -11,7 +14,12 @@ type Experimental struct {
 	EnableAmbient *bool `json:"enableAmbient,omitempty"`
 }
 
+// Defines experimental features for Istio Pilot.
 type PilotFeatures struct {
+	// Defines alpha Gateway API support.
+	// +kubebuilder:validation:Optional
 	EnableAlphaGatewayAPI                bool `json:"enableAlphaGatewayAPI"`
+	// Enables multi-network discovery for Gateway API.
+	// +kubebuilder:validation:Optional
 	EnableMultiNetworkDiscoverGatewayAPI bool `json:"enableMultiNetworkDiscoverGatewayAPI"`
 }