Contour HTTPProxy API

openapi: 3.1.0
info:
  title: Contour HTTPProxy API
  description: >-
    The Contour HTTPProxy API is a Kubernetes Custom Resource Definition that
    extends the standard Ingress API with advanced routing features including
    multi-team support, TLS delegation, weighted load balancing, and cross-namespace
    inclusion of routing configuration. HTTPProxy is Contour's primary ingress
    configuration resource, managed through the Kubernetes API server.
  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
externalDocs:
  description: Contour HTTPProxy Documentation
  url: https://projectcontour.io/docs/main/config/api/
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.
  - name: TLSCertificateDelegation
    description: >-
      Operations for managing TLSCertificateDelegation resources that allow
      certificates in one namespace to be used by HTTPProxy resources in other
      namespaces.
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
  /apis/projectcontour.io/v1/namespaces/{namespace}/tlscertificatedelegations:
    get:
      operationId: listNamespacedTLSCertificateDelegation
      summary: Contour List TLSCertificateDelegation resources
      description: >-
        Returns all TLSCertificateDelegation resources in the specified namespace.
        These resources allow TLS certificates to be delegated for use by
        HTTPProxy resources in other namespaces.
      tags:
        - TLSCertificateDelegation
      parameters:
        - $ref: '#/components/parameters/namespace'
      responses:
        '200':
          description: List of TLSCertificateDelegation resources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TLSCertificateDelegationList'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    post:
      operationId: createNamespacedTLSCertificateDelegation
      summary: Contour Create a TLSCertificateDelegation resource
      description: >-
        Creates a TLSCertificateDelegation resource that grants specified target
        namespaces permission to reference TLS certificates from this namespace
        in their HTTPProxy resources.
      tags:
        - TLSCertificateDelegation
      parameters:
        - $ref: '#/components/parameters/namespace'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TLSCertificateDelegation'
      responses:
        '201':
          description: TLSCertificateDelegation created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TLSCertificateDelegation'
        '400':
          description: Invalid specification
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
components:
  parameters:
    namespace:
      name: namespace
      in: path
      required: true
      description: The Kubernetes namespace of the resource.
      schema:
        type: string
    name:
      name: name
      in: path
      required: true
      description: The name of the resource.
      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
    fieldSelector:
      name: fieldSelector
      in: query
      required: false
      description: >-
        A selector to restrict the list of returned resources by their fields.
      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
    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
  schemas:
    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'
    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.
    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'
    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'
    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'
    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'
    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.
    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.
    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
    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
    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.
    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
    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.
    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
    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
    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.
    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'
    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'
    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.
    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'
    TLSCertificateDelegation:
      type: object
      description: >-
        Contour TLSCertificateDelegation resource granting other namespaces
        permission to reference TLS certificates from this namespace in their
        HTTPProxy resources.
      required:
        - apiVersion
        - kind
        - metadata
        - spec
      properties:
        apiVersion:
          type: string
          enum:
            - projectcontour.io/v1
        kind:
          type: string
          enum:
            - TLSCertificateDelegation
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        spec:
          type: object
          description: Specification for the delegation.
          properties:
            delegations:
              type: array
              description: List of delegations granting certificate access to namespaces.
              items:
                type: object
                required:
                  - secretName
                  - targetNamespaces
                properties:
                  secretName:
                    type: string
                    description: Name of the Kubernetes Secret containing the TLS certificate.
                  targetNamespaces:
                    type: array
                    description: >-
                      Namespaces permitted to reference this certificate. Use '*'
                      to allow all namespaces.
                    items:
                      type: string
    TLSCertificateDelegationList:
      type: object
      description: List of TLSCertificateDelegation resources.
      properties:
        apiVersion:
          type: string
        kind:
          type: string
        metadata:
          type: object
        items:
          type: array
          items:
            $ref: '#/components/schemas/TLSCertificateDelegation'
    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.
    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.