Reference: HTTPProxy CRD
The HTTPProxy is a Custom Resource Definition (CRD) that tells the Service
Proxy how to route external traffic to the Service objects in your namespace.
A "root" HTTPProxy defines a virtual host (a fully qualified domain name and
its TLS settings). It can route requests itself and can include other
HTTPProxy resources, possibly from other namespaces, that handle part of the
path space.
apiVersion: projectcontour.io/v1
kind: HTTPProxy
- Scope: Namespaced
- Short names:
proxy, proxies
This page documents Contour 1.33.8.
Example
The following root HTTPProxy serves my-app.your-domain.com over HTTPS. It
applies a cross-origin resource sharing (CORS) policy and a local rate limit to
the whole virtual host. All traffic goes to my-app-service, except requests
under /new-ui, which are split 90/10 between the current version and a canary.
apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
name: my-app-proxy
namespace: your-namespace
spec:
virtualhost:
fqdn: my-app.your-domain.com
tls:
# Secret created by a cert-manager Certificate in the same namespace.
secretName: my-app-tls-secret
minimumProtocolVersion: "1.3"
corsPolicy:
allowOrigin:
- https://www.your-domain.com
allowMethods:
- GET
- POST
- OPTIONS
allowHeaders:
- authorization
- content-type
maxAge: 10m
rateLimitPolicy:
local:
requests: 100
unit: second
burst: 50
routes:
- conditions:
- prefix: /new-ui
services:
- name: my-app-service
port: 8080
weight: 90
- name: my-app-canary
port: 8080
weight: 10
pathRewritePolicy:
replacePrefix:
- replacement: /
- conditions:
- prefix: /
services:
- name: my-app-service
port: 8080
timeoutPolicy:
response: 30s
idle: 5m
retryPolicy:
count: 3
perTryTimeout: 10s
retryOn:
- gateway-error
- connect-failure
responseHeadersPolicy:
set:
- name: Strict-Transport-Security
value: max-age=31536000
Specification (spec)
An HTTPProxy must define at least one route or include, or a tcpproxy.
| Field |
Type |
Description |
virtualhost |
object |
Optional. Makes this HTTPProxy a root. Defines the domain name, TLS, and policies that apply to the whole virtual host. An HTTPProxy that is included by another must not set virtualhost. See spec.virtualhost. |
routes |
[]object |
Optional. Routing rules that match requests and send them to Service objects. Ignored when tcpproxy is set. See spec.routes[]. |
includes |
[]object |
Optional. Other HTTPProxy resources whose routes are merged into this one, optionally under extra match conditions. See spec.includes[]. |
tcpproxy |
object |
Optional. Forwards raw TCP traffic for the virtual host to a Service. Requires virtualhost.tls. When set, routes is ignored. See spec.tcpproxy. |
ingressClassName |
string |
Optional. The ingress class this HTTPProxy belongs to. Replaces the deprecated kubernetes.io/ingress.class annotation. If the annotation is set, it takes precedence over this field. |
Durations in this resource use the Go duration format, for example 300ms,
5s, 1m or 1h30m. Valid units are ns, us (or µs), ms, s, m
and h. Fields marked as accepting infinity also accept infinity or
infinite to disable the timeout.
spec.virtualhost
| Field |
Type |
Description |
fqdn |
string |
Required. The fully qualified domain name the virtual host serves, for example my-app.your-domain.com. Lowercase DNS name. A leading wildcard label (*.your-domain.com) is allowed. |
tls |
object |
Optional. Enables HTTPS for the virtual host. See spec.virtualhost.tls. |
corsPolicy |
object |
Optional. The cross-origin resource sharing (CORS) policy for the virtual host. See spec.virtualhost.corsPolicy. |
rateLimitPolicy |
object |
Optional. Rate limiting for all requests to the virtual host. See Rate Limit Policy. |
authorization |
object |
Optional. Sends each request to an external authorization service before routing it. Requires tls with secretName. See spec.virtualhost.authorization. |
jwtProviders |
[]object |
Optional. Providers used to verify JSON Web Tokens (JWTs) on requests. Requires tls with secretName. See spec.virtualhost.jwtProviders[]. |
ipAllowPolicy |
[]object |
Optional. Allows only requests from the listed IP ranges and denies all others. Routes can override it. You can set either ipAllowPolicy or ipDenyPolicy, not both. See IP Filter Policies. |
ipDenyPolicy |
[]object |
Optional. Denies requests from the listed IP ranges and allows all others. Routes can override it. You can set either ipAllowPolicy or ipDenyPolicy, not both. |
spec.virtualhost.tls
When TLS is enabled, the Service Proxy answers plain HTTP requests with a 301
redirect to HTTPS. Set permitInsecure on a route to serve that route over
plain HTTP as well.
| Field |
Type |
Description |
secretName |
string |
Optional. Name of a kubernetes.io/tls Secret whose certificate matches fqdn. Set exactly one of secretName and passthrough. You can reference a Secret in another namespace as namespace/name if that namespace has a TLSCertificateDelegation granting access to it. |
passthrough |
boolean |
Optional. When true, the Service Proxy does not terminate TLS. It routes the encrypted connection by its Server Name Indication (SNI) to the Service in tcpproxy, which completes the TLS handshake itself. Set exactly one of secretName and passthrough. |
minimumProtocolVersion |
string |
Optional. The lowest TLS version to negotiate. Allowed values: 1.2 (default) and 1.3. Any other value is treated as 1.2. |
maximumProtocolVersion |
string |
Optional. The highest TLS version to negotiate. Allowed values: 1.2 and 1.3 (default). Any other value is treated as 1.3. |
clientValidation |
object |
Optional. Enables mutual TLS by requesting and validating client certificates. See spec.virtualhost.tls.clientValidation. |
enableFallbackCertificate |
boolean |
Optional. Serves a cluster-wide fallback certificate to clients that do not send SNI. Not compatible with clientValidation, authorization or jwtProviders. Requires a fallback certificate configured for the cluster. |
spec.virtualhost.tls.clientValidation
| Field |
Type |
Description |
caSecret |
string |
Optional. Name of a Secret with a ca.crt key that holds the CA bundle client certificates must chain to. Accepts namespace/name for a Secret delegated with TLSCertificateDelegation. If set together with skipClientCertValidation: true, clients must present a certificate, but it is not verified. |
crlSecret |
string |
Optional. Name of an opaque Secret with a crl.pem key that holds concatenated PEM certificate revocation lists. A revocation list must be present for every CA in the chain unless crlOnlyVerifyLeafCert is true. A Secret is limited to 1 MiB, so large revocation lists are not supported. Accepts namespace/name as for caSecret. |
crlOnlyVerifyLeafCert |
boolean |
Optional. When true, only the leaf certificate is checked against the CRL. |
optionalClientCertificate |
boolean |
Optional. When true, a client certificate is requested, but the connection continues if the client sends none. A certificate that is sent is still validated. Default: false. |
skipClientCertValidation |
boolean |
Optional. When true, client certificates are requested but not verified by the proxy. Use this only together with authorization, so the external authorization service validates the certificate. Default: false. |
forwardClientCertificate |
object |
Optional. Selects which client certificate details to add to the x-forwarded-client-cert request header. Boolean fields: cert (the certificate as URL-encoded PEM), chain (the full chain as URL-encoded PEM), subject, dns (DNS Subject Alternative Names) and uri (URI Subject Alternative Name). |
spec.virtualhost.corsPolicy
| Field |
Type |
Description |
allowOrigin |
[]string |
Required. Origins allowed to make cross-origin requests. Each entry is * (any origin), an exact origin such as https://www.your-domain.com:8443, or a regular expression. A glob such as *.your-domain.com is not valid and is rejected or matches unexpectedly. |
allowMethods |
[]string |
Required. Content of the Access-Control-Allow-Methods header, for example GET, POST, OPTIONS. |
allowHeaders |
[]string |
Optional. Content of the Access-Control-Allow-Headers header. |
exposeHeaders |
[]string |
Optional. Content of the Access-Control-Expose-Headers header. |
allowCredentials |
boolean |
Optional. Whether the browser may send credentials such as cookies. |
allowPrivateNetwork |
boolean |
Optional. Whether to allow private network access requests from browsers. |
maxAge |
string |
Optional. How long browsers may cache the result of a preflight request, as a duration. 0 disables caching, so every cross-origin request needs a preflight OPTIONS request. |
spec.virtualhost.authorization
External authorization sends each request to an authorization service before
the Service Proxy routes it. The service is described by an ExtensionService
resource, which extensionRef points to. The ExtensionService must be in the
same namespace as the Service objects it targets.
| Field |
Type |
Description |
extensionRef |
object |
Optional. Reference to the ExtensionService that authorizes requests. Fields: name, namespace (defaults to the namespace of the HTTPProxy) and apiVersion (defaults to projectcontour.io/v1alpha1). |
authPolicy |
object |
Optional. The default authorization policy for all routes. Routes can override it. See authPolicy. |
responseTimeout |
string |
Optional. Maximum time to wait for the authorization service to respond, as a duration. Accepts infinity. |
failOpen |
boolean |
Optional. When true, requests are forwarded even if the authorization service does not respond. Intended only for migrating from in-application authorization. |
withRequestBody |
object |
Optional. Sends the request body to the authorization service. Fields: maxRequestBytes (integer, default 1024, minimum 1) limits the buffered body size, allowPartialMessage (boolean) sends the body even when it is truncated at maxRequestBytes, and packAsBytes (boolean) sends the body as raw bytes. |
spec.virtualhost.jwtProviders[]
JWT verification checks the signature and claims of the token in the
Authorization header. A route requires a provider either by naming it in
jwtVerificationPolicy.require or through a provider marked default.
| Field |
Type |
Description |
name |
string |
Required. Unique name of the provider. Routes reference this name. |
remoteJWKS |
object |
Required. Where to fetch the JSON Web Key Set (JWKS) used to verify signatures. See the table below. |
issuer |
string |
Optional. Required value of the iss claim. If unset, the issuer is not checked. |
audiences |
[]string |
Optional. Allowed values of the aud claim. If unset, the audience is not checked. |
default |
boolean |
Optional. Applies this provider to all routes of the HTTPProxy and its includes, unless a route disables verification or requires another provider. At most one provider can be the default. |
forwardJWT |
boolean |
Optional. Forwards the JWT to the backend after successful verification. Default: not forwarded. |
remoteJWKS has the following fields.
| Field |
Type |
Description |
uri |
string |
Required. URI of the JWKS. Must use https when validation is set. |
timeout |
string |
Optional. How long to wait for the JWKS server to respond, as a duration. Default: 1s. |
cacheDuration |
string |
Optional. How long to cache the JWKS, as a duration. Default: 5m. |
dnsLookupFamily |
string |
Optional. IP family used to resolve the JWKS host. Allowed values: auto, v4, v6. Default: the cluster-wide setting, which defaults to auto. |
validation |
object |
Optional. Validates the TLS certificate of the JWKS server. Without it, the certificate is not validated. See Upstream Validation. |
spec.virtualhost.ipAllowPolicy and ipDenyPolicy
Both lists use the same rule object. The same fields are available on routes as
spec.routes[].ipAllowPolicy and spec.routes[].ipDenyPolicy, where they
override the rules of the virtual host.
| Field |
Type |
Description |
cidr |
string |
Required. An IPv4 or IPv6 CIDR block, or a single IP address without a mask. |
source |
string |
Required. Which address to filter on. Remote uses the client address, taking the PROXY protocol and X-Forwarded-For into account. Peer uses the address of the direct network connection and ignores both. Allowed values: Remote, Peer. |
spec.virtualhost.rateLimitPolicy and spec.routes[].rateLimitPolicy
You can set a rate limit policy on the virtual host, on individual routes, or
both. A local rate limit is enforced inside each Envoy pod, so the effective
limit across the platform is the configured limit multiplied by the number of
Envoy pods. A global rate limit sends request descriptors to an external rate
limit service (RLS), which makes the decision.
| Field |
Type |
Description |
local |
object |
Optional. Limits enforced by each Envoy pod. See the local table below. |
global |
object |
Optional. Descriptors sent to the external rate limit service. See the global table below. |
local has the following fields.
| Field |
Type |
Description |
requests |
integer |
Required. Number of requests allowed per unit. Minimum 1. |
unit |
string |
Required. The period for requests. Allowed values: second, minute, hour. |
burst |
integer |
Optional. Extra requests allowed above requests within a short period. |
responseStatusCode |
integer |
Optional. HTTP status returned for rate-limited requests, between 400 and 599. Default: 429. |
responseHeadersToAdd |
[]object |
Optional. Headers added to rate-limited responses. Each entry has a required name and value. |
global has the following fields.
| Field |
Type |
Description |
descriptors |
[]object |
Optional. Descriptors generated for each request. Each descriptor has a required entries list with at least one entry. A descriptor is only sent if all its entries produce a value. |
disabled |
boolean |
Optional. When true, the cluster-wide default global rate limit policy does not apply to this virtual host or route. |
Each item in descriptors[].entries sets exactly one of the following fields.
| Field |
Type |
Description |
genericKey |
object |
A static entry. Fields: value (Required.) and key (Optional., default generic_key). |
remoteAddress |
object |
An entry with key remote_address and the client IP address as value. Takes no fields ({}). |
requestHeader |
object |
An entry with key descriptorKey and the value of the request header headerName. Both fields are Required. No entry is produced if the header is missing. |
requestHeaderValueMatch |
object |
An entry with key header_match and the static value (Required.), produced when the request matches headers. headers is a list of header match conditions. expectMatch (default true) set to false produces the entry when the headers do not match. |
spec.routes[]
Each route matches requests by its conditions and handles them in one of
three ways. It forwards them to services, answers with a redirect
(requestRedirectPolicy), or answers directly (directResponsePolicy).
| Field |
Type |
Description |
conditions |
[]object |
Optional. Match conditions, combined with AND. Without conditions, the route matches all paths (prefix: /). See Match Conditions. |
services |
[]object |
Optional. The Service objects that receive the traffic. With several services, traffic is balanced between them by weight. See spec.routes[].services[]. |
enableWebsockets |
boolean |
Optional. Enables WebSocket upgrades on the route. |
permitInsecure |
boolean |
Optional. Serves the route over plain HTTP even when the virtual host has TLS enabled, instead of redirecting to HTTPS. |
timeoutPolicy |
object |
Optional. Response and idle timeouts. See spec.routes[].timeoutPolicy. |
retryPolicy |
object |
Optional. When and how often to retry failed requests. See spec.routes[].retryPolicy. |
healthCheckPolicy |
object |
Optional. Active HTTP health checks against the route's services. See spec.routes[].healthCheckPolicy. |
loadBalancerPolicy |
object |
Optional. How requests are spread across the pods of a service. See spec.routes[].loadBalancerPolicy. |
pathRewritePolicy |
object |
Optional. Rewrites the request path before forwarding. See spec.routes[].pathRewritePolicy. |
requestHeadersPolicy |
object |
Optional. Sets or removes request headers. Can rewrite the Host header, including dynamically. See Header Policies. |
responseHeadersPolicy |
object |
Optional. Sets or removes response headers. Cannot rewrite Host. See Header Policies. |
cookieRewritePolicies |
[]object |
Optional. Rewrites attributes of Set-Cookie response headers. Cookie names must be unique in the list. See cookieRewritePolicies[]. |
requestRedirectPolicy |
object |
Optional. Answers with an HTTP redirect instead of forwarding. See spec.routes[].requestRedirectPolicy. |
directResponsePolicy |
object |
Optional. Answers with a fixed response instead of forwarding. See spec.routes[].directResponsePolicy. |
internalRedirectPolicy |
object |
Optional. Follows 3xx responses from the backend inside the proxy. See spec.routes[].internalRedirectPolicy. |
rateLimitPolicy |
object |
Optional. Rate limiting for this route. See Rate Limit Policy. |
ipAllowPolicy |
[]object |
Optional. Overrides the IP allow rules of the virtual host for this route. See IP Filter Policies. |
ipDenyPolicy |
[]object |
Optional. Overrides the IP deny rules of the virtual host for this route. |
authPolicy |
object |
Optional. Overrides the external authorization policy of the virtual host. See authPolicy. |
jwtVerificationPolicy |
object |
Optional. Selects or disables JWT verification for the route. See jwtVerificationPolicy. |
spec.routes[].conditions and spec.includes[].conditions
Conditions in one list are combined with AND. A list can contain at most one
path condition (prefix, exact or regex). Contradictory conditions make the
route or include invalid. On includes, only prefix, header and
queryParameter are allowed.
Conditions on an include are added to the conditions of every route in the
included HTTPProxy. Path conditions are concatenated, so prefix: /api on the
include and prefix: /v1 on the route match /api/v1.
| Field |
Type |
Description |
prefix |
string |
Matches paths that start with this value. Must start with /. |
exact |
string |
Matches exactly this path. Must start with /. Routes only. |
regex |
string |
Matches paths against this regular expression. Must start with /. Routes only. |
header |
object |
Matches a request header. See Header Match Conditions. |
queryParameter |
object |
Matches a query parameter. See Query Parameter Match Conditions. |
Set name and one operator.
| Field |
Type |
Description |
name |
string |
Required. Header name. Case-insensitive. |
present |
boolean |
Matches when the header is present, with any value. |
notpresent |
boolean |
Matches when the header is absent. |
exact |
string |
Matches when the value equals this string. |
notexact |
string |
Matches when the header has any other value. |
contains |
string |
Matches when the value contains this substring. |
notcontains |
string |
Matches when the value does not contain this substring. |
regex |
string |
Matches when the value matches this regular expression. |
ignoreCase |
boolean |
Optional. Makes string operators case-insensitive. No effect on regex. |
treatMissingAsEmpty |
boolean |
Optional. Treats a missing header as an empty value. Only supported with notcontains and notexact. Default: false. |
Query Parameter Match Conditions
Set name and one operator.
| Field |
Type |
Description |
name |
string |
Required. Query parameter name. |
present |
boolean |
Matches when the parameter is present, with any value. |
exact |
string |
Matches when the value equals this string. |
prefix |
string |
Matches when the value starts with this string. |
suffix |
string |
Matches when the value ends with this string. |
contains |
string |
Matches when the value contains this substring. |
regex |
string |
Matches when the value matches this regular expression. |
ignoreCase |
boolean |
Optional. Makes string operators case-insensitive. No effect on regex and present. |
spec.routes[].services[]
| Field |
Type |
Description |
name |
string |
Required. Name of a Service in the same namespace as the HTTPProxy. |
port |
integer |
Required. The Service port to send traffic to. |
weight |
integer |
Optional. Relative share of traffic. Weights do not need to add up to 100. If no service has a weight, traffic is split evenly. If only some services have a weight, the others get none. For a mirror service, the percentage of traffic to mirror (1-100). |
mirror |
boolean |
Optional. Sends a copy of the route's traffic to this service and discards its responses. Without weight, all traffic is mirrored. Setting weight: 0 also mirrors all traffic. |
protocol |
string |
Optional. Protocol used to reach the service. Allowed values: h2 (HTTP/2 over TLS), h2c (HTTP/2 without TLS), tls (TLS). If unset, annotations on the Service decide. |
validation |
object |
Optional. Validates the certificate the service presents when protocol uses TLS. See Upstream Validation. |
healthPort |
integer |
Optional. Port used for health checks. Default: port. |
slowStartPolicy |
object |
Optional. Gradually increases traffic to new pods. See slowStartPolicy. |
requestHeadersPolicy |
object |
Optional. Sets or removes request headers for this service only. A dynamic Host rewrite is not possible here. See Header Policies. |
responseHeadersPolicy |
object |
Optional. Sets or removes response headers for this service only. See Header Policies. |
cookieRewritePolicies |
[]object |
Optional. Rewrites Set-Cookie attributes for this service only. See cookieRewritePolicies[]. |
spec.routes[].services[].validation
The same object configures TLS validation for services in routes and
tcpproxy, and for jwtProviders[].remoteJWKS.
| Field |
Type |
Description |
caSecret |
string |
Required. Name of a Secret with a ca.crt key that holds the trusted CA certificates. Accepts namespace/name for a Secret delegated with TLSCertificateDelegation. |
subjectName |
string |
Required. A name expected in the Subject Alternative Names of the certificate. Deprecated in favor of subjectNames, but still required by the schema. If subjectNames is set, its first entry must equal subjectName. |
subjectNames |
[]string |
Optional. Up to 8 names. The certificate must contain at least one of them in its Subject Alternative Names. |
spec.routes[].services[].slowStartPolicy
| Field |
Type |
Description |
window |
string |
Required. Duration of the slow start period. |
aggression |
string |
Optional. How fast traffic increases during the window, as a decimal number greater than 0. 1.0 (default) increases traffic linearly. Higher values ramp up faster. |
minWeightPercent |
integer |
Optional. Starting percentage of traffic for a new pod, between 0 and 100. Default: 10. |
requestHeadersPolicy and responseHeadersPolicy have the same fields on
routes and on services.
| Field |
Type |
Description |
set |
[]object |
Optional. Headers to set. Each entry has a required name and value. Existing headers with that name are overwritten. |
remove |
[]string |
Optional. Names of headers to remove. |
A value can contain dynamic placeholders such as %REQ(header-name)%, which
inserts the value of a request header. On a route, setting the Host request
header to %REQ(X-Header-Name)% rewrites the host dynamically. Only use headers
from a trusted source for this, and note that the rewrite does not affect
routing.
cookieRewritePolicies[]
Available on routes and on services.
| Field |
Type |
Description |
name |
string |
Required. Name of the cookie to rewrite. |
pathRewrite |
object |
Optional. Sets the Path attribute to value (Required.). |
domainRewrite |
object |
Optional. Sets the Domain attribute to value (Required., a DNS name). |
secure |
boolean |
Optional. Sets or clears the Secure attribute. |
sameSite |
string |
Optional. Sets the SameSite attribute. Allowed values: Strict, Lax, None. |
Attributes you do not set are left unchanged.
spec.routes[].timeoutPolicy
| Field |
Type |
Description |
response |
string |
Optional. Time from the end of the client request until the complete response is received from the backend. Default: 15s. Accepts infinity. 0s means the default. |
idle |
string |
Optional. Time without activity on a single request/response (HTTP/1.1) or stream (HTTP/2). Does not apply to idle HTTP/1.1 connections between requests. If unset, the proxy-wide stream idle timeout of 5m applies. Accepts infinity. |
idleConnection |
string |
Optional. How long a connection from the proxy to the backend stays open without active requests. Default: 1h. Accepts infinity. |
spec.routes[].retryPolicy
| Field |
Type |
Description |
count |
integer |
Optional. Maximum number of retries. -1 disables retries. 0 or unset means 1. Default: 1. |
perTryTimeout |
string |
Optional. Timeout for each attempt. Ignored if count is unset or if it exceeds the route's response timeout. Accepts infinity. |
retryOn |
[]string |
Optional. Conditions that trigger a retry. HTTP: 5xx, gateway-error, reset, reset-before-request, connect-failure, envoy-ratelimited, retriable-4xx, refused-stream, retriable-status-codes, retriable-headers, http3-post-connect-failure. gRPC: cancelled, deadline-exceeded, internal, resource-exhausted, unavailable. |
retriableStatusCodes |
[]integer |
Optional. HTTP status codes to retry. Only used when retryOn contains retriable-status-codes. |
spec.routes[].healthCheckPolicy
Active health checks remove pods that fail the check from load balancing.
| Field |
Type |
Description |
path |
string |
Required. HTTP path to request on the service. |
host |
string |
Optional. Host header of the check request. Default: contour-envoy-healthcheck. |
intervalSeconds |
integer |
Optional. Seconds between checks. |
timeoutSeconds |
integer |
Optional. Seconds to wait for a check response. |
unhealthyThresholdCount |
integer |
Optional. Failed checks before a pod is marked unhealthy. |
healthyThresholdCount |
integer |
Optional. Successful checks before a pod is marked healthy. |
expectedStatuses |
[]object |
Optional. HTTP status ranges counted as healthy. Each range has a required start (inclusive, 100-599) and end (exclusive, 101-600). Default: only 200. |
spec.routes[].loadBalancerPolicy
| Field |
Type |
Description |
strategy |
string |
Optional. Allowed values: RoundRobin (default), WeightedLeastRequest (prefers pods with fewer active requests), Random, Cookie (session affinity through a cookie) and RequestHash (selects a pod by hashing request attributes from requestHashPolicies). An unknown value falls back to RoundRobin. |
requestHashPolicies |
[]object |
Optional. Hash inputs for RequestHash. Invalid entries are ignored. If no valid entry remains, the strategy falls back to RoundRobin. See the table below. |
Each item in requestHashPolicies sets exactly one hash input. An item with
more than one input is ignored.
| Field |
Type |
Description |
headerHashOptions |
object |
Hashes the request header headerName (Required.). No hash is produced if the header is missing. |
queryParameterHashOptions |
object |
Hashes the query parameter parameterName (Required.). No hash is produced if the parameter is missing. |
hashSourceIP |
boolean |
Hashes the client source IP address. |
terminal |
boolean |
Optional. When true and this input is present, later hash policies are skipped. |
spec.routes[].pathRewritePolicy
| Field |
Type |
Description |
replacePrefix |
[]object |
Optional. Replaces the matched path prefix before the request is forwarded. Each entry has a required replacement and an optional prefix. If prefix is set, only that exact prefix is replaced. It must equal the full prefix produced by the include chain, which matters when the HTTPProxy is included through several roots. If prefix is unset, any matched prefix is replaced. |
spec.routes[].requestRedirectPolicy
Fields you leave unset keep the value from the original request.
| Field |
Type |
Description |
scheme |
string |
Optional. Scheme of the Location header. Allowed values: http, https. |
hostname |
string |
Optional. Host of the Location header. No wildcards. |
port |
integer |
Optional. Port of the Location header, 1-65535. |
path |
string |
Optional. Replaces the whole path. Must start with /. Set either path or prefix, not both. |
prefix |
string |
Optional. Replaces the matched prefix or path. Must start with /. Set either path or prefix, not both. |
statusCode |
integer |
Optional. Redirect status. Allowed values: 301, 302, 303, 307, 308. Default: 302. |
spec.routes[].directResponsePolicy
| Field |
Type |
Description |
statusCode |
integer |
Required. HTTP status to return, 200-599. |
body |
string |
Optional. Response body. Keep it short, because large bodies increase resource usage. |
spec.routes[].internalRedirectPolicy
With an internal redirect, the proxy follows a 3xx response from the backend
itself and returns the final response to the client.
| Field |
Type |
Description |
redirectResponseCodes |
[]integer |
Optional. Response codes to follow. Allowed values: 301, 302, 303, 307, 308. Default: only 302. |
maxInternalRedirects |
integer |
Optional. Maximum number of internal redirects for one request. |
allowCrossSchemeRedirect |
string |
Optional. Whether a redirect can change the scheme. Never (default), Always, or SafeOnly (an HTTPS request may follow HTTP and HTTPS targets, an HTTP request only HTTP targets). |
denyRepeatedRouteRedirect |
boolean |
Optional. Rejects redirects to a route that an earlier redirect in the same request already followed. |
spec.routes[].authPolicy and jwtVerificationPolicy
authPolicy has the same fields on a route and in
spec.virtualhost.authorization.authPolicy.
| Field |
Type |
Description |
authPolicy.disabled |
boolean |
Optional. When true, requests in this scope skip external authorization. |
authPolicy.context |
map[string]string |
Optional. Key-value pairs sent to the authorization service. Route entries override virtual host entries with the same key. |
jwtVerificationPolicy.require |
string |
Optional. Name of the JWT provider the route requires. Overrides the default provider. Set either require or disabled, not both. |
jwtVerificationPolicy.disabled |
boolean |
Optional. When true, the route skips JWT verification, including the default provider. |
spec.includes[]
spec:
virtualhost:
fqdn: my-app.your-domain.com
tls:
secretName: my-app-tls-secret
includes:
- name: api-routes
namespace: api-team-namespace
conditions:
- prefix: /api
| Field |
Type |
Description |
name |
string |
Required. Name of the included HTTPProxy. It must not define virtualhost. |
namespace |
string |
Optional. Namespace of the included HTTPProxy. Default: the namespace of this HTTPProxy. |
conditions |
[]object |
Optional. Conditions added to every route of the included HTTPProxy. Only prefix, header and queryParameter are allowed, with at most one prefix. See Match Conditions. |
An include that points to a missing HTTPProxy makes the matching requests
fail with 502 Bad Gateway. An HTTPProxy without virtualhost that no root
includes is "orphaned" and is not used.
spec.tcpproxy
A tcpproxy forwards TCP connections for the virtual host to a Service. With
tls.secretName, the proxy terminates TLS and forwards the decrypted stream.
With tls.passthrough: true, it forwards the encrypted stream unchanged.
spec:
virtualhost:
fqdn: tcp.your-domain.com
tls:
passthrough: true
tcpproxy:
services:
- name: my-tcp-service
port: 8443
| Field |
Type |
Description |
services |
[]object |
Optional. The Service objects that receive the connections. Same fields as spec.routes[].services[]. |
include |
object |
Optional. Delegates the TCP proxy to another HTTPProxy. Fields: name (Required.) and namespace (default: this namespace). |
loadBalancerPolicy |
object |
Optional. Same fields as spec.routes[].loadBalancerPolicy. The Cookie and RequestHash strategies are not available. |
healthCheckPolicy |
object |
Optional. Active TCP health checks. Fields: intervalSeconds, timeoutSeconds, unhealthyThresholdCount, healthyThresholdCount, with the same meaning as for routes. |
Deprecated Fields
spec.tcpproxy.includes: use spec.tcpproxy.include instead.
validation.subjectName: use validation.subjectNames. The schema still
requires subjectName, so set both.
Status (status)
The Service Proxy writes the result of validating your HTTPProxy to its
status. kubectl get httpproxy shows currentStatus in the STATUS column.
| Field |
Type |
Description |
currentStatus |
string |
valid, invalid, orphaned (not included by any root), or NotReconciled before the first reconciliation. |
description |
string |
Short explanation of currentStatus, for example the reason a route is invalid. |
conditions |
[]object |
Contains a Valid condition. When it is False, its errors list (type, reason, message) explains why. warnings lists problems that do not invalidate the resource. |
loadBalancer.ingress |
[]object |
The ip or hostname where the Service Proxy receives traffic for this virtual host. |
The Service Proxy serves the valid parts of a partially invalid HTTPProxy.
Requests to a route that references a missing Service fail with
503 Service Unavailable.
- Network access: Pods that receive traffic from the Service Proxy must
carry the label
netic.dk/network-ingress: "contour". Without it, traffic
from the ingress controller is not allowed to reach your pods.
- TLS certificates: Create the
Secret referenced by
virtualhost.tls.secretName with the Certificates Service.
The secretName of the Certificate must match the secretName of the
HTTPProxy, and fqdn must be one of its dnsNames.
- DNS records: ExternalDNS creates the DNS record for
virtualhost.fqdn
automatically.
- Managed components: We deploy, scale and operate Contour and Envoy for
you. You only create
HTTPProxy resources in your own namespaces.
- Alternatives: The platform also supports the Gateway API and the standard
Ingress resource. See Exposing Applications to the Internet.
Further Reading