Merge refs/heads/main into cors_on_direct_response

changelog/v1.15.0-beta18/docs-inheritance.yaml

@@ -0,0 +1,5 @@
+changelog:
+  - type: NON_USER_FACING
+    description: >- 
+      Adds concept docs for inheritance and links to existing examples. 
+      skipCI-kube-tests:true

docs/content/guides/traffic_management/request_processing/append_remove_headers/_index.md

@@ -201,4 +201,78 @@ spec:
 status: {}
 {{< /highlight >}}
 
+## Inheritance of request headers {#inheritance}
 
+Headers can be inherited by children options, such as shown in the following example with delegated routes. For more information about inheritance, see [Inheritance rules]({{% versioned_link_path fromRoot="/introduction/traffic_filter/" %}}). For more information about delegation, see [Delegating with route tables]({{% versioned_link_path fromRoot="/guides/traffic_management/destination_types/delegation/" %}}).
+
+1. In your Virtual Service, set up a delegated route.
+   ```yaml
+   apiVersion: gateway.solo.io/v1
+   kind: VirtualService
+   metadata:
+     name: 'example'
+     namespace: 'gloo-system'
+   spec:
+     virtualHost:
+       domains:
+       - 'example.com'
+       routes:
+       - matchers:
+          - prefix: '/a' # delegate ownership of routes for `example.com/a`
+         delegateAction:
+           ref:
+             name: 'a-routes'
+             namespace: 'a'
+       - matchers:
+          - prefix: '/b' # delegate ownership of routes for `example.com/b`
+         delegateAction:
+           ref:
+             name: 'b-routes'
+             namespace: 'b'
+   ```
+2. Add headers that you want all child objects to inherit in the VirtualHost parent object in the same VirtualService as the previous step. In the following example, the `x-gateway-start-time` header is added to requests, and the `x-route-table: alphabet` header is added to responses.
+   ```yaml
+   ...
+   virtualHost:
+     options:
+       headerManipulation:
+         requestHeadersToAdd:
+           - header:
+               key: x-gateway-start-time
+               value: '%START_TIME%'
+         responseHeadersToAdd:
+           - header:
+               key: x-route-table
+               value: alphabet
+   ```
+3. In the RouteTable child object, define other headers. In the following example, the `x-route-table` header is added to requests, and the `x-route-table: a` header is added to responses.
+   ```yaml
+   apiVersion: gateway.solo.io/v1
+   kind: RouteTable
+   metadata:
+     name: 'a-routes'
+     namespace: 'a'
+   spec:
+     routes:
+       - matchers:
+           # the path matchers in this RouteTable must begin with the prefix `/a/`
+          - prefix: '/a/1'
+         routeAction:
+           single:
+             upstream:
+               name: 'foo-upstream'
+     options:
+       headerManipulation:
+         requestHeadersToAdd:
+           - header:
+               key: x-route-table
+               value: a
+         responseHeadersToAdd:
+           - header:
+               key: x-route-table
+               value: a
+   ```
+4. Now, requests that match the route `/a/1` get the following headers:
+   * The `x-gateway-start-time` request header is inherited from the parent VirtualHost option.
+   * The `x-route-table` request header is set in the child Route option.
+   * The `x-route-table` response header in the child overwrites the parent object's value of `alphabet` instead to `a`, because child objects take precedence in case of conflict.

docs/content/guides/traffic_management/request_processing/transformations/_index.md

@@ -38,11 +38,11 @@ By default, a transformation defined on a Virtual Service attribute is **inherit
 - transformations defined on `VirtualHosts` are inherited by `Route`s and `WeightedDestination`s.
 - transformations defined on `Route`s are inherited by `WeightedDestination`s.
 
-If a child attribute defines its own transformation, it will override the configuration on its parent.
+If a child attribute defines its own transformation, it overrides the configuration on its parent.
 However, if `inheritTransformation` is set to true on the `stagedTransformations` for a Route, it can inherit transformations
 from its parent as illustrated below.
 
