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)

• Defaults & Overrides (RFC 0009) architecture#58
• Rate limiting wasmplugin controller: using GatewayAPI topology (DAG) #447
• refactor: api machinary  #396

Tier 1

(priority: 1)

• Full ("atomic") defaults
  • Add the default field to the RateLimitPolicy API #455
  • Add the default field to the AuthPolicy API #462
• Full ("atomic") overrides
  • Add full overrides to the RateLimitPolicy API #463
  • Add full overrides to the AuthPolicy API #464
• Policy status
  • RateLimitPolicy status for D/O #465
  • AuthPolicy status for D/O #466
• Policy discoverability (PolicyAffected condition on the target objects)
  • RateLimitPolicy discoverability #467
  • AuthPolicy discoverability #468
• Policy class CRD label
  • Tag RateLimitPolicy CRD as inherited policy attachment class #469
  • Tag AuthPolicy CRD as inherited policy attachment class #470
  • Tag DNSPolicy CRD as direct policy attachment class #471
  • Tag TLSPolicy CRD as direct policy attachment class #472
• Docs
  • docs: defaults & overrides #575
  • Document limitations on multiple routes with identical host name #547

Tier 2

(priority: 2)

• Support for multiple routes with same host name
• D/O conditions (enables support for "constraints")
  • Add support for D/O when conditions in the RateLimitPolicy API #473
  • Add support for D/O when conditions in the AuthPolicy API #474
• Merge strategy
  • D/O merge strategy for RateLimitPolicies #475
  • D/O merge strategy for AuthPolicies #476
• Effective policy reporting (options: status blocks, new CRD, HTTP endpoint)
  • Investigate options for Effective policy #486
  • RateLimitPolicy effective policy #477
  • AuthPolicy effective policy #478

Tier 3

(priority: 3)

• Unsetting defaults
  • Add support for unsetting defaults in the RateLimitPolicy API #479
  • Add support for unsetting defaults in the AuthPolicy API #480
• Control-plane metrics for D/O #481
• Document possible approaches for "requirements" #482

Enhancements & refactoring

(priority: 4)

• Extract generic part of D/O implementation to Kuadrant/gateway-api-machinery #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 Adding GEP-995 for support for named route rules kubernetes-sigs/gateway-api#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
  • Investigate compatibility for changing the spec of the policies to match the spec of the route #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
  • Investigate options for handling references to objects across namespaces in merged policies #485

Tests

• Defaults & Overrides testsuite#369
• Resources for testing complex topology scenarios #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 #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 kubernetes-sigs/gateway-api#2813.

cc @maleck13