From d84380882b88a2e06b1889ad822469939ed8a6a8 Mon Sep 17 00:00:00 2001 From: Paul Banks Date: Wed, 15 Sep 2021 13:36:58 +0100 Subject: [PATCH] Document HTTP Header manipulation options added in #10613 --- .../config-entries/ingress-gateway.mdx | 62 ++++++++++++++- .../connect/config-entries/service-router.mdx | 63 +++++++++++++++ .../config-entries/service-splitter.mdx | 78 +++++++++++++++++++ 3 files changed, 201 insertions(+), 2 deletions(-) diff --git a/website/content/docs/connect/config-entries/ingress-gateway.mdx b/website/content/docs/connect/config-entries/ingress-gateway.mdx index 6ada45780..049a3077a 100644 --- a/website/content/docs/connect/config-entries/ingress-gateway.mdx +++ b/website/content/docs/connect/config-entries/ingress-gateway.mdx @@ -400,6 +400,10 @@ spec: Set up a 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. + ```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"] + } } ] } @@ -458,6 +479,10 @@ spec: Set up a 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. + ```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: ', + 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: ', + 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.`, + }, ], }, ], diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index 7bc6af1fb..c2f00ac3c 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -574,6 +574,69 @@ spec: description: 'A list of HTTP response status codes that are eligible for retry.', }, + { + yaml: false, + name: 'RequestHeaders', + type: 'HTTPHeaderModifiers: ', + 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: ', + 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` + +: optional', + description: `The set of header value keyed by header name to + add. If a header with the same (case-insensitive) name already + exists, 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: optional', + description: `The set of header value keyed by header name to + add. If one or more header values with the same (case-insensitive) name already exist, + the value set here will replace them all. + 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: optional', + description: `The set of header names to remove. Only headers + whose names are an case-insensitive exact match will be removed`, + }, ]} /> diff --git a/website/content/docs/connect/config-entries/service-splitter.mdx b/website/content/docs/connect/config-entries/service-splitter.mdx index ad3798c78..f6eb62ddf 100644 --- a/website/content/docs/connect/config-entries/service-splitter.mdx +++ b/website/content/docs/connect/config-entries/service-splitter.mdx @@ -146,6 +146,68 @@ spec: + +### Set HTTP Headers + +Split traffic between two subsets with extra headers added so clients can tell +which version (not yet supported in Kubernetes CRD): + + + +```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" + } + } + } + ] +} +``` + + + ## Available Fields ', + 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: ', + 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.`, + }, ], }, ]}