-Let's define the `virtualHost` and it's child route is defined as follows:
+Let's define the `virtualHost` and its child route is defined as follows:
 {{< highlight yaml "hl_lines=7-13 20-27" >}}
 # This snippet has been abridged for brevity, and only includes transformation-relevant config
 virtualHost:
@@ -72,8 +72,7 @@ virtualHost:
                       text: 'baz'
 {{< /highlight >}}
 
-Because `inheritTransformation` is set to `true` on the child route, the parent `virtualHost` transformation config will
-be merged into the child. The child route's transformations will look like:
+Because `inheritTransformation` is set to `true` on the child route, the parent `virtualHost` transformation config is merged into the child. The child route's transformations look like the following.
 
 {{< highlight yaml "hl_lines=8-22" >}}
 # This snippet has been abridged for brevity, and only includes transformation-relevant config
@@ -99,10 +98,9 @@ routes:
                 text: 'bar'
 {{< /highlight >}}
 
-As stated above, the route's configuration will override its parent's, but now it also inherits the parent's transformations. So in this case,
-routes matching `/parent` will also be transformed. If `inheritTransformation` was set to `false`, this would not be the case. 
-Note that only the first matched transformation will run, so if both the child and the parent had the same matchers, the child's transformation
-would run.
+As stated above, the route's configuration overrides its parent's, but now it also inherits the parent's transformations. So in this case,
+routes matching `/parent` are also transformed. If `inheritTransformation` were set to `false`, the matching `/parent` routes would not be transformed. 
+Note that only the first matched transformation runs, so if both the child and the parent had the same matchers, the child's transformation would run.
 
 ### Configuration format
 Learn more about the properties that you can set in the `stagedTransformations` {{< protobuf display="object" name="transformation.options.gloo.solo.io.TransformationStages" >}} section of your YAML file. 

docs/content/introduction/traffic_filter.md

@@ -55,7 +55,22 @@ More information about configuring the [timeout]({{% versioned_link_path fromRoo
 
 ### Traffic shadowing
 
-You can control the rollout of changes using canary releases or blue-green deployments with Upstream Groups. The downside to using either feature is that your are working with live traffic. Real clients are consuming the new version of your service, with potentially negative consequences. An alternative is to shadow the client traffic to your new release, while still processing the original request normally. [Traffic shadowing]({{% versioned_link_path fromRoot="/guides/traffic_management/request_processing/shadowing//" %}}) makes a copy of an incoming request and sends it out-of-band to the new version of your service, without altering the original request.
+You can control the rollout of changes using canary releases or blue-green deployments with Upstream Groups. The downside to using either feature is that your are working with live traffic. Real clients are consuming the new version of your service, with potentially negative consequences. An alternative is to shadow the client traffic to your new release, while still processing the original request normally. [Traffic shadowing]({{% versioned_link_path fromRoot="/guides/traffic_management/request_processing/shadowing/" %}}) makes a copy of an incoming request and sends it out-of-band to the new version of your service, without altering the original request.
+
+---
+
+## Inheritance rules
+
+In general, options that you set in a parent object are inherited by a child object. Then, the child has both its own options and those of its parent appended. If the option in the child and parent conflict, the child option takes precedence and overwrites the parent option. You can change this behavior by setting the `inheritTransformation` option to `false` in the children objects.
+
+Examples of parent and child objects:
+* VirtualHost parent object options append to children objects like Routes and WeightedDestinations
+* Route parent object options append to children objects like WeightedDestinations
+
+For examples of inherited options, see the following guides:
+* [Request processing transformation inheritance]({{% versioned_link_path fromRoot="/guides/traffic_management/request_processing/transformations/" %}})
+* [Header inheritance]({{% versioned_link_path fromRoot="/guides/traffic_management/request_processing/append_remove_headers/#inheritance" %}})
+* [Auth config inheritance]({{% versioned_link_path fromRoot="/guides/security/auth/extauth/#configuration-format/" %}})
 
 ---