Skip to content

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.

Header 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.

Header Policies

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.

Platform Notes

  • 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