openapi: 3.1.0
info:
  title: Emissary-Ingress Configuration AuthService RateLimitService 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: RateLimitService
  description: Operations for managing RateLimitService custom resources that configure integration with external rate limiting services compatible with the Envoy rate limit API.
paths:
  /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
components:
  schemas:
    RateLimitServiceSpec:
      type: object
      description: Specification for the RateLimitService.
      required:
      - service
      properties:
        service:
          type: string
          description: Name (and optional port) of the Kubernetes service implementing the Envoy rate limit gRPC API.
          example: rate-limit-service:8081
        protocol_version:
          type: string
          description: Version of the Envoy rate limit gRPC protocol to use.
          enum:
          - v2
          - v3
          default: v2
        timeout_ms:
          type: integer
          description: Timeout in milliseconds for rate limit service calls. Requests will proceed if the rate limit service times out.
          minimum: 0
          default: 20
        grpc_service:
          type: object
          description: Advanced gRPC service configuration.
          properties:
            target_uri:
              type: string
              description: Target URI for the gRPC rate limit service.
    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.
    RateLimitService:
      type: object
      description: Emissary-Ingress RateLimitService custom resource configuring integration with an external rate limiting service. The service must implement the Envoy rate limit gRPC API. Only one RateLimitService can be active at a time.
      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:
          - RateLimitService
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        spec:
          $ref: '#/components/schemas/RateLimitServiceSpec'
    RateLimitServiceList:
      type: object
      description: List of RateLimitService resources.
      required:
      - apiVersion
      - kind
      - items
      properties:
        apiVersion:
          type: string
        kind:
          type: string
          enum:
          - RateLimitServiceList
        metadata:
          type: object
        items:
          type: array
          description: List of RateLimitService resources.
          items:
            $ref: '#/components/schemas/RateLimitService'
  parameters:
    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
externalDocs:
  description: Emissary-Ingress Documentation
  url: https://www.getambassador.io/docs/emissary/