openapi: 3.1.0
info:
title: Emissary-Ingress Configuration API
description: >-
Emissary-Ingress is a CNCF incubating Kubernetes-native API gateway and
ingress controller built on the Envoy proxy. It is configured through
Kubernetes Custom Resource Definitions (CRDs) including Mapping for
request routing, Host for domain and TLS management, TLSContext for TLS
termination settings, RateLimitService for delegating rate limiting to
external services, and AuthService for external authentication. All
resources are managed through the Kubernetes API server using standard
CRUD operations.
version: '3.9.0'
contact:
name: Emissary-Ingress Community
url: https://www.getambassador.io/community
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
description: Emissary-Ingress Documentation
url: https://www.getambassador.io/docs/emissary/
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: AuthService
description: >-
Operations for managing AuthService custom resources that configure
external authentication and authorization services. Emissary-Ingress
will call the configured auth service before forwarding requests to
upstream services.
- name: Host
description: >-
Operations for managing Host custom resources that configure domain
names, TLS certificate management via ACME/Let's Encrypt, and
TLS termination for ingress traffic. A Host binds a hostname to
TLS configuration and controls HTTPS redirect behavior.
- name: Mapping
description: >-
Operations for managing Mapping custom resources that define routing
rules for inbound HTTP/HTTPS traffic. A Mapping connects a URL path
or prefix to a backend Kubernetes service with support for header
matching, rewriting, timeouts, retries, and traffic weighting.
- name: RateLimitService
description: >-
Operations for managing RateLimitService custom resources that
configure integration with external rate limiting services compatible
with the Envoy rate limit API.
- name: TLSContext
description: >-
Operations for managing TLSContext custom resources that define
reusable TLS configuration including certificates, cipher suites,
minimum protocol versions, and client certificate validation settings.
paths:
/apis/getambassador.io/v3alpha1/namespaces/{namespace}/mappings:
get:
operationId: listNamespacedMapping
summary: Emissary-Ingress List Mapping resources in a namespace
description: >-
Returns a list of all Mapping custom resources in the specified
Kubernetes namespace. Mappings define how inbound HTTP/HTTPS requests
are routed to backend services based on URL prefix, headers, and
other match criteria.
tags:
- Mapping
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 Mapping resources
content:
application/json:
schema:
$ref: '#/components/schemas/MappingList'
'401':
description: Unauthorized - authentication required
'403':
description: Forbidden - insufficient permissions
post:
operationId: createNamespacedMapping
summary: Emissary-Ingress Create a Mapping resource
description: >-
Creates a new Mapping custom resource in the specified namespace.
The Mapping defines routing rules including the URL prefix, target
service, rewrite rules, timeout policies, retry policies, CORS
settings, and traffic weighting for canary or A/B deployments.
tags:
- Mapping
parameters:
- $ref: '#/components/parameters/namespace'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Mapping'
responses:
'201':
description: Mapping resource created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Mapping'
'400':
description: Invalid Mapping specification
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'401':
description: Unauthorized
'403':
description: Forbidden
'409':
description: Mapping with this name already exists
/apis/getambassador.io/v3alpha1/namespaces/{namespace}/mappings/{name}:
get:
operationId: readNamespacedMapping
summary: Emissary-Ingress Get a specific Mapping resource
description: >-
Returns the specified Mapping custom resource from the given namespace,
including its current status, route configuration, and observed
generation information.
tags:
- Mapping
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: Mapping resource retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Mapping'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Mapping resource not found
put:
operationId: replaceNamespacedMapping
summary: Emissary-Ingress Replace a Mapping resource
description: >-
Replaces the entire Mapping resource with the provided specification.
The resourceVersion in the metadata must match the current version
to prevent conflicting concurrent updates.
tags:
- Mapping
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Mapping'
responses:
'200':
description: Mapping resource updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Mapping'
'400':
description: Invalid Mapping specification
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Mapping resource not found
'409':
description: Conflict - resource version mismatch
patch:
operationId: patchNamespacedMapping
summary: Emissary-Ingress Partially update a Mapping resource
description: >-
Applies a partial update to the specified Mapping resource using
JSON Merge Patch or Strategic Merge Patch format.
tags:
- Mapping
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: Mapping resource patched successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Mapping'
'400':
description: Invalid patch
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Mapping resource not found
delete:
operationId: deleteNamespacedMapping
summary: Emissary-Ingress Delete a Mapping resource
description: >-
Deletes the specified Mapping resource. Emissary-Ingress will remove
the corresponding routing rule from Envoy configuration after the
resource is deleted.
tags:
- Mapping
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: Mapping resource deleted successfully
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Mapping resource not found
/apis/getambassador.io/v3alpha1/mappings:
get:
operationId: listMappingAllNamespaces
summary: Emissary-Ingress List Mapping resources across all namespaces
description: >-
Returns all Mapping custom resources across all namespaces in the
cluster. Useful for cluster-wide visibility into all routing
configurations managed by Emissary-Ingress.
tags:
- Mapping
parameters:
- $ref: '#/components/parameters/labelSelector'
- $ref: '#/components/parameters/fieldSelector'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/continueToken'
responses:
'200':
description: List of all Mapping resources across namespaces
content:
application/json:
schema:
$ref: '#/components/schemas/MappingList'
'401':
description: Unauthorized
'403':
description: Forbidden
/apis/getambassador.io/v3alpha1/namespaces/{namespace}/hosts:
get:
operationId: listNamespacedHost
summary: Emissary-Ingress List Host resources in a namespace
description: >-
Returns a list of all Host custom resources in the specified namespace.
Host resources configure domain names, ACME-based TLS certificate
provisioning, and TLS termination settings for inbound traffic.
tags:
- Host
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 Host resources
content:
application/json:
schema:
$ref: '#/components/schemas/HostList'
'401':
description: Unauthorized
'403':
description: Forbidden
post:
operationId: createNamespacedHost
summary: Emissary-Ingress Create a Host resource
description: >-
Creates a new Host custom resource in the specified namespace. The Host
defines the hostname, TLS certificate management via ACME, and TLS
termination configuration for accepting inbound HTTPS traffic.
tags:
- Host
parameters:
- $ref: '#/components/parameters/namespace'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Host'
responses:
'201':
description: Host resource created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Host'
'400':
description: Invalid Host specification
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'401':
description: Unauthorized
'403':
description: Forbidden
'409':
description: Host with this name already exists
/apis/getambassador.io/v3alpha1/namespaces/{namespace}/hosts/{name}:
get:
operationId: readNamespacedHost
summary: Emissary-Ingress Get a specific Host resource
description: >-
Returns the specified Host custom resource from the given namespace,
including its current certificate provisioning status and TLS
configuration.
tags:
- Host
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: Host resource retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Host'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Host resource not found
put:
operationId: replaceNamespacedHost
summary: Emissary-Ingress Replace a Host resource
description: >-
Replaces the entire Host resource with the provided specification.
Changes to the TLS configuration may trigger certificate
re-provisioning via the ACME protocol.
tags:
- Host
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Host'
responses:
'200':
description: Host resource updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Host'
'400':
description: Invalid Host specification
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Host resource not found
delete:
operationId: deleteNamespacedHost
summary: Emissary-Ingress Delete a Host resource
description: >-
Deletes the specified Host resource. Emissary-Ingress will stop
accepting traffic for the corresponding hostname after deletion.
tags:
- Host
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: Host resource deleted successfully
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Host resource not found
/apis/getambassador.io/v3alpha1/namespaces/{namespace}/tlscontexts:
get:
operationId: listNamespacedTLSContext
summary: Emissary-Ingress List TLSContext resources in a namespace
description: >-
Returns all TLSContext custom resources in the specified namespace.
TLSContext resources define reusable TLS configuration including
certificates, protocols, cipher suites, and mutual TLS settings
that can be referenced by Mapping and Host resources.
tags:
- TLSContext
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/labelSelector'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/continueToken'
responses:
'200':
description: Successfully retrieved list of TLSContext resources
content:
application/json:
schema:
$ref: '#/components/schemas/TLSContextList'
'401':
description: Unauthorized
'403':
description: Forbidden
post:
operationId: createNamespacedTLSContext
summary: Emissary-Ingress Create a TLSContext resource
description: >-
Creates a new TLSContext custom resource in the specified namespace
defining TLS termination settings including the certificate secret,
minimum protocol version, cipher suite restrictions, and client
certificate validation options.
tags:
- TLSContext
parameters:
- $ref: '#/components/parameters/namespace'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TLSContext'
responses:
'201':
description: TLSContext resource created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/TLSContext'
'400':
description: Invalid TLSContext specification
'401':
description: Unauthorized
'403':
description: Forbidden
/apis/getambassador.io/v3alpha1/namespaces/{namespace}/tlscontexts/{name}:
get:
operationId: readNamespacedTLSContext
summary: Emissary-Ingress Get a specific TLSContext resource
description: >-
Returns the specified TLSContext custom resource from the given
namespace, including its certificate configuration and protocol
settings.
tags:
- TLSContext
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: TLSContext resource retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/TLSContext'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: TLSContext resource not found
delete:
operationId: deleteNamespacedTLSContext
summary: Emissary-Ingress Delete a TLSContext resource
description: >-
Deletes the specified TLSContext resource. Any Mappings or Hosts
referencing this TLSContext will fall back to default TLS settings.
tags:
- TLSContext
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/name'
responses:
'200':
description: TLSContext resource deleted successfully
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: TLSContext resource not found
/apis/getambassador.io/v3alpha1/namespaces/{namespace}/ratelimitservices:
get:
operationId: listNamespacedRateLimitService
summary: Emissary-Ingress List RateLimitService resources in a namespace
description: >-
Returns all RateLimitService custom resources in the specified
namespace. These resources configure integration with external
rate limiting services that implement the Envoy rate limit gRPC API.
tags:
- RateLimitService
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/labelSelector'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/continueToken'
responses:
'200':
description: Successfully retrieved list of RateLimitService resources
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitServiceList'
'401':
description: Unauthorized
'403':
description: Forbidden
post:
operationId: createNamespacedRateLimitService
summary: Emissary-Ingress Create a RateLimitService resource
description: >-
Creates a new RateLimitService custom resource pointing to an external
rate limiting service. Emissary-Ingress will consult this service for
rate limit decisions on all requests that include rate limit labels
in their Mapping configuration.
tags:
- RateLimitService
parameters:
- $ref: '#/components/parameters/namespace'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitService'
responses:
'201':
description: RateLimitService resource created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitService'
'400':
description: Invalid RateLimitService specification
'401':
description: Unauthorized
'403':
description: Forbidden
/apis/getambassador.io/v3alpha1/namespaces/{namespace}/authservices:
get:
operationId: listNamespacedAuthService
summary: Emissary-Ingress List AuthService resources in a namespace
description: >-
Returns all AuthService custom resources in the specified namespace.
AuthService resources configure an external authentication and
authorization service that Emissary-Ingress calls before forwarding
requests to upstream backend services.
tags:
- AuthService
parameters:
- $ref: '#/components/parameters/namespace'
- $ref: '#/components/parameters/labelSelector'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/continueToken'
responses:
'200':
description: Successfully retrieved list of AuthService resources
content:
application/json:
schema:
$ref: '#/components/schemas/AuthServiceList'
'401':
description: Unauthorized
'403':
description: Forbidden
post:
operationId: createNamespacedAuthService
summary: Emissary-Ingress Create an AuthService resource
description: >-
Creates a new AuthService custom resource in the specified namespace
configuring the external authentication service URL, protocol, timeout,
allowed request headers, and allowed authorization headers.
tags:
- AuthService
parameters:
- $ref: '#/components/parameters/namespace'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthService'
responses:
'201':
description: AuthService resource created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/AuthService'
'400':
description: Invalid AuthService 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:
Mapping:
type: object
description: >-
Emissary-Ingress Mapping custom resource that defines how inbound
HTTP/HTTPS requests are routed to backend Kubernetes services. A
Mapping matches on a URL prefix (and optionally headers, method, or
hostname) and forwards the request to the configured service with
support for rewriting, retries, timeouts, CORS, traffic weighting,
and shadow traffic.
required:
- apiVersion
- kind
- metadata
- spec
properties:
apiVersion:
type: string
description: API version of the resource.
enum:
- getambassador.io/v3alpha1
kind:
type: string
description: Resource kind.
enum:
- Mapping
metadata:
$ref: '#/components/schemas/ObjectMeta'
spec:
$ref: '#/components/schemas/MappingSpec'
status:
$ref: '#/components/schemas/MappingStatus'
MappingSpec:
type: object
description: Specification for the Mapping defining routing behavior.
required:
- prefix
- service
properties:
prefix:
type: string
description: >-
URL prefix that incoming requests must match for this Mapping to
apply. All requests whose path starts with this prefix will be
forwarded to the configured service.
example: /api/v1/
service:
type: string
description: >-
Name of the Kubernetes service (and optional port) to forward
matching requests to. Format is 'service-name' or
'service-name:port'.
example: my-service:8080
hostname:
type: string
description: >-
Hostname that requests must match in addition to the prefix.
Supports glob patterns such as '*.example.com'.
host:
type: string
description: >-
Deprecated. Use hostname instead. The Host header value requests
must present to match this Mapping.
method:
type: string
description: HTTP method that requests must use to match this Mapping.
enum:
- GET
- POST
- PUT
- PATCH
- DELETE
- HEAD
- OPTIONS
headers:
type: object
description: >-
HTTP request headers that must be present with the given values
for this Mapping to match. Key is header name, value is the
required value.
additionalProperties:
type: string
regex_headers:
type: object
description: >-
HTTP request headers that must match the given regular expressions.
Key is header name, value is the regex pattern.
additionalProperties:
type: string
rewrite:
type: string
description: >-
URL prefix to substitute for the matched prefix before forwarding
the request to the upstream service. Set to empty string to strip
the prefix entirely.
example: /
timeout_ms:
type: integer
description: >-
Overall timeout in milliseconds for requests on this Mapping.
Defaults to 3000ms.
minimum: 0
connect_timeout_ms:
type: integer
description: >-
Timeout in milliseconds for establishing a connection to the
upstream service. Defaults to 3000ms.
minimum: 0
idle_timeout_ms:
type: integer
description: >-
Timeout in milliseconds for idle connections to the upstream
service.
minimum: 0
retries:
$ref: '#/components/schemas/RetryPolicy'
cors:
$ref: '#/components/schemas/CORSPolicy'
weight:
type: integer
description: >-
Relative weight for distributing traffic when multiple Mappings
match the same prefix. Used to implement canary deployments.
minimum: 0
maximum: 100
shadow:
type: boolean
description: >-
If true, traffic is mirrored to this Mapping's service but
responses are discarded. Used for dark launch testing.
tls:
type: string
description: >-
Name of a TLSContext resource to use when connecting to the
upstream service over TLS.
load_balancer:
$ref: '#/components/schemas/LoadBalancer'
circuit_breakers:
type: array
description: Circuit breaker configuration for the upstream service connection.
items:
$ref: '#/components/schemas/CircuitBreaker'
add_request_headers:
type: object
description: >-
Headers to add to all forwarded requests. Key is header name,
value is the value to set.
additionalProperties:
type: string
remove_request_headers:
type: array
description: Header names to remove from all forwarded requests.
items:
type: string
add_response_headers:
type: object
description: >-
Headers to add to all responses. Key is header name, value is
the value to set.
additionalProperties:
type: string
grpc:
type: boolean
description: >-
If true, configures Emissary-Ingress to treat the upstream as
a gRPC service, enabling HTTP/2 and gRPC-specific routing.
prefix_regex:
type: boolean
description: >-
If true, the prefix field is treated as a regular expression
rather than a literal prefix match.
MappingStatus:
type: object
description: >-
Observed status of the Mapping resource as reported by Emissary-Ingress.
properties:
state:
type: string
description: Current state of the Mapping.
enum:
- Ok
- Warning
- Error
reason:
type: string
description: Human-readable reason for the current state.
conditions:
type: array
description: Detailed conditions about this Mapping's state.
items:
$ref: '#/components/schemas/Condition'
Host:
type: object
description: >-
Emissary-Ingress Host custom resource that configures a hostname for
TLS termination, including ACME-based certificate provisioning via
Let's Encrypt and TLS protocol settings.
required:
- apiVersion
- kind
- metadata
- spec
properties:
apiVersion:
type: string
description: API version of the resource.
enum:
- getambassador.io/v3alpha1
kind:
type: string
description: Resource kind.
enum:
- Host
metadata:
$ref: '#/components/schemas/ObjectMeta'
spec:
$ref: '#/components/schemas/HostSpec'
status:
$ref: '#/components/schemas/HostStatus'
HostSpec:
type: object
description: Specification for the Host defining domain and TLS configuration.
properties:
hostname:
type: string
description: >-
Fully qualified domain name (or glob pattern) this Host handles.
Supports wildcards such as '*.example.com'.
example: api.example.com
acmeProvider:
$ref: '#/components/schemas/ACMEProvider'
tlsSecret:
type: object
description: >-
Reference to a Kubernetes Secret containing the TLS certificate
and private key when not using ACME.
properties:
name:
type: string
description: Name of the Kubernetes Secret.
tls:
type: object
description: >-
Inline TLS configuration specifying minimum protocol version and
cipher suites for this host.
properties:
min_tls_version:
type: string
description: Minimum TLS protocol version to accept.
enum:
- v1.0
- v1.1
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/emissary-ingress/refs/heads/main/openapi/emissary-ingress-openapi.yml