Adding SectionName to PolicyTargetReference

apis/v1alpha2/policy_types.go

@@ -38,6 +38,19 @@ type PolicyTargetReference struct {
 	//
 	// +optional
 	Namespace *Namespace `json:"namespace,omitempty"`
+
+	// 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:
+	// * Gateway: Listener 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
+	// a `ResolvedRefs` or similar Condition in the Policy's status.
+	//
+	// +optional
+	SectionName *SectionName `json:"sectionName,omitempty"`
 }
 
 // PolicyConditionType is a type of condition for a policy. This type should be

geps/gep-713.md

@@ -1244,91 +1244,35 @@ level. The implementations that support this policy attachment model will have
 the same behavior and semantics, although they may not be able to support
 attachment of all types of policy at all potential attachment points.
 
-### Apply Policies to Sections of a Resource (Future Extension)
-Although initially out of scope, it would be helpful to be able to target
-specific matches within nested objects. For example, it may be useful to attach
-policies to a specific Gateway listener or Route rule. This section explores
-what that could look like.
-
-Each Route rule or Gateway listener should be expanded with an optional name
-field. The target ref would be expanded with an optional sectionName field that
-could be used to refer to that specific section of the resource. It would refer
-to the following concepts on these resources:
-
-* Gateway.Listeners.Name
-* xRoute.Rules.Name
-* Service.Ports.Name
+### Apply Policies to Sections of a Resource
+Policies can target specific matches within nested objects. For instance, rather than
+applying a policy to the entire Gateway, we may want to attach it to a particular Gateway listener.
+
+To achieve this, an optional `sectionName` field can be set in the `targetRef` of a policy
+to refer to a specific listener within the target Gateway.
 
 ```yaml
-apiVersion: gateway.networking.k8s.io/v1alpha2
-kind: HTTPRoute
-metadata:
-  name: http-app-1
-  labels:
-    app: foo
-spec:
-  hostnames:
-  - "foo.com"
-  rules:
-  - name: bar
-    matches:
-    - path:
-        type: Prefix
-        value: /bar
-    forwardTo:
-    - serviceName: my-service1
-      port: 8080
----
 apiVersion: networking.acme.io/v1alpha2
-kind: RetryPolicy
+kind: AuthenticationPolicy
 metadata:
   name: foo
 spec:
-  maxRetries: 5
+  provider:
+    issuer: "https://accounts.google.com"
   targetRef:
     name: foo
     group: gateway.networking.k8s.io
-    kind: HTTPRoute
+    kind: Gateway
     sectionName: bar
 ```
 
-This would require adding a `SectionName` field to the PolicyTargetReference:
-```go
-type PolicyTargetReference struct {
-    // SectionName is the name of a section within the target resource. When
-    // unspecified, this targets the entire resource. In the following
-    // resources, SectionName is interpreted as the following:
-    // * Gateway: Listener Name
-    // * Route: Rule Name
-    // * Service: Port Name
-    //
-    // +kubebuilder:validation:MinLength=1
-    // +kubebuilder:validation:MaxLength=253
-    // +optional
-    SectionName string `json:"sectionName,omitempty"`
-    // ...
-}
-```
-
-This would also require adding a `Name` field to Gateway listeners and Route
-rules:
+The `sectionName` field can also be used to target a specific section of other resources, for example:
 
-```go
-type Listener struct {
-    // Name is the name of the Listener. If more than one Listener is present
-    // each Listener MUST specify a name. The names of Listeners MUST be unique
-    // within a Gateway.
-    //
-    // Support: Core
-    //
-    // +kubebuilder:validation:MinLength=1
-    // +kubebuilder:validation:MaxLength=253
-    // +optional
-    Name string `json:"name,omitempty"`
-    // ...
-}
-```
+* Service.Ports.Name
+* xRoute.Rules.Name
 
+This would require adding a `Name` field to those sub-resources that currently lack a name. For example,
+a `Name` field could be added to the `RouteRule` object:
 ```go
 type RouteRule struct {
     // Name is the name of the Route rule. If more than one Route Rule is
@@ -1345,6 +1289,9 @@ type RouteRule struct {
 }
 ```
 
+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 a `resolvedRefs` or similar Condition in the Policy's status.
+
 ### Advantages
 * Incredibly flexible approach that should work well for both ingress and mesh
 * Conceptually similar to existing ServicePolicy proposal and BackendPolicy