Emissary-Ingress Mapping API

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/