From 87b3e5b8e11fe0cb9a0fe14371de6473c1e8eb9e Mon Sep 17 00:00:00 2001 From: Nick Young Date: Wed, 29 Mar 2023 05:02:01 +0000 Subject: [PATCH] Change inherited policy example to a filter instead of field Signed-off-by: Nick Young --- site-src/references/policy-attachment.md | 67 ++++++++++++------------ 1 file changed, 34 insertions(+), 33 deletions(-) diff --git a/site-src/references/policy-attachment.md b/site-src/references/policy-attachment.md index 1e22846ef8..b3d1ce48d7 100644 --- a/site-src/references/policy-attachment.md +++ b/site-src/references/policy-attachment.md @@ -591,14 +591,14 @@ Only the Policy owner can change this Policy. ### Handling non-scalar values In this example, we will assume that at some future point, HTTPRoute has grown -fields to configure retries, including a field called `retryOn` that reflects -the HTTP status codes that should be retried. The _value_ of this field is a -list of strings, being the HTTP codes that must be retried. The `retryOn` field -has no defaults in the field definitions (which is probably a bad design, but we -need to show this interaction somehow!) +a Filter to configure retries (`RetryFilter`), including a field called `retryOn` +that reflects the HTTP status codes that should be retried. The _value_ of this +field is a list of strings, being the HTTP codes that must be retried. The `retryOn` +field has no defaults in the field definitions (which is probably a bad design, +but we need to show this interaction somehow!) We also assume that an Inherited `RetryOnPolicy` exists that allows both -defaulting and overriding of the `retryOn` field. +defaulting and overriding of the `retryOn` field in the `RetryFilter`. A full `RetryOnPolicy` to default the field to the codes `501`, `502`, and `503` would look like this: @@ -620,12 +620,12 @@ spec: name: we-love-retries ``` -This means that, for HTTPRoutes that do _NOT_ explicitly set this field to something +This means that, for HTTPRoutes that use the `RetryFilter and do _NOT_ explicitly set this field to something else, (in other words, they contain an empty list), then the field will be set to a list containing `501`, `502`, and `503`. (Notably, because of Go zero values, this would also occur if the user explicitly set the value to the empty list.) -However, if a HTTPRoute owner sets any value other than the empty list, then that +However, if a HTTPRoute owner sets any value other than the empty list in the filter, then that value will remain, and the Policy will have _no effect_. These values are _not_ merged. @@ -647,20 +647,20 @@ spec: name: you-must-retry ``` -Then no matter what the value is in the HTTPRoute, it will be set to `501`, `503` +Then no matter what the value is in the filter, it will be set to `501`, `503` by the Policy override. ### Interactions between defaults, overrides, and field values -All HTTPRoutes that attach to the `YouMustRetry` Gateway will have any value -_overwritten_ by this policy. The empty list, or any number of values, will all -be replaced with `501`, `502`, and `503`. +All HTTPRoutes that attach to the `YouMustRetry` Gateway and use a `RetryFilter` +will have any value _overwritten_ by this policy. The empty list, or any number +of values, will all be replaced with `501`, `502`, and `503`. Now, let's also assume that we use the Namespace -> Gateway hierarchy on top of the Gateway -> HTTPRoute hierarchy, and allow attaching a `RetryOnPolicy` to a _namespace_. The expectation here is that this will affect all Gateways in a namespace -and all HTTPRoutes that attach to those Gateways. (Note that the HTTPRoutes -themselves may not necessarily be in the same namespace though.) +and all HTTPRoutes that use the `RetryFilter` and attach to those Gateways. +(Note that the HTTPRoutes themselves may not necessarily be in the same namespace though.) If we apply the default policy from earlier to the namespace: ```yaml @@ -683,16 +683,17 @@ spec: Then this will have the same effect as applying that Policy to every Gateway in the `default` namespace - namely that every HTTPRoute that attaches to every -Gateway will have its `retryOn` field set to `501`, `502`, `503`, _if_ there is no -other setting in the HTTPRoute itself. +Gateway will have its `retryOn` field in the `RetryFilter` set to `501`, `502`, `503`, +_if_ there is no other setting in the `RetryFilter` itself. With two layers in the hierarchy, we have a more complicated set of interactions possible. Let's look at some tables for a particular HTTPRoute, assuming that it does _not_ -configure the `retryOn` field, for various types of Policy at different levels. +configure the `retryOn` field, but _does_ configure a `RetryFilter`, for various +types of Policy at different levels. -#### Overrides interacting with defaults for RetryOnPolicy, empty list in HTTPRoute +#### Overrides interacting with defaults for RetryOnPolicy, empty list in RetryFilter ||None|Namespace override|Gateway override|HTTPRoute override| |----|-----|-----|----|----| @@ -701,7 +702,7 @@ configure the `retryOn` field, for various types of Policy at different levels. |Gateway default| Gateway default | Namespace override | Gateway override | HTTPRoute override | |HTTPRoute default| HTTPRoute default | Namespace override | Gateway override | HTTPRoute override| -#### Overrides interacting with other overrides for RetryOnPolicy, empty list in HTTPRoute +#### Overrides interacting with other overrides for RetryOnPolicy, empty list in RetryFilter ||No override|Namespace override A|Gateway override A|HTTPRoute override A| |----|-----|-----|----|----| |No override|Empty list|Namespace override| Gateway override| HTTPRoute override| @@ -709,7 +710,7 @@ configure the `retryOn` field, for various types of Policy at different levels. |Gateway override B| Gateway override B | Namespace override A| Gateway override
first created wins
otherwise first alphabetically | Gateway override B| |HTTPRoute override B| HTTPRoute override B | Namespace override A| Gateway override A| HTTPRoute override
first created wins
otherwise first alphabetically| -#### Defaults interacting with other defaults for RetryOnPolicy, empty list in HTTPRoute +#### Defaults interacting with other defaults for RetryOnPolicy, empty list in RetryFilter ||No default|Namespace default A|Gateway default A|HTTPRoute default A| |----|-----|-----|----|----| |No default|Empty list|Namespace default| Gateway default| HTTPRoute default A| @@ -718,30 +719,30 @@ configure the `retryOn` field, for various types of Policy at different levels. |HTTPRoute default B| HTTPRoute default B| HTTPRoute default B| HTTPRoute default B| HTTPRoute default
first created wins
otherwise first alphabetically| -Now, if the HTTPRoute _does_ specify a RetryPolicy, +Now, if the HTTPRoute _does_ specify a value in its `RetryFilter`, it's a bit easier, because we can basically disregard all defaults: -#### Overrides interacting with defaults for RetryOnPolicy, value in HTTPRoute +#### Overrides interacting with defaults for RetryOnPolicy, value in RetryFilter ||None|Namespace override|Gateway override|HTTPRoute override| |----|-----|-----|----|----| -|No default| Value in HTTPRoute|Namespace override| Gateway override | HTTPRoute override| -|Namespace default| Value in HTTPRoute| Namespace override | Gateway override | HTTPRoute override | -|Gateway default| Value in HTTPRoute | Namespace override | Gateway override | HTTPRoute override | -|HTTPRoute default| Value in HTTPRoute | Namespace override | Gateway override | HTTPRoute override| +|No default| Value in RetryFilter|Namespace override| Gateway override | HTTPRoute override| +|Namespace default| Value in RetryFilter| Namespace override | Gateway override | HTTPRoute override | +|Gateway default| Value in RetryFilter | Namespace override | Gateway override | HTTPRoute override | +|HTTPRoute default| Value in RetryFilter | Namespace override | Gateway override | HTTPRoute override| -#### Overrides interacting with other overrides for RetryOnPolicy, value in HTTPRoute +#### Overrides interacting with other overrides for RetryOnPolicy, value in RetryFilter ||No override|Namespace override A|Gateway override A|HTTPRoute override A| |----|-----|-----|----|----| -|No override|Value in HTTPRoute|Namespace override A| Gateway override A| HTTPRoute override A| +|No override|Value in RetryFilter|Namespace override A| Gateway override A| HTTPRoute override A| |Namespace override B| Namespace override B| Namespace override
first created wins
otherwise first alphabetically | Namespace override B| Namespace override B| |Gateway override B| Gateway override B| Namespace override A| Gateway override
first created wins
otherwise first alphabetically | Gateway override B| |HTTPRoute override B| HTTPRoute override B | Namespace override A| Gateway override A| HTTPRoute override
first created wins
otherwise first alphabetically| -#### Defaults interacting with other defaults for RetryOnPolicy, value in HTTPRoute +#### Defaults interacting with other defaults for RetryOnPolicy, value in RetryFilter ||No default|Namespace default A|Gateway default A|HTTPRoute default A| |----|-----|-----|----|----| -|No default|Value in HTTPRoute|Value in HTTPRoute|Value in HTTPRoute|Value in HTTPRoute| -|Namespace default B|Value in HTTPRoute|Value in HTTPRoute|Value in HTTPRoute|Value in HTTPRoute| -|Gateway default B|Value in HTTPRoute|Value in HTTPRoute|Value in HTTPRoute|Value in HTTPRoute| -|HTTPRoute default B|Value in HTTPRoute|Value in HTTPRoute|Value in HTTPRoute|Value in HTTPRoute| +|No default|Value in RetryFilter|Value in RetryFilter|Value in RetryFilter|Value in RetryFilter| +|Namespace default B|Value in RetryFilter|Value in RetryFilter|Value in RetryFilter|Value in RetryFilter| +|Gateway default B|Value in RetryFilter|Value in RetryFilter|Value in RetryFilter|Value in RetryFilter| +|HTTPRoute default B|Value in RetryFilter|Value in RetryFilter|Value in RetryFilter|Value in RetryFilter|