From ff170b0f6a45a28b3f832bce2208386c1ce56f11 Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Mon, 8 Apr 2024 15:25:13 -0400 Subject: [PATCH] improve SectionName examples and documentation for well-known resources (#2946) * apis: improve SectionName examples and documentation for well-known resources * remove trailing period * add docs for HTTPRoute section name --------- Co-authored-by: Mike Morris <1149913+mikemorris@users.noreply.github.com> --- apis/v1/shared_types.go | 17 ++++++++++++++--- apis/v1alpha2/policy_types.go | 5 +++-- apis/v1alpha2/shared_types.go | 11 +++++++++++ apis/v1beta1/shared_types.go | 13 ++++++++++++- ...ay.networking.k8s.io_backendtlspolicies.yaml | 9 +++++---- .../gateway.networking.k8s.io_grpcroutes.yaml | 8 ++++---- .../gateway.networking.k8s.io_httproutes.yaml | 16 ++++++++-------- .../gateway.networking.k8s.io_tcproutes.yaml | 8 ++++---- .../gateway.networking.k8s.io_tlsroutes.yaml | 8 ++++---- .../gateway.networking.k8s.io_udproutes.yaml | 8 ++++---- .../gateway.networking.k8s.io_httproutes.yaml | 16 ++++++++-------- pkg/generated/openapi/zz_generated.openapi.go | 4 ++-- 12 files changed, 79 insertions(+), 44 deletions(-) diff --git a/apis/v1/shared_types.go b/apis/v1/shared_types.go index cc0133ac25..bb40b8880f 100644 --- a/apis/v1/shared_types.go +++ b/apis/v1/shared_types.go @@ -91,10 +91,10 @@ type ParentReference struct { // SectionName is the name of a section within the target resource. In the // following resources, SectionName is interpreted as the following: // - // * Gateway: Listener Name. When both Port (experimental) and SectionName + // * Gateway: Listener name. When both Port (experimental) and SectionName // are specified, the name and port of the selected listener must match // both specified values. - // * Service: Port Name. When both Port (experimental) and SectionName + // * Service: Port name. When both Port (experimental) and SectionName // are specified, the name and port of the selected listener must match // both specified values. // @@ -572,7 +572,7 @@ type Group string type Kind string // ObjectName refers to the name of a Kubernetes object. -// Object names can have a variety of forms, including RFC1123 subdomains, +// Object names can have a variety of forms, including RFC 1123 subdomains, // RFC 1123 labels, or RFC 1035 labels. // // +kubebuilder:validation:MinLength=1 @@ -602,11 +602,22 @@ type Namespace string // SectionName is the name of a section in a Kubernetes resource. // +// In the following resources, SectionName is interpreted as the following: +// +// * Gateway: Listener name +// * HTTPRoute: HTTPRouteRule name +// * Service: Port name +// +// Section names can have a variety of forms, including RFC 1123 subdomains, +// RFC 1123 labels, or RFC 1035 labels. +// // This validation is based off of the corresponding Kubernetes validation: // https://github.com/kubernetes/apimachinery/blob/02cfb53916346d085a6c6c7c66f882e3c6b0eca6/pkg/util/validation/validation.go#L208 // // Valid values include: // +// * "example" +// * "foo-example" // * "example.com" // * "foo.example.com" // diff --git a/apis/v1alpha2/policy_types.go b/apis/v1alpha2/policy_types.go index 092e743e6a..af13314860 100644 --- a/apis/v1alpha2/policy_types.go +++ b/apis/v1alpha2/policy_types.go @@ -71,8 +71,9 @@ type PolicyTargetReferenceWithSectionName struct { // unspecified, this targetRef targets the entire resource. In the following // resources, SectionName is interpreted as the following: // - // * Gateway: Listener Name - // * Service: Port Name + // * Gateway: Listener name + // * HTTPRoute: HTTPRouteRule name + // * Service: Port name // // If a SectionName is specified, but does not exist on the targeted object, // the Policy must fail to attach, and the policy implementation should record diff --git a/apis/v1alpha2/shared_types.go b/apis/v1alpha2/shared_types.go index 4ff14aace6..a2e484ae4f 100644 --- a/apis/v1alpha2/shared_types.go +++ b/apis/v1alpha2/shared_types.go @@ -253,11 +253,22 @@ type Namespace = v1.Namespace // SectionName is the name of a section in a Kubernetes resource. // +// In the following resources, SectionName is interpreted as the following: +// +// * Gateway: Listener name +// * HTTPRoute: HTTPRouteRule name +// * Service: Port name +// +// Section names can have a variety of forms, including RFC 1123 subdomains, +// RFC 1123 labels, or RFC 1035 labels. +// // This validation is based off of the corresponding Kubernetes validation: // https://github.com/kubernetes/apimachinery/blob/02cfb53916346d085a6c6c7c66f882e3c6b0eca6/pkg/util/validation/validation.go#L208 // // Valid values include: // +// * "example" +// * "foo-example" // * "example.com" // * "foo.example.com" // diff --git a/apis/v1beta1/shared_types.go b/apis/v1beta1/shared_types.go index 7b60f3dd76..2dfbb9264a 100644 --- a/apis/v1beta1/shared_types.go +++ b/apis/v1beta1/shared_types.go @@ -223,7 +223,7 @@ type Group = v1.Group type Kind = v1.Kind // ObjectName refers to the name of a Kubernetes object. -// Object names can have a variety of forms, including RFC1123 subdomains, +// Object names can have a variety of forms, including RFC 1123 subdomains, // RFC 1123 labels, or RFC 1035 labels. // // +kubebuilder:validation:MinLength=1 @@ -253,11 +253,22 @@ type Namespace = v1.Namespace // SectionName is the name of a section in a Kubernetes resource. // +// In the following resources, SectionName is interpreted as the following: +// +// * Gateway: Listener name +// * HTTPRoute: HTTPRouteRule name +// * Service: Port name +// +// Section names can have a variety of forms, including RFC 1123 subdomains, +// RFC 1123 labels, or RFC 1035 labels. +// // This validation is based off of the corresponding Kubernetes validation: // https://github.com/kubernetes/apimachinery/blob/02cfb53916346d085a6c6c7c66f882e3c6b0eca6/pkg/util/validation/validation.go#L208 // // Valid values include: // +// * "example" +// * "foo-example" // * "example.com" // * "foo.example.com" // diff --git a/config/crd/experimental/gateway.networking.k8s.io_backendtlspolicies.yaml b/config/crd/experimental/gateway.networking.k8s.io_backendtlspolicies.yaml index 348ddf4d87..543a826a21 100644 --- a/config/crd/experimental/gateway.networking.k8s.io_backendtlspolicies.yaml +++ b/config/crd/experimental/gateway.networking.k8s.io_backendtlspolicies.yaml @@ -101,8 +101,9 @@ spec: resources, SectionName is interpreted as the following: - * Gateway: Listener Name - * Service: Port Name + * Gateway: Listener name + * HTTPRoute: HTTPRouteRule name + * Service: Port name If a SectionName is specified, but does not exist on the targeted object, @@ -437,10 +438,10 @@ spec: following resources, SectionName is interpreted as the following: - * Gateway: Listener Name. When both Port (experimental) and SectionName + * Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. - * Service: Port Name. When both Port (experimental) and SectionName + * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. diff --git a/config/crd/experimental/gateway.networking.k8s.io_grpcroutes.yaml b/config/crd/experimental/gateway.networking.k8s.io_grpcroutes.yaml index 9aaa27ecdc..68b11c64ed 100644 --- a/config/crd/experimental/gateway.networking.k8s.io_grpcroutes.yaml +++ b/config/crd/experimental/gateway.networking.k8s.io_grpcroutes.yaml @@ -384,10 +384,10 @@ spec: following resources, SectionName is interpreted as the following: - * Gateway: Listener Name. When both Port (experimental) and SectionName + * Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. - * Service: Port Name. When both Port (experimental) and SectionName + * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. @@ -2204,10 +2204,10 @@ spec: following resources, SectionName is interpreted as the following: - * Gateway: Listener Name. When both Port (experimental) and SectionName + * Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. - * Service: Port Name. When both Port (experimental) and SectionName + * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. diff --git a/config/crd/experimental/gateway.networking.k8s.io_httproutes.yaml b/config/crd/experimental/gateway.networking.k8s.io_httproutes.yaml index f46ec7b1d1..105e7c1d4b 100644 --- a/config/crd/experimental/gateway.networking.k8s.io_httproutes.yaml +++ b/config/crd/experimental/gateway.networking.k8s.io_httproutes.yaml @@ -362,10 +362,10 @@ spec: following resources, SectionName is interpreted as the following: - * Gateway: Listener Name. When both Port (experimental) and SectionName + * Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. - * Service: Port Name. When both Port (experimental) and SectionName + * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. @@ -3084,10 +3084,10 @@ spec: following resources, SectionName is interpreted as the following: - * Gateway: Listener Name. When both Port (experimental) and SectionName + * Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. - * Service: Port Name. When both Port (experimental) and SectionName + * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. @@ -3475,10 +3475,10 @@ spec: following resources, SectionName is interpreted as the following: - * Gateway: Listener Name. When both Port (experimental) and SectionName + * Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. - * Service: Port Name. When both Port (experimental) and SectionName + * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. @@ -6197,10 +6197,10 @@ spec: following resources, SectionName is interpreted as the following: - * Gateway: Listener Name. When both Port (experimental) and SectionName + * Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. - * Service: Port Name. When both Port (experimental) and SectionName + * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. diff --git a/config/crd/experimental/gateway.networking.k8s.io_tcproutes.yaml b/config/crd/experimental/gateway.networking.k8s.io_tcproutes.yaml index fb68022061..1b7b23b73e 100644 --- a/config/crd/experimental/gateway.networking.k8s.io_tcproutes.yaml +++ b/config/crd/experimental/gateway.networking.k8s.io_tcproutes.yaml @@ -267,10 +267,10 @@ spec: following resources, SectionName is interpreted as the following: - * Gateway: Listener Name. When both Port (experimental) and SectionName + * Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. - * Service: Port Name. When both Port (experimental) and SectionName + * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. @@ -766,10 +766,10 @@ spec: following resources, SectionName is interpreted as the following: - * Gateway: Listener Name. When both Port (experimental) and SectionName + * Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. - * Service: Port Name. When both Port (experimental) and SectionName + * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. diff --git a/config/crd/experimental/gateway.networking.k8s.io_tlsroutes.yaml b/config/crd/experimental/gateway.networking.k8s.io_tlsroutes.yaml index 72e6a59196..1c2fc67604 100644 --- a/config/crd/experimental/gateway.networking.k8s.io_tlsroutes.yaml +++ b/config/crd/experimental/gateway.networking.k8s.io_tlsroutes.yaml @@ -337,10 +337,10 @@ spec: following resources, SectionName is interpreted as the following: - * Gateway: Listener Name. When both Port (experimental) and SectionName + * Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. - * Service: Port Name. When both Port (experimental) and SectionName + * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. @@ -839,10 +839,10 @@ spec: following resources, SectionName is interpreted as the following: - * Gateway: Listener Name. When both Port (experimental) and SectionName + * Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. - * Service: Port Name. When both Port (experimental) and SectionName + * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. diff --git a/config/crd/experimental/gateway.networking.k8s.io_udproutes.yaml b/config/crd/experimental/gateway.networking.k8s.io_udproutes.yaml index eaf7712e69..6a5acffa8b 100644 --- a/config/crd/experimental/gateway.networking.k8s.io_udproutes.yaml +++ b/config/crd/experimental/gateway.networking.k8s.io_udproutes.yaml @@ -267,10 +267,10 @@ spec: following resources, SectionName is interpreted as the following: - * Gateway: Listener Name. When both Port (experimental) and SectionName + * Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. - * Service: Port Name. When both Port (experimental) and SectionName + * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. @@ -766,10 +766,10 @@ spec: following resources, SectionName is interpreted as the following: - * Gateway: Listener Name. When both Port (experimental) and SectionName + * Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. - * Service: Port Name. When both Port (experimental) and SectionName + * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. diff --git a/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml b/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml index 9c8a867e38..012cf20b20 100644 --- a/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml +++ b/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml @@ -336,10 +336,10 @@ spec: following resources, SectionName is interpreted as the following: - * Gateway: Listener Name. When both Port (experimental) and SectionName + * Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. - * Service: Port Name. When both Port (experimental) and SectionName + * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. @@ -2981,10 +2981,10 @@ spec: following resources, SectionName is interpreted as the following: - * Gateway: Listener Name. When both Port (experimental) and SectionName + * Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. - * Service: Port Name. When both Port (experimental) and SectionName + * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. @@ -3346,10 +3346,10 @@ spec: following resources, SectionName is interpreted as the following: - * Gateway: Listener Name. When both Port (experimental) and SectionName + * Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. - * Service: Port Name. When both Port (experimental) and SectionName + * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. @@ -5991,10 +5991,10 @@ spec: following resources, SectionName is interpreted as the following: - * Gateway: Listener Name. When both Port (experimental) and SectionName + * Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. - * Service: Port Name. When both Port (experimental) and SectionName + * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. diff --git a/pkg/generated/openapi/zz_generated.openapi.go b/pkg/generated/openapi/zz_generated.openapi.go index e6039df231..3ebedc8e13 100644 --- a/pkg/generated/openapi/zz_generated.openapi.go +++ b/pkg/generated/openapi/zz_generated.openapi.go @@ -4481,7 +4481,7 @@ func schema_sigsk8sio_gateway_api_apis_v1_ParentReference(ref common.ReferenceCa }, "sectionName": { SchemaProps: spec.SchemaProps{ - Description: "SectionName is the name of a section within the target resource. In the following resources, SectionName is interpreted as the following:\n\n* Gateway: Listener Name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. * Service: Port Name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values.\n\nImplementations MAY choose to support attaching Routes to other resources. If that is the case, they MUST clearly document how SectionName is interpreted.\n\nWhen unspecified (empty string), this will reference the entire resource. For the purpose of status, an attachment is considered successful if at least one section in the parent resource accepts it. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway.\n\nSupport: Core", + Description: "SectionName is the name of a section within the target resource. In the following resources, SectionName is interpreted as the following:\n\n* Gateway: Listener name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values. * Service: Port name. When both Port (experimental) and SectionName are specified, the name and port of the selected listener must match both specified values.\n\nImplementations MAY choose to support attaching Routes to other resources. If that is the case, they MUST clearly document how SectionName is interpreted.\n\nWhen unspecified (empty string), this will reference the entire resource. For the purpose of status, an attachment is considered successful if at least one section in the parent resource accepts it. For example, Gateway listeners can restrict which Routes can attach to them by Route kind, namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from the referencing Route, the Route MUST be considered successfully attached. If no Gateway listeners accept attachment from this Route, the Route MUST be considered detached from the Gateway.\n\nSupport: Core", Type: []string{"string"}, Format: "", }, @@ -5800,7 +5800,7 @@ func schema_sigsk8sio_gateway_api_apis_v1alpha2_PolicyTargetReferenceWithSection }, "sectionName": { SchemaProps: spec.SchemaProps{ - Description: "SectionName is the name of a section within the target resource. When unspecified, this targetRef targets the entire resource. In the following resources, SectionName is interpreted as the following:\n\n* Gateway: Listener Name * Service: Port Name\n\nIf a SectionName is specified, but does not exist on the targeted object, the Policy must fail to attach, and the policy implementation should record a `ResolvedRefs` or similar Condition in the Policy's status.", + Description: "SectionName is the name of a section within the target resource. When unspecified, this targetRef targets the entire resource. In the following resources, SectionName is interpreted as the following:\n\n* Gateway: Listener name * HTTPRoute: HTTPRouteRule name * Service: Port name\n\nIf a SectionName is specified, but does not exist on the targeted object, the Policy must fail to attach, and the policy implementation should record a `ResolvedRefs` or similar Condition in the Policy's status.", Type: []string{"string"}, Format: "", },