Skip to content

Commit 386e9ec

Browse files
zhaohuabingzhaohuabing
authored
Adding SectionName to PolicyTargetReference (#2283)
* add SectionName to PolicyTargetReference Signed-off-by: huabing zhao <[email protected]> * modify gep 713 to accout for the chage Signed-off-by: huabing zhao <[email protected]> * modify gep 713 to accout for the chage Signed-off-by: huabing zhao <[email protected]> * remove route rule name since it doesn't exist yet Signed-off-by: huabing zhao <[email protected]> * address comments Signed-off-by: huabing zhao <[email protected]> * address comments Signed-off-by: huabing zhao <[email protected]> * Add a DirectPolicyTargetReference for Direct Policy Attachment Signed-off-by: huabing zhao <[email protected]> * add HTTPRoute example Signed-off-by: huabing zhao <[email protected]> * add HTTPRoute and Gateway example Signed-off-by: huabing zhao <[email protected]> * address comments Signed-off-by: huabing zhao <[email protected]> * address comments Signed-off-by: huabing zhao <[email protected]> * fix test Signed-off-by: huabing zhao <[email protected]> * address comments Signed-off-by: huabing zhao <[email protected]> * rename to PolicyTargetReferenceWithSectionName Signed-off-by: huabing zhao <[email protected]> --------- Signed-off-by: huabing zhao <[email protected]>
1 parent 0089b6e commit 386e9ec

File tree

3 files changed

+103
-55
lines changed

3 files changed

+103
-55
lines changed

‎apis/v1alpha2/policy_types.go‎

Lines changed: 32 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,11 @@ limitations under the License.
1616

1717
package v1alpha2
1818

19-
// PolicyTargetReference identifies an API object to apply policy to. This
20-
// should be used as part of Policy resources that can target Gateway API
21-
// resources. For more information on how this policy attachment model works,
22-
// and a sample Policy resource, refer to the policy attachment documentation
23-
// for Gateway API.
19+
// PolicyTargetReference identifies an API object to apply a direct or
20+
// inherited policy to. This should be used as part of Policy resources
21+
// that can target Gateway API resources. For more information on how this
22+
// policy attachment model works, and a sample Policy resource, refer to
23+
// the policy attachment documentation for Gateway API.
2424
type PolicyTargetReference struct {
2525
// Group is the group of the target resource.
2626
Group Group `json:"group"`
@@ -40,6 +40,33 @@ type PolicyTargetReference struct {
4040
Namespace *Namespace `json:"namespace,omitempty"`
4141
}
4242

43+
// PolicyTargetReferenceWithSectionName identifies an API object to apply a direct
44+
// policy to. This should be used as part of Policy resources that can target
45+
// single resources. For more information on how this policy attachment mode
46+
// works, and a sample Policy resource, refer to the policy attachment documentation
47+
// for Gateway API.
48+
//
49+
// Note: This should only be used for direct policy attachment when references
50+
// to SectionName are actually needed. In all other cases, PolicyTargetReference
51+
// should be used.
52+
type PolicyTargetReferenceWithSectionName struct {
53+
PolicyTargetReference `json:",inline"`
54+
55+
// SectionName is the name of a section within the target resource. When
56+
// unspecified, this targetRef targets the entire resource. In the following
57+
// resources, SectionName is interpreted as the following:
58+
//
59+
// * Gateway: Listener Name
60+
// * Service: Port Name
61+
//
62+
// If a SectionName is specified, but does not exist on the targeted object,
63+
// the Policy must fail to attach, and the policy implementation should record
64+
// a `ResolvedRefs` or similar Condition in the Policy's status.
65+
//
66+
// +optional
67+
SectionName *SectionName `json:"sectionName,omitempty"`
68+
}
69+
4370
// PolicyConditionType is a type of condition for a policy. This type should be
4471
// used with a Policy resource Status.Conditions field.
4572
type PolicyConditionType string

‎apis/v1alpha2/zz_generated.deepcopy.go‎

Lines changed: 21 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎geps/gep-713.md‎

Lines changed: 50 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1244,20 +1244,44 @@ level. The implementations that support this policy attachment model will have
12441244
the same behavior and semantics, although they may not be able to support
12451245
attachment of all types of policy at all potential attachment points.
12461246

1247-
### Apply Policies to Sections of a Resource (Future Extension)
1248-
Although initially out of scope, it would be helpful to be able to target
1249-
specific matches within nested objects. For example, it may be useful to attach
1250-
policies to a specific Gateway listener or Route rule. This section explores
1251-
what that could look like.
1252-
1253-
Each Route rule or Gateway listener should be expanded with an optional name
1254-
field. The target ref would be expanded with an optional sectionName field that
1255-
could be used to refer to that specific section of the resource. It would refer
1256-
to the following concepts on these resources:
1257-
1258-
* Gateway.Listeners.Name
1259-
* xRoute.Rules.Name
1247+
### Apply Policies to Sections of a Resource
1248+
Policies can target specific matches within nested objects. For instance, rather than
1249+
applying a policy to the entire Gateway, we may want to attach it to a particular Gateway listener.
1250+
1251+
To achieve this, an optional `sectionName` field can be set in the `targetRef` of a policy
1252+
to refer to a specific listener within the target Gateway.
1253+
1254+
```yaml
1255+
apiVersion: gateway.networking.k8s.io/v1beta1
1256+
kind: Gateway
1257+
metadata:
1258+
name: foo-gateway
1259+
spec:
1260+
gatewayClassName: foo-lb
1261+
listeners:
1262+
- name: bar
1263+
...
1264+
---
1265+
apiVersion: networking.acme.io/v1alpha2
1266+
kind: AuthenticationPolicy
1267+
metadata:
1268+
name: foo
1269+
spec:
1270+
provider:
1271+
issuer: "https://oidc.example.com"
1272+
targetRef:
1273+
name: foo-gateway
1274+
group: gateway.networking.k8s.io
1275+
kind: Gateway
1276+
sectionName: bar
1277+
```
1278+
1279+
The `sectionName` field can also be used to target a specific section of other resources:
1280+
12601281
* Service.Ports.Name
1282+
* xRoute.Rules.Name
1283+
1284+
For example, the RetryPolicy below applies to a RouteRule inside an HTTPRoute.
12611285

12621286
```yaml
12631287
apiVersion: gateway.networking.k8s.io/v1alpha2
@@ -1292,43 +1316,8 @@ spec:
12921316
sectionName: bar
12931317
```
12941318

1295-
This would require adding a `SectionName` field to the PolicyTargetReference:
1296-
```go
1297-
type PolicyTargetReference struct {
1298-
// SectionName is the name of a section within the target resource. When
1299-
// unspecified, this targets the entire resource. In the following
1300-
// resources, SectionName is interpreted as the following:
1301-
// * Gateway: Listener Name
1302-
// * Route: Rule Name
1303-
// * Service: Port Name
1304-
//
1305-
// +kubebuilder:validation:MinLength=1
1306-
// +kubebuilder:validation:MaxLength=253
1307-
// +optional
1308-
SectionName string `json:"sectionName,omitempty"`
1309-
// ...
1310-
}
1311-
```
1312-
1313-
This would also require adding a `Name` field to Gateway listeners and Route
1314-
rules:
1315-
1316-
```go
1317-
type Listener struct {
1318-
// Name is the name of the Listener. If more than one Listener is present
1319-
// each Listener MUST specify a name. The names of Listeners MUST be unique
1320-
// within a Gateway.
1321-
//
1322-
// Support: Core
1323-
//
1324-
// +kubebuilder:validation:MinLength=1
1325-
// +kubebuilder:validation:MaxLength=253
1326-
// +optional
1327-
Name string `json:"name,omitempty"`
1328-
// ...
1329-
}
1330-
```
1331-
1319+
This would require adding a `name` field to those sub-resources that currently lack a name. For example,
1320+
a `name` field could be added to the `RouteRule` object:
13321321
```go
13331322
type RouteRule struct {
13341323
// Name is the name of the Route rule. If more than one Route Rule is
@@ -1345,6 +1334,17 @@ type RouteRule struct {
13451334
}
13461335
```
13471336

1337+
If a `sectionName` is specified, but does not exist on the targeted object, the Policy must fail to attach,
1338+
and the policy implementation should record a `resolvedRefs` or similar Condition in the Policy's status.
1339+
1340+
When multiple Policies of the same type target the same object, one with a `sectionName` specified, and one without,
1341+
the one with a `sectionName` is more specific, and so will have all its settings apply. The less-specific Policy will
1342+
not attach to the target.
1343+
1344+
Note that the `sectionName` is currently intended to be used only for Direct Policy Attachment when references to
1345+
SectionName are actually needed. Inherited Policies are always applied to the entire object.
1346+
The `PolicyTargetReferenceWithSectionName` API can be used to apply a direct Policy to a section of an object.
1347+
13481348
### Advantages
13491349
* Incredibly flexible approach that should work well for both ingress and mesh
13501350
* Conceptually similar to existing ServicePolicy proposal and BackendPolicy

0 commit comments

Comments
 (0)