Skip to content

Commit

Permalink
Clarify the difference between Direct and Hierarchical policies
Browse files Browse the repository at this point in the history
Signed-off-by: Nick Young <nick@isovalent.com>
  • Loading branch information
youngnick committed Mar 13, 2023
1 parent 3bf3456 commit 53f18f3
Showing 1 changed file with 20 additions and 7 deletions.
27 changes: 20 additions & 7 deletions site-src/references/policy-attachment.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,19 @@ Individual policy APIs must
- can be included in the Gateway API API group and installation or be defined by
implementations
- and must include a common `TargetRef` struct in their specification to identify
how and where to apply that policy, along with a field that indicates if
the reference is `Direct` or `Hierarchical`. (Shorter name suggestions welcomed)
how and where to apply that policy.
- Hierarchical policies must include one of:
- a `defaults` stanza indicating which settings should flow across a hierarchy
and be defaulted
- an `overrides` stanza indicating which settings should flow across a hierarchy
and be overridden.

If a policy CRD has a `targetRef` stanza, but _does not_ have either a
`defaults` stanza, `overrides` stanza, or both, then it is a Direct Attachment Policy.

If a policy CRD has a `targetRef` stanza, and _does_ have either a `defaults` stanza,
an `overrides` stanza, or both, then it is a Hierarchical Attachment Policy, and
its settings will flow over multiple objects.

For Hierarchical Policies, this document also describes a set of expected behaviors
for how settings can flow across a defined hierarchy.
Expand Down Expand Up @@ -178,7 +189,6 @@ spec:
includeProtocol: true
includeQueryString: true
targetRef:
type: hiearchical
kind: Gateway
name: example
---
Expand Down Expand Up @@ -224,23 +234,26 @@ kind: RetryPolicy
metadata:
name: foo
spec:
default:
maxRetries: 5
maxRetries: 5
targetRef:
type: direct
group: networking.example.net
kind: ExternalService
name: foo.com
```

Because this CRD does _not_ have a `defaults` or `overrides` section, it is
a Direct Attached Policy.

### Conflict Resolution
It is possible for multiple policies to target the same resource. When this
happens, merging is the preferred outcome. If multiple policy resources target
the same resource _and_ have an identical field specified with different values,
precedence MUST be determined in order of the following criteria, continuing on
ties:

* Hierarchical Policies override Direct Policies.
* Direct Policies override Hierarchical Policies. If preventing settings from
being overwritten is important, implementations should only use Hierarchical
Policies, and the `override` stanza that implies.
* The oldest Policy based on creation timestamp. For example, a Policy with a
creation timestamp of "2021-07-15 01:02:03" is given precedence over a Policy
with a creation timestamp of "2021-07-15 01:02:04".
Expand Down

0 comments on commit 53f18f3

Please sign in to comment.