Merge pull request #11037 from hashicorp/docs/mesh-header-manip

Document HTTP Header manipulation options added in #10613

website/content/docs/connect/config-entries/ingress-gateway.mdx

@@ -397,9 +397,13 @@ spec:
 <Tabs>
 <Tab heading="Consul OSS">
 
-Set up a HTTP listener on an ingress gateway named "us-east-ingress" to proxy
+Set up an HTTP listener on an ingress gateway named "us-east-ingress" to proxy
 traffic to a virtual service named "api".
 
+Additionally, ensure internal-only debug headers are stripped before responding
+to external clients, and that requests to internal services are labelled to
+indicate which gateway they came through.
+
 <CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
 
 ```hcl
@@ -413,6 +417,14 @@ Listeners = [
     Services = [
       {
         Name = "api"
+        RequestHeaders {
+          Add {
+            "x-gateway" = "us-east-ingress"
+          }
+        }
+        ResponseHeaders {
+          Remove = ["x-debug"]
+        }
       }
     ]
   }
@@ -430,6 +442,7 @@ spec:
       protocol: http
       services:
         - name: api
+          # HTTP Header manipulation is not yet supported in Kubernetes CRD
 ```
 
 ```json
@@ -442,7 +455,15 @@ spec:
       "Protocol": "http",
       "Services": [
         {
-          "Name": "api"
+          "Name": "api",
+          "RequestHeaders": {
+            "Add": {
+              "x-gateway": "us-east-ingress"
+            }
+          },
+          "ResponseHeaders": {
+            "Remove": ["x-debug"]
+          }
         }
       ]
     }
@@ -455,9 +476,13 @@ spec:
 </Tab>
 <Tab heading="Consul Enterprise">
 
-Set up a HTTP listener on an ingress gateway named "us-east-ingress" in the
+Set up an HTTP listener on an ingress gateway named "us-east-ingress" in the
 default namespace to proxy traffic to a virtual service named "api".
 
+Additionally, ensure internal-only debug headers are stripped before responding
+to external clients, and that requests to internal services are labelled to
+indicate which gateway they came through.
+
 <CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
 
 ```hcl
@@ -473,6 +498,14 @@ Listeners = [
       {
         Name = "api"
         Namespace = "frontend"
+        RequestHeaders {
+          Add {
+            "x-gateway" = "us-east-ingress"
+          }
+        }
+        ResponseHeaders {
+          Remove = ["x-debug"]
+        }
       }
     ]
   }
@@ -492,6 +525,7 @@ spec:
       services:
         - name: api
           namespace: frontend
+          # HTTP Header manipulation is not yet supported in Kubernetes CRD
 ```
 
 ```json
@@ -506,7 +540,15 @@ spec:
       "Services": [
         {
           "Name": "api",
-          "Namespace": "frontend"
+          "Namespace": "frontend",
+           "RequestHeaders": {
+            "Add": {
+              "x-gateway": "us-east-ingress"
+            }
+          },
+          "ResponseHeaders": {
+            "Remove": ["x-debug"]
+          }
         }
       ]
     }
@@ -838,6 +880,22 @@ spec:
               records. For example, \`*.example.com\` is valid, while \`example.*\` and
               \`*-suffix.example.com\` are not.`,
             },
+            {
+              yaml: false,
+              name: 'RequestHeaders',
+              type: 'HTTPHeaderModifiers: <optional>',
+              description: `A set of [HTTP-specific header modification rules](/docs/connect/config-entries/service-router#httpheadermodifiers)
+              that will be applied to requests routed to this service.
+              This cannot be used with a \`tcp\` listener.`,
+            },
+            {
+              yaml: false,
+              name: 'ResponseHeaders',
+              type: 'HTTPHeaderModifiers: <optional>',
+              description: `A set of [HTTP-specific header modification rules](/docs/connect/config-entries/service-router#httpheadermodifiers)
+              that will be applied to responses from this service.
+              This cannot be used with a \`tcp\` listener.`,
+            },
           ],
         },
       ],

website/content/docs/connect/config-entries/service-router.mdx

@@ -574,6 +574,71 @@ spec:
       description:
         'A list of HTTP response status codes that are eligible for retry.',
     },
