From fe92cf7cb61bf3f05918ff521ec012c50ae4c358 Mon Sep 17 00:00:00 2001 From: Paul Banks Date: Wed, 15 Sep 2021 13:36:58 +0100 Subject: [PATCH 1/3] 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 6ada45780c..049a3077a8 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 7bc6af1fb0..c2f00ac3ce 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 ad3798c785..f6eb62ddf7 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.`, + }, ], }, ]} From 1a611f0c1be790a45c114661d90c00939e0b2034 Mon Sep 17 00:00:00 2001 From: Paul Banks Date: Tue, 28 Sep 2021 17:19:13 +0100 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Blake Covarrubias --- .../content/docs/connect/config-entries/service-router.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index c2f00ac3ce..e63added61 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -610,8 +610,8 @@ spec: yaml: false, name: 'Add', type: 'map: optional', - description: `The set of header value keyed by header name to - add. If a header with the same (case-insensitive) name already + description: `The set of header values to add, keyed by header name. + 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 @@ -635,7 +635,7 @@ spec: 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`, + whose names are a case-insensitive exact match will be removed`, }, ]} /> From 3da2fbdc632ddc8b002feebf0cadfed3d5f7280b Mon Sep 17 00:00:00 2001 From: Paul Banks Date: Fri, 8 Oct 2021 12:26:11 +0100 Subject: [PATCH 3/3] Wording improvements from review --- .../connect/config-entries/ingress-gateway.mdx | 4 ++-- .../docs/connect/config-entries/service-router.mdx | 14 ++++++++------ 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/website/content/docs/connect/config-entries/ingress-gateway.mdx b/website/content/docs/connect/config-entries/ingress-gateway.mdx index 049a3077a8..6be29df290 100644 --- a/website/content/docs/connect/config-entries/ingress-gateway.mdx +++ b/website/content/docs/connect/config-entries/ingress-gateway.mdx @@ -397,7 +397,7 @@ spec: -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 @@ -476,7 +476,7 @@ spec: -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 diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index e63added61..3e02f16011 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -610,9 +610,10 @@ spec: yaml: false, name: 'Add', type: 'map: optional', - description: `The set of header values to add, keyed by header name. - If a header with the same (case-insensitive) name already - exists, the value set here will be appended and both will be present. + 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 @@ -622,9 +623,10 @@ spec: 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. + 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