Http header pictures (#98)

* docs: added pictures for header based routing

Signed-off-by: Kostis Kapelonis <[email protected]>

* docs: clarify header based routing

Signed-off-by: Kostis Kapelonis <[email protected]>

---------

Signed-off-by: Kostis Kapelonis <[email protected]>

docs/features/grpc.md

@@ -5,7 +5,7 @@ To use GRPCRoute:
 1. Install your traffic provider
 2. Install [GatewayAPI CRD](https://gateway-api.sigs.k8s.io/guides/#installing-gateway-api) if your traffic provider doesn't do it by default
 3. Install [Argo Rollouts](https://argoproj.github.io/argo-rollouts/installation/)
-4. Install [Argo Rollouts GatewayAPI plugin](installation.md)
+4. Install [Argo Rollouts GatewayAPI plugin](../installation.md)
 5. Create stable and canary services
 6. Create GRPCRoute resource according to the GatewayAPI and your traffic provider documentation
 ```yaml

docs/features/header-based-routing.md

@@ -4,8 +4,35 @@ When you want to isolate the behavior of clients that connect to a canary, you c
 
 An alternative method is to use HTTP headers that distinguish which clients connect to the canary and which do not.
 
+## How Header based routing works
+
+By default when Argo Rollouts sends new traffic to canary pods, this happens on the request level and it is completely random.
+
+![Random percentage routing](../images/header-based-routing/request-routing.png)
+
+This means that you cannot predict which requests from a single user will go the canary pods and which will go to the stable pods. This can be a big issue if the rollout represents an end-user application with a web based interface.
+
+For example, if the new version has different colors on the web page buttons or different elements, a single user might see a different graphical interface each time they request the page.
+
+To overcome this issue you can get full control over which requests go to the canary pods by using a special [HTTP header](https://datatracker.ietf.org/doc/html/rfc2616#section-4.2). This instructs Argo Rollouts to always sends requests to the canary pods if this special header is present. 
+
+![how headers work](../images/header-based-routing/using-a-header.png)
+
+Therefore you have the power to direct specific users to the canary instead of just random requests. There are several ways to inject custom headers in your network calls
+
+1. Several network products (load balancers, proxies, firewalls etc.) can inject and process HTTP headers
+1. You can have the application itself inject HTTP headers on its own requests
+1. You can instruct other applications that call the canary application to use HTTP headers when they communicate with it.
+
+![User routing](../images/header-based-routing/user-routing.png)
+
+The end result is that instead of having random requests go to canary pods, you can now decide exactly which users will see the canary pods.
+
 ## Using a custom header with a single route
 
+!!! important
+    Your [Gateway API provider](https://gateway-api.sigs.k8s.io/implementations/) must also support Header based routing before you can activate it in a Rollout manifest.
+
 Here is an example of a rollout that uses headers 
 for the canary:
 
@@ -68,11 +95,19 @@ spec:
               protocol: TCP
 ```              
 
+This manifest instructs Argo Rollouts to do the following:
+
+1. Create 2 **brand new** HTTP routes called `canary-route1` and `canary-route2`
+1. The first route will be created on the fly when the canary is at 10% traffic. The second when the canary is at 50% traffic.
+1. These routes will be cloned/copied from the provided `argo-rollouts-http-route`
+1. Both of these 2 routes will always point to the canary pods
+1. All requests with an HTTP header `X-Canary-start: ten-per-cent` will be sent to the first route while all requests with an http header `X-Canary-middle:half-traffic` will be sent to the second route
+
 Notice that the route names used for headers in `setHeaderRoute` must also be defined in the `managedRoutes` block as well.
 
-Now when the canary reaches 10% an extra route will be created that uses the `X-Canary-start` header with value `ten-per-cent`
+Now when the canary reaches 10% an extra route will be created that uses the `X-Canary-start` header with value `ten-per-cent`. When the canary reaches 50% a different header route will be created. At the end of the canary all header routes are discarded.
 
-When the canary reaches 50% a different header route will be created. At the end of the canary all header routes are discarded.
+These smart routes will be created by Argo Rollouts and will be destroyed automatically when the rollout has finished. In your manifests you only need to provide the `argo-rollouts-http-route` definition. See also the [HTTP routing](https://gateway-api.sigs.k8s.io/guides/http-routing/) documentation.
 
 ## Using multiple routes with headers
 
@@ -147,4 +182,8 @@ spec:
 ```    
 
 With the `useHeaderRoutes` variable you can decide which routes
-will honor the custom headers.
+will honor the custom headers.
+
+## Full example with Header based routing and Argo Rollouts
+
+For a complete example with header based routing see our [LinkerD example](https://github.com/argoproj-labs/rollouts-plugin-trafficrouter-gatewayapi/tree/main/examples/linkerd-header-based).

docs/features/tcp.md

@@ -5,7 +5,7 @@ To use TCPRoute:
 1. Install your traffic provider
 2. Install [GatewayAPI CRD](https://gateway-api.sigs.k8s.io/guides/#installing-gateway-api) if your traffic provider doesn't do it by default
 3. Install [Argo Rollouts](https://argoproj.github.io/argo-rollouts/installation/)
-4. Install [Argo Rollouts GatewayAPI plugin](installation.md)
+4. Install [Argo Rollouts GatewayAPI plugin](../installation.md)
 5. Create stable and canary services
 6. Create TCPRoute resource according to the GatewayAPI and your traffic provider documentation
 ```yaml