+    {
+      yaml: false,
+      name: 'RequestHeaders',
+      type: 'HTTPHeaderModifiers: <optional>',
+      description: `A set of [HTTP-specific header modification rules](/docs/connect/config-entries/service-router#httpheadermodifiers)
+      that will be applied to requests routed to this service.
+      This cannot be used with a \`tcp\` listener.`,
+    },
+    {
+      yaml: false,
+      name: 'ResponseHeaders',
+      type: 'HTTPHeaderModifiers: <optional>',
+      description: `A set of [HTTP-specific header modification rules](/docs/connect/config-entries/service-router#httpheadermodifiers)
+      that will be applied to responses from this service.
+      This cannot be used with a \`tcp\` listener.`,
+    },
+  ]}
+/>
+
+
+### `HTTPHeaderModifiers`
+
+<ConfigEntryReference
+  topLevel={false}
+  yaml={false}
+  keys={[
+    {
+      hcl: false,
+      name: 'Unsupported',
+      type: '',
+      description: `HTTP Header modification is not yet supported in our Kubernetes CRDs.`,
+    },
+    {
+      yaml: false,
+      name: 'Add',
+      type: 'map<string|string>: optional',
+      description: `The set of key/value pairs that specify header values to add.
+      Use header names as keys. Header names are _not_ case-sensitive.
+      If header values with the same name already exist, the value set here will
+      be appended and both will be present.
+      If Envoy is used as the proxy, the value may contain
+      [variable placeholders](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#custom-request-response-headers) for example
+      \`%DOWNSTREAM_REMOTE_ADDRESS%\` to interpolate dynamic request
+      metadata into the value added.`,
+    },
+    {
+      yaml: false,
+      name: 'Set',
+      type: 'map<string|string>: optional',
+      description: `The set of key/value pairs that specify header values to add.
+      Use header names as keys. Header names are _not_ case-sensitive.
+      If header values with the same name already exist, the value set here will
+      _replace_ them.
+      If Envoy is used as the proxy, the value may contain
+      [variable placeholders](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#custom-request-response-headers) for example
+      \`%DOWNSTREAM_REMOTE_ADDRESS%\` to interpolate dynamic request
+      metadata into the value added.`,
+    },
+    {
+      yaml: false,
+      name: 'Remove',
+      type: 'array<string>: optional',
+      description: `The set of header names to remove. Only headers
+      whose names are a <i>case-insensitive</i> exact match will be removed`,
+    },
   ]}
 />
 

website/content/docs/connect/config-entries/service-splitter.mdx

@@ -146,6 +146,68 @@ spec:
 
 </CodeTabs>
 
+
+### Set HTTP Headers
+
+Split traffic between two subsets with extra headers added so clients can tell
+which version (not yet supported in Kubernetes CRD):
+
+<CodeTabs tabs={[ "HCL", "JSON" ]}>
+
+```hcl
+Kind = "service-splitter"
+Name = "web"
+Splits = [
+  {
+    Weight        = 90
+    ServiceSubset = "v1"
+    ResponseHeaders {
+      Set {
+        "X-Web-Version": "v1"
+      }
+    }
+  },
+  {
+    Weight        = 10
+    ServiceSubset = "v2"
+    ResponseHeaders {
+      Set {
+        "X-Web-Version": "v2"
+      }
+    }
+  },
+]
+```
+
+```json
+{
+  "Kind": "service-splitter",
+  "Name": "web",
+  "Splits": [
+    {
+      "Weight": 90,
+      "ServiceSubset": "v1",
+      "ResponseHeaders": {
+        "Set": {
+          "X-Web-Version": "v1"
+        }
+      }
+    },
+    {
+      "Weight": 10,
+      "ServiceSubset": "v2",
+      "ResponseHeaders": {
+        "Set": {
+          "X-Web-Version": "v2"
+        }
+      }
+    }
+  ]
+}
+```
+
+</CodeTabs>
+
 ## Available Fields
 
 <ConfigEntryReference
@@ -231,6 +293,22 @@ spec:
           description:
             'The namespace to resolve the service from instead of the current namespace. If empty the current namespace is assumed.',
         },
+        {
+          yaml: false,
+          name: 'RequestHeaders',
+          type: 'HTTPHeaderModifiers: <optional>',
+          description: `A set of [HTTP-specific header modification rules](/docs/connect/config-entries/service-router#httpheadermodifiers)
+          that will be applied to requests routed to this split.
+          This cannot be used with a \`tcp\` listener.`,
+        },
+        {
+          yaml: false,
+          name: 'ResponseHeaders',
+          type: 'HTTPHeaderModifiers: <optional>',
+          description: `A set of [HTTP-specific header modification rules](/docs/connect/config-entries/service-router#httpheadermodifiers)
+          that will be applied to responses from this split.
+          This cannot be used with a \`tcp\` listener.`,
+        },
       ],
     },
   ]}