improve SectionName examples and documentation for well-known resourc…

…es (#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 <[email protected]>

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"
 //

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

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"
 //

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"
 //