Operations for managing Contour HTTPProxy custom resources in a Kubernetes cluster. HTTPProxy resources define ingress routing rules for HTTP and HTTPS traffic.
openapi: 3.1.0
info:
title: Contour Gateway HTTPProxy API
description: Contour's implementation of the Kubernetes Gateway API, providing support for GatewayClass, Gateway, HTTPRoute, TLSRoute, and related resources. The Gateway API is the next-generation Kubernetes ingress standard, and Contour implements it alongside the legacy Ingress and HTTPProxy resources. All resources are managed through the Kubernetes API server using standard Kubernetes CRD patterns.
version: 1.30.0
contact:
name: Contour Community
url: https://projectcontour.io/community/
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{kubernetes-api-server}
description: Kubernetes API server
variables:
kubernetes-api-server:
default: localhost:6443
description: Address of the Kubernetes API server
tags:
- name: HTTPProxy
description: Operations for managing Contour HTTPProxy custom resources in a Kubernetes cluster. HTTPProxy resources define ingress routing rules for HTTP and HTTPS traffic.
paths:
/apis/projectcontour.io/v1/namespaces/{namespace}/httpproxies:
get:
operationId: listNamespacedHTTPProxy
summary: Contour List HTTPProxy resources in a namespace
description: Returns a list of all HTTPProxy custom resources in the specified Kubernetes namespace. Results can be filtered using label selectors and field selectors.
tags:
- HTTPProxy
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/labelSelector'
- $ref: '#/components/parameters/fieldSelector'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/continueToken'
responses:
'200':
description: Successfully retrieved list of HTTPProxy resources
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPProxyList'
'401':
description: Unauthorized - authentication required
'403':
description: Forbidden - insufficient permissions
post:
operationId: createNamespacedHTTPProxy
summary: Contour Create an HTTPProxy resource
description: Creates a new HTTPProxy custom resource in the specified namespace. The HTTPProxy defines virtual hosts, routing rules, TLS configuration, and load balancing behavior for inbound HTTP/HTTPS traffic.
tags:
- HTTPProxy
parameters:
- $ref: '#/components/parameters/namespace'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPProxy'
responses:
'201':
description: HTTPProxy resource created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPProxy'
'400':
description: Invalid HTTPProxy specification
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'401':
description: Unauthorized
'403':
description: Forbidden
'409':
description: HTTPProxy with this name already exists
/apis/projectcontour.io/v1/namespaces/{namespace}/httpproxies/{name}:
get:
operationId: readNamespacedHTTPProxy
summary: Contour Get a specific HTTPProxy resource
description: Returns the specified HTTPProxy custom resource from the given namespace, including its current status, observed generation, and condition information.
tags:
- HTTPProxy
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: HTTPProxy resource retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPProxy'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: HTTPProxy resource not found
put:
operationId: replaceNamespacedHTTPProxy
summary: Contour Replace an HTTPProxy resource
description: Replaces the entire HTTPProxy resource with the provided specification. The resourceVersion in the metadata must match the current version to prevent conflicting updates.
tags:
- HTTPProxy
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPProxy'
responses:
'200':
description: HTTPProxy resource updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPProxy'
'400':
description: Invalid HTTPProxy specification
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: HTTPProxy resource not found
'409':
description: Conflict - resource version mismatch
patch:
operationId: patchNamespacedHTTPProxy
summary: Contour Partially update an HTTPProxy resource
description: Applies a partial update to the specified HTTPProxy resource using JSON Merge Patch or Strategic Merge Patch format.
tags:
- HTTPProxy
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
requestBody:
required: true
content:
application/merge-patch+json:
schema:
type: object
application/strategic-merge-patch+json:
schema:
type: object
responses:
'200':
description: HTTPProxy resource patched successfully
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPProxy'
'400':
description: Invalid patch
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: HTTPProxy resource not found
delete:
operationId: deleteNamespacedHTTPProxy
summary: Contour Delete an HTTPProxy resource
description: Deletes the specified HTTPProxy resource from the namespace. Contour will stop configuring Envoy for the routes defined in this resource.
tags:
- HTTPProxy
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: HTTPProxy resource deleted
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: HTTPProxy resource not found
/apis/projectcontour.io/v1/httpproxies:
get:
operationId: listHTTPProxyAllNamespaces
summary: Contour List HTTPProxy resources across all namespaces
description: Returns all HTTPProxy custom resources across all namespaces in the cluster. Useful for cluster-wide visibility into all ingress configurations managed by Contour.
tags:
- HTTPProxy
parameters:
- $ref: '#/components/parameters/labelSelector'
- $ref: '#/components/parameters/fieldSelector'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/continueToken'
responses:
'200':
description: List of all HTTPProxy resources across namespaces
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPProxyList'
'401':
description: Unauthorized
'403':
description: Forbidden
components:
schemas:
TCPProxy:
type: object
description: TCP proxy configuration for passthrough TLS or TCP routing.
properties:
services:
type: array
description: Backend services for TCP proxying.
items:
$ref: '#/components/schemas/Service'
include:
$ref: '#/components/schemas/Include'
RetryPolicy:
type: object
description: Retry configuration for failed upstream requests.
properties:
count:
type: integer
description: Number of retry attempts.
minimum: 0
perTryTimeout:
type: string
description: Timeout per retry attempt as a duration string.
retriableStatusCodes:
type: array
description: HTTP status codes that trigger a retry.
items:
type: integer
DetailedCondition:
type: object
description: Detailed condition providing status information about the HTTPProxy.
properties:
type:
type: string
description: Type of the condition.
status:
type: string
description: Status of the condition.
enum:
- 'True'
- 'False'
- Unknown
observedGeneration:
type: integer
format: int64
description: Generation of the resource when this condition was set.
lastTransitionTime:
type: string
format: date-time
description: Time when the condition last changed.
reason:
type: string
description: Short reason code for the condition.
message:
type: string
description: Human-readable details about the condition.
errors:
type: array
description: List of error sub-conditions.
items:
$ref: '#/components/schemas/SubCondition'
warnings:
type: array
description: List of warning sub-conditions.
items:
$ref: '#/components/schemas/SubCondition'
Service:
type: object
description: A backend Kubernetes service to route traffic to.
required:
- name
- port
properties:
name:
type: string
description: Name of the Kubernetes Service.
port:
type: integer
description: Port number of the Kubernetes Service.
minimum: 1
maximum: 65535
weight:
type: integer
description: Relative weight for traffic distribution when multiple services are specified. Defaults to 1.
minimum: 0
healthPort:
type: integer
description: Port to use for health checking, if different from the service port.
protocol:
type: string
description: Protocol to use when connecting to the service.
enum:
- h2
- h2c
- tls
VirtualHost:
type: object
description: Defines the virtual host for this HTTPProxy, including its FQDN and TLS configuration. Only present on root HTTPProxy resources.
required:
- fqdn
properties:
fqdn:
type: string
description: Fully qualified domain name of the virtual host.
example: app.example.com
tls:
$ref: '#/components/schemas/TLS'
rateLimitPolicy:
$ref: '#/components/schemas/RateLimitPolicy'
corsPolicy:
$ref: '#/components/schemas/CORSPolicy'
authorization:
$ref: '#/components/schemas/AuthorizationServer'
SubCondition:
type: object
description: A sub-condition providing additional detail about an error or warning.
properties:
type:
type: string
description: Type of the sub-condition.
status:
type: string
description: Status of the sub-condition.
reason:
type: string
description: Short reason code.
message:
type: string
description: Human-readable details.
CORSPolicy:
type: object
description: CORS policy configuration for the virtual host.
properties:
allowCredentials:
type: boolean
description: Whether to allow credentials in cross-origin requests.
allowOrigin:
type: array
description: Allowed origins for CORS requests.
items:
type: string
allowMethods:
type: array
description: Allowed HTTP methods for CORS requests.
items:
type: string
allowHeaders:
type: array
description: Allowed request headers for CORS requests.
items:
type: string
exposeHeaders:
type: array
description: Response headers to expose to browser clients.
items:
type: string
maxAge:
type: string
description: Duration to cache preflight responses.
HTTPProxySpec:
type: object
description: Specification for the HTTPProxy defining routing behavior.
properties:
virtualhost:
$ref: '#/components/schemas/VirtualHost'
includes:
type: array
description: List of HTTPProxy resources from the same or other namespaces to include as sub-routes under this proxy.
items:
$ref: '#/components/schemas/Include'
routes:
type: array
description: List of routing rules for this HTTPProxy.
items:
$ref: '#/components/schemas/Route'
tcpproxy:
$ref: '#/components/schemas/TCPProxy'
ingressClassName:
type: string
description: Name of the IngressClass to use for this HTTPProxy.
AuthorizationServer:
type: object
description: External authorization server configuration for the virtual host.
properties:
extensionRef:
type: object
description: Reference to an ExtensionService providing authorization.
properties:
name:
type: string
description: Name of the ExtensionService resource.
namespace:
type: string
description: Namespace of the ExtensionService resource.
authPolicy:
type: object
description: Authorization policy settings.
properties:
disabled:
type: boolean
context:
type: object
additionalProperties:
type: string
Status:
type: object
description: Standard Kubernetes Status response for error conditions.
properties:
apiVersion:
type: string
kind:
type: string
enum:
- Status
message:
type: string
description: Human-readable description of the error.
reason:
type: string
description: Machine-readable reason for the error.
code:
type: integer
description: HTTP status code.
HTTPProxy:
type: object
description: Contour HTTPProxy custom resource defining advanced ingress routing rules for HTTP and HTTPS traffic entering the cluster.
required:
- apiVersion
- kind
- metadata
- spec
properties:
apiVersion:
type: string
description: API version of the resource.
enum:
- projectcontour.io/v1
kind:
type: string
description: Resource kind.
enum:
- HTTPProxy
metadata:
$ref: '#/components/schemas/ObjectMeta'
spec:
$ref: '#/components/schemas/HTTPProxySpec'
status:
$ref: '#/components/schemas/HTTPProxyStatus'
HTTPProxyStatus:
type: object
description: Observed status of the HTTPProxy resource as reported by Contour.
properties:
currentStatus:
type: string
description: Current processing status of the HTTPProxy. Valid statuses are 'valid', 'invalid', and 'orphaned'.
enum:
- valid
- invalid
- orphaned
description:
type: string
description: Human-readable description of the current status.
loadBalancer:
type: object
description: LoadBalancer ingress endpoints assigned to this HTTPProxy.
conditions:
type: array
description: Detailed condition information for this HTTPProxy.
items:
$ref: '#/components/schemas/DetailedCondition'
QueryParameterMatchCondition:
type: object
description: A condition matching on HTTP query parameters.
required:
- name
properties:
name:
type: string
description: Query parameter name to match.
exact:
type: string
description: Exact value the query parameter must equal.
prefix:
type: string
description: Prefix value the query parameter must start with.
suffix:
type: string
description: Suffix value the query parameter must end with.
contains:
type: string
description: Value the query parameter must contain.
present:
type: boolean
description: If true, the query parameter must be present.
TimeoutPolicy:
type: object
description: Timeout configuration for requests on this route.
properties:
response:
type: string
description: Timeout for a complete response from the backend.
idle:
type: string
description: Timeout for idle connections.
idleConnection:
type: string
description: Timeout for idle backend connections.
HeaderMatchCondition:
type: object
description: A condition matching on HTTP request headers.
required:
- name
properties:
name:
type: string
description: HTTP header name to match.
present:
type: boolean
description: If true, the header must be present.
contains:
type: string
description: Value the header must contain.
notcontains:
type: string
description: Value the header must not contain.
exact:
type: string
description: Exact value the header must equal.
notexact:
type: string
description: Value the header must not equal.
HTTPProxyList:
type: object
description: List of HTTPProxy resources.
required:
- apiVersion
- kind
- items
properties:
apiVersion:
type: string
kind:
type: string
enum:
- HTTPProxyList
metadata:
type: object
properties:
resourceVersion:
type: string
continue:
type: string
items:
type: array
description: List of HTTPProxy resources.
items:
$ref: '#/components/schemas/HTTPProxy'
TLS:
type: object
description: TLS configuration for the virtual host.
properties:
secretName:
type: string
description: Name of the Kubernetes Secret containing the TLS certificate and private key. May reference a Secret in another namespace if TLSCertificateDelegation is configured.
minimumProtocolVersion:
type: string
description: Minimum TLS protocol version to negotiate.
enum:
- '1.2'
- '1.3'
passthrough:
type: boolean
description: If true, TLS termination is done at the backend service.
enableFallbackCertificate:
type: boolean
description: If true, a default fallback certificate is served for SNI names that don't match any configured virtual host.
Include:
type: object
description: Reference to another HTTPProxy resource to include as child routes, optionally in another namespace.
required:
- name
properties:
name:
type: string
description: Name of the HTTPProxy resource to include.
namespace:
type: string
description: Namespace of the included HTTPProxy. Defaults to the current namespace.
conditions:
type: array
description: Conditions that must match for this include to apply.
items:
$ref: '#/components/schemas/MatchCondition'
HeadersPolicy:
type: object
description: Policy for manipulating HTTP request or response headers.
properties:
set:
type: array
description: Headers to set on requests or responses.
items:
$ref: '#/components/schemas/HeaderValue'
remove:
type: array
description: Header names to remove from requests or responses.
items:
type: string
RateLimitPolicy:
type: object
description: Rate limiting configuration applied to this route or virtual host.
properties:
local:
type: object
description: Local rate limiting using Envoy's built-in token bucket algorithm.
properties:
requests:
type: integer
description: Maximum number of requests per unit.
unit:
type: string
description: Time unit for the rate limit.
enum:
- second
- minute
- hour
burst:
type: integer
description: Maximum number of burst requests above the rate limit.
global:
type: object
description: Global rate limiting via an external rate limit service.
properties:
descriptors:
type: array
description: Descriptors sent to the rate limit service.
items:
type: object
HeaderValue:
type: object
description: A header name-value pair.
required:
- name
- value
properties:
name:
type: string
description: HTTP header name.
value:
type: string
description: HTTP header value.
MatchCondition:
type: object
description: A condition that must match for a route or include to apply.
properties:
prefix:
type: string
description: URL path prefix that must match.
example: /api
header:
$ref: '#/components/schemas/HeaderMatchCondition'
queryParameter:
$ref: '#/components/schemas/QueryParameterMatchCondition'
Route:
type: object
description: A single routing rule mapping request conditions to backend services.
properties:
conditions:
type: array
description: Match conditions for this route.
items:
$ref: '#/components/schemas/MatchCondition'
services:
type: array
description: Backend services to route matching requests to.
items:
$ref: '#/components/schemas/Service'
enableWebsockets:
type: boolean
description: If true, upgrades HTTP connections to WebSocket connections.
permitInsecure:
type: boolean
description: If true, allows this route to respond to non-TLS requests when the parent virtual host has TLS enabled.
retryPolicy:
$ref: '#/components/schemas/RetryPolicy'
timeoutPolicy:
$ref: '#/components/schemas/TimeoutPolicy'
rateLimitPolicy:
$ref: '#/components/schemas/RateLimitPolicy'
requestHeadersPolicy:
$ref: '#/components/schemas/HeadersPolicy'
responseHeadersPolicy:
$ref: '#/components/schemas/HeadersPolicy'
ObjectMeta:
type: object
description: Standard Kubernetes object metadata.
required:
- name
properties:
name:
type: string
description: Name of the resource, unique within the namespace.
namespace:
type: string
description: Namespace the resource belongs to.
labels:
type: object
additionalProperties:
type: string
description: Map of string keys and values for organizing resources.
annotations:
type: object
additionalProperties:
type: string
description: Map of non-identifying metadata for the resource.
resourceVersion:
type: string
description: An opaque value representing the internal version of the resource, used for optimistic concurrency control.
generation:
type: integer
format: int64
description: Sequence number representing the generation of the desired state.
uid:
type: string
description: Unique identifier assigned by the Kubernetes system.
creationTimestamp:
type: string
format: date-time
description: Timestamp when the resource was created.
parameters:
fieldSelector:
name: fieldSelector
in: query
required: false
description: A selector to restrict the list of returned resources by their fields.
schema:
type: string
name:
name: name
in: path
required: true
description: The name of the resource.
schema:
type: string
limit:
name: limit
in: query
required: false
description: Maximum number of responses to return per page. If there are additional results, a continue token is returned.
schema:
type: integer
minimum: 1
namespace:
name: namespace
in: path
required: true
description: The Kubernetes namespace of the resource.
schema:
type: string
continueToken:
name: continue
in: query
required: false
description: A continuation token for paginating through large result sets, returned from a previous list call.
schema:
type: string
labelSelector:
name: labelSelector
in: query
required: false
description: A selector to restrict the list of returned resources by their labels. Defaults to everything.
schema:
type: string
externalDocs:
description: Contour Gateway API Documentation
url: https://projectcontour.io/docs/1.30/config/gateway-api/