Namespace-scoped resources that describe network infrastructure instances that route traffic. Each Gateway is associated with a GatewayClass and defines listeners for inbound traffic.
openapi: 3.1.0
info:
title: Contour Gateway 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: Gateway
description: Namespace-scoped resources that describe network infrastructure instances that route traffic. Each Gateway is associated with a GatewayClass and defines listeners for inbound traffic.
paths:
/apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/gateways:
get:
operationId: listNamespacedGateway
summary: Contour List Gateway resources in a namespace
description: Returns all Gateway resources in the specified namespace. Each Gateway describes network infrastructure with one or more listeners for inbound traffic, associated with a GatewayClass.
tags:
- Gateway
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/labelSelector'
responses:
'200':
description: List of Gateway resources
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayList'
'401':
description: Unauthorized
'403':
description: Forbidden
post:
operationId: createNamespacedGateway
summary: Contour Create a Gateway resource
description: Creates a new Gateway resource in the specified namespace. Contour will provision an Envoy instance to handle traffic according to the Gateway's listener configuration.
tags:
- Gateway
parameters:
- $ref: '#/components/parameters/namespace'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Gateway'
responses:
'201':
description: Gateway created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Gateway'
'400':
description: Invalid Gateway specification
'401':
description: Unauthorized
'403':
description: Forbidden
'409':
description: Gateway with this name already exists
/apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/gateways/{name}:
get:
operationId: readNamespacedGateway
summary: Contour Get a specific Gateway resource
description: Returns the specified Gateway resource, including its listeners, addresses, and current status as reported by the Contour controller.
tags:
- Gateway
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: Gateway resource
content:
application/json:
schema:
$ref: '#/components/schemas/Gateway'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Gateway not found
put:
operationId: replaceNamespacedGateway
summary: Contour Replace a Gateway resource
description: Replaces the entire Gateway resource with the provided specification.
tags:
- Gateway
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Gateway'
responses:
'200':
description: Gateway updated
content:
application/json:
schema:
$ref: '#/components/schemas/Gateway'
'400':
description: Invalid specification
'401':
description: Unauthorized
'404':
description: Gateway not found
delete:
operationId: deleteNamespacedGateway
summary: Contour Delete a Gateway resource
description: Deletes the specified Gateway resource. Contour will decommission the associated Envoy infrastructure.
tags:
- Gateway
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: Gateway deleted
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Gateway not found
components:
schemas:
SecretObjectReference:
type: object
description: A reference to a Kubernetes Secret containing a TLS certificate.
required:
- name
properties:
group:
type: string
kind:
type: string
default: Secret
namespace:
type: string
name:
type: string
description: Name of the Secret.
Gateway:
type: object
description: Namespace-scoped resource describing a network infrastructure instance with one or more listeners for handling inbound traffic.
required:
- apiVersion
- kind
- metadata
- spec
properties:
apiVersion:
type: string
enum:
- gateway.networking.k8s.io/v1
kind:
type: string
enum:
- Gateway
metadata:
$ref: '#/components/schemas/ObjectMeta'
spec:
type: object
description: Gateway specification.
required:
- gatewayClassName
properties:
gatewayClassName:
type: string
description: Name of the GatewayClass this Gateway belongs to.
listeners:
type: array
description: List of listeners for accepting inbound traffic.
items:
$ref: '#/components/schemas/Listener'
addresses:
type: array
description: Requested network addresses for the Gateway.
items:
type: object
properties:
type:
type: string
enum:
- IPAddress
- Hostname
value:
type: string
status:
type: object
description: Status of the Gateway as reported by the controller.
properties:
addresses:
type: array
description: Network addresses assigned to the Gateway.
items:
type: object
properties:
type:
type: string
value:
type: string
conditions:
type: array
items:
$ref: '#/components/schemas/Condition'
listeners:
type: array
items:
$ref: '#/components/schemas/ListenerStatus'
Listener:
type: object
description: A listener on the Gateway accepting inbound connections.
required:
- name
- port
- protocol
properties:
name:
type: string
description: Unique name for this listener within the Gateway.
hostname:
type: string
description: Hostname that this listener is bound to. Requests with matching SNI or Host header are routed to this listener.
port:
type: integer
description: Network port number the listener binds to.
minimum: 1
maximum: 65535
protocol:
type: string
description: Network protocol the listener accepts.
enum:
- HTTP
- HTTPS
- TLS
- TCP
tls:
type: object
description: TLS configuration for HTTPS and TLS listeners.
properties:
mode:
type: string
enum:
- Terminate
- Passthrough
certificateRefs:
type: array
items:
$ref: '#/components/schemas/SecretObjectReference'
allowedRoutes:
type: object
description: Defines which routes are allowed to attach to this listener.
properties:
namespaces:
type: object
properties:
from:
type: string
enum:
- All
- Same
- Selector
selector:
type: object
kinds:
type: array
items:
type: object
properties:
group:
type: string
kind:
type: string
ListenerStatus:
type: object
description: Status of a Gateway listener.
properties:
name:
type: string
description: Name of the listener.
supportedKinds:
type: array
description: Route kinds supported by this listener.
items:
type: object
attachedRoutes:
type: integer
description: Number of routes currently attached to this listener.
conditions:
type: array
items:
$ref: '#/components/schemas/Condition'
Condition:
type: object
description: A standard Kubernetes condition indicating the state of a resource.
required:
- type
- status
properties:
type:
type: string
description: Type of the condition.
status:
type: string
enum:
- 'True'
- 'False'
- Unknown
description: Status of the condition.
observedGeneration:
type: integer
format: int64
lastTransitionTime:
type: string
format: date-time
description: Time when this condition last changed.
reason:
type: string
description: Short reason code for the condition.
message:
type: string
description: Human-readable details about this condition.
GatewayList:
type: object
description: List of Gateway resources.
properties:
apiVersion:
type: string
kind:
type: string
items:
type: array
items:
$ref: '#/components/schemas/Gateway'
ObjectMeta:
type: object
description: Standard Kubernetes object metadata.
required:
- name
properties:
name:
type: string
description: Name of the resource.
namespace:
type: string
description: Namespace the resource belongs to.
labels:
type: object
additionalProperties:
type: string
description: Labels for organizing and selecting resources.
annotations:
type: object
additionalProperties:
type: string
description: Annotations for non-identifying metadata.
resourceVersion:
type: string
description: Internal version for optimistic concurrency.
generation:
type: integer
format: int64
uid:
type: string
creationTimestamp:
type: string
format: date-time
parameters:
name:
name: name
in: path
required: true
description: The name of the resource.
schema:
type: string
labelSelector:
name: labelSelector
in: query
required: false
description: Label selector to filter resources.
schema:
type: string
namespace:
name: namespace
in: path
required: true
description: The Kubernetes namespace of the resource.
schema:
type: string
externalDocs:
description: Contour Gateway API Documentation
url: https://projectcontour.io/docs/1.30/config/gateway-api/