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

Document HTTP Header manipulation options added in #10613
This commit is contained in:
Paul Banks 2021-10-08 13:11:44 +01:00 committed by GitHub
commit 51769d1f95
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 205 additions and 4 deletions

View File

@ -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.`,
},
],
},
],

View File

@ -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`,
},
]}
/>

View File

@ -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.`,
},
],
},
]}