openapi: 3.1.0 info: title: Emissary-Ingress Configuration AuthService Mapping 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 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: 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. 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 components: schemas: CircuitBreaker: type: object description: Circuit breaker configuration to prevent cascading failures. properties: priority: type: string description: Priority level to apply these circuit breaker settings to. enum: - default - high max_connections: type: integer description: Maximum number of connections to the upstream cluster. minimum: 0 max_pending_requests: type: integer description: Maximum number of pending requests to the upstream cluster. minimum: 0 max_requests: type: integer description: Maximum number of parallel requests to the upstream cluster. minimum: 0 max_retries: type: integer description: Maximum number of parallel retries to the upstream cluster. minimum: 0 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' ObjectMeta: type: object description: Standard Kubernetes object metadata. required: - name properties: name: type: string description: Name of the resource, unique within the namespace. maxLength: 253 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: Opaque value used for optimistic concurrency control. Must be provided on update and delete operations. generation: type: integer format: int64 description: Monotonically increasing sequence number for desired state changes. uid: type: string description: Unique identifier assigned by the Kubernetes system. creationTimestamp: type: string format: date-time description: Timestamp when the resource was created. CORSPolicy: type: object description: Cross-Origin Resource Sharing (CORS) policy for a Mapping. properties: origins: type: string description: Comma-separated list of allowed origins, or '*' to allow any origin. methods: type: string description: Comma-separated list of allowed HTTP methods. example: GET, POST, PUT headers: type: string description: Comma-separated list of allowed request headers. credentials: type: boolean description: Whether to allow credentials in CORS requests. exposed_headers: type: string description: Comma-separated list of response headers to expose. max_age: type: string description: Duration to cache CORS preflight responses. MappingList: type: object description: List of Mapping resources. required: - apiVersion - kind - items properties: apiVersion: type: string kind: type: string enum: - MappingList metadata: type: object properties: resourceVersion: type: string continue: type: string items: type: array description: List of Mapping resources. items: $ref: '#/components/schemas/Mapping' 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. Condition: type: object description: A Kubernetes condition representing a point-in-time status observation. required: - type - status properties: type: type: string description: Type of the condition. status: type: string description: Status of the condition. enum: - 'True' - 'False' - Unknown lastTransitionTime: type: string format: date-time description: Time when the condition last changed. reason: type: string description: Short machine-readable reason for the condition. message: type: string description: Human-readable details about the condition. RetryPolicy: type: object description: Retry configuration for failed upstream requests on a Mapping. properties: retry_on: type: string description: Condition(s) under which to retry. Supports Envoy retry policy values such as '5xx', 'connect-failure', 'retriable-4xx'. example: 5xx num_retries: type: integer description: Number of retry attempts before returning an error. minimum: 0 per_try_timeout: type: string description: Timeout per retry attempt as a duration string, e.g. '2s'. LoadBalancer: type: object description: Load balancing configuration for selecting between multiple instances of the upstream service. properties: policy: type: string description: Load balancing policy to apply. enum: - round_robin - ring_hash - maglev - least_request default: round_robin cookie: type: object description: Cookie configuration for sticky sessions using ring_hash or maglev. properties: name: type: string description: Name of the cookie to use for session affinity. path: type: string description: Cookie path. ttl: type: string description: Cookie TTL as a duration string. header: type: string description: Header name to use for consistent hashing when policy is ring_hash or maglev. source_ip: type: boolean description: If true, use the source IP address for consistent hashing. 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' 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. parameters: name: name: name in: path required: true description: The name of the resource. schema: type: string 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 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 fieldSelector: name: fieldSelector in: query required: false description: A selector to restrict the list of returned resources by their fields. schema: type: string externalDocs: description: Emissary-Ingress Documentation url: https://www.getambassador.io/docs/emissary/