Defaults & Overrides

[guicassolato]

Extend the Kuadrant Policy APIs so we support use cases of Defaults & Overrides (D/O) for Inherited Policies, including the following base use cases:

• Defaults: policies set at a lower level in the hierarchy supersede ones set (as "defaults") at a higher level, or "more specific beats less specific"
• Overrides: policies set at a higher level in the hierarchy supersede ones set at the lower levels, or "less specific beats more specific"

As well as the following derivative cases:

• Merged defaults: default policy rules that are merged into the more specific policies (as opposed to an atomic less specific set of rules that is activated only when another more specific one is absent)
• Merged overrides: override policy rules that are merged into the more specific policies (as opposed to an atomic less specific set of rules that is activated fully replacing another more specific one that is present)
• Constraints: specialization of an override that rather than declaring concrete values, specify constraints for values – typically numeric values and regular patterns (e.g. limited sets) – declared at the lower levels, that is used to "clip" the requested specific values within the boundaries dictated by the constraint, in an override fashion – e.g.: min value, max value, in operator.
• Deactivation: specialization that completes a merge default use case by allowing lower level policies to disable ("deactivate") individual defaults set a higher level (as opposed to superseding those defaults with actual more specific policy rules with meaning)

Out of scope:

• Requirements: high level policies that declare requirements to be fulfilled by more specific (lower level) policies without specifying concrete default or override values or constraints. E.g.: "an authentication policy must be enforced, but none is provided by default."

Affected APIs:

• AuthPolicy
• RateLimitPolicy

Non-affected APIs, while these are considered Direct Policies, i.e. with no hierarchical effect:

• DNSPolicy
• TLSPolicy

Implementation steps

Tier 0: Specification and WIP to close first

(priority: 0)

• [x] https://github.com/Kuadrant/architecture/pull/58
• [x] https://github.com/Kuadrant/kuadrant-operator/pull/447
• [x] https://github.com/Kuadrant/kuadrant-operator/pull/396

Tier 1

(priority: 1)

• Full ("atomic") defaults
  • [x] #455
  • [x] #462
• Full ("atomic") overrides
  • [x] #463
  • [x] #464
• Policy status
  • [x] #465
  • [x] #466
• Policy discoverability (PolicyAffected condition on the target objects)
  • [x] #467
  • [x] #468
• Policy class CRD label
  • [x] #469
  • [x] #470
  • [x] #471
  • [x] #472
• Docs
  • [x] #575
  • [x] #547

Tier 2

(priority: 2)

• [ ] Support for multiple routes with same host name
• D/O conditions (enables support for "constraints")
  • [ ] #473
  • [ ] #474
• Merge strategy
  • [ ] #475
  • [ ] #476
• Effective policy reporting (options: status blocks, new CRD, HTTP endpoint)
  • [ ] #486
  • [ ] #477
  • [ ] #478

Tier 3

(priority: 3)

• Unsetting defaults
  • [ ] #479
  • [ ] #480
• [ ] #481
• [ ] #482

Enhancements & refactoring

(priority: 4)

• [x] #483

Unresolved questions & Future possibilities

(priority: 5)

• Multiple policies with the same target (N:1 policy-target relationship)
  • [ ] Allow multiple RateLimitPolicies to target the same object
  • [ ] Allow multiple AuthPolicies to target the same object
• Depending on https://github.com/kubernetes-sigs/gateway-api/pull/2593
  • [ ] Add sectionName to the RateLimitPolicy API
  • [ ] Add sectionName to the AuthPolicy API
• Change maps of rules to lists
  • [ ] Change RateLimitPolicies to listMapType
  • [ ] Change AuthPolicies to listMapType
• Change the spec of the inherited policies to match the xRoute spec
  • [ ] #484
  • [ ] Change the spec of RateLimitPolicy to match the xRoute spec
  • [ ] Change the spec of AuthPolicy to match the xRoute spec
• Merging policies with references to external objects
  • [ ] #485

Tests

• [ ] https://github.com/Kuadrant/testsuite/issues/369
• [ ] #529

[KevFan]

Implementation steps looks good to me to cover the RFC suggestions 👍

I've updated the PR link for RateLimit WasmPlugin Controller as the intial PR has now been superseded by https://github.com/Kuadrant/kuadrant-operator/pull/447

[guicassolato]

About using maps vs listMapType and the effects on merging into spec fields, to leave no doubts, @youngnick has added an excellent example to https://github.com/kubernetes-sigs/gateway-api/pull/2813.

cc @maleck13