Emissary-Ingress TLSContext API

openapi: 3.1.0
info:
  title: Emissary-Ingress Configuration AuthService TLSContext 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: 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}/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
components:
  schemas:
    TLSContextList:
      type: object
      description: List of TLSContext resources.
      required:
      - apiVersion
      - kind
      - items
      properties:
        apiVersion:
          type: string
        kind:
          type: string
          enum:
          - TLSContextList
        metadata:
          type: object
        items:
          type: array
          description: List of TLSContext resources.
          items:
            $ref: '#/components/schemas/TLSContext'
    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.
    TLSContext:
      type: object
      description: Emissary-Ingress TLSContext custom resource defining reusable TLS configuration for both terminating inbound TLS and originating outbound TLS connections. TLSContexts can be referenced by name from Host and Mapping resources.
      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:
          - TLSContext
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        spec:
          $ref: '#/components/schemas/TLSContextSpec'
    TLSContextSpec:
      type: object
      description: Specification for the TLSContext defining certificate and protocol settings.
      properties:
        secret:
          type: string
          description: Name of the Kubernetes Secret containing the TLS certificate (tls.crt) and private key (tls.key). May reference a secret in another namespace using 'namespace/name' format.
        cert_chain_file:
          type: string
          description: Path to the PEM certificate chain file in the Emissary-Ingress pod.
        private_key_file:
          type: string
          description: Path to the PEM private key file in the Emissary-Ingress pod.
        cacert_chain_file:
          type: string
          description: Path to the CA certificate chain file for client certificate validation.
        alpn_protocols:
          type: string
          description: Comma-separated list of ALPN protocols to offer during TLS negotiation, e.g. 'h2,http/1.1'.
        min_tls_version:
          type: string
          description: Minimum TLS protocol version to accept.
          enum:
          - v1.0
          - v1.1
          - v1.2
          - v1.3
        max_tls_version:
          type: string
          description: Maximum TLS protocol version to accept.
          enum:
          - v1.0
          - v1.1
          - v1.2
          - v1.3
        cipher_suites:
          type: array
          description: TLS cipher suites to allow during negotiation.
          items:
            type: string
        ecdh_curves:
          type: array
          description: ECDH curves to offer during TLS negotiation.
          items:
            type: string
        redirect_cleartext_from:
          type: integer
          description: Insecure port to redirect to HTTPS. When set, Emissary-Ingress listens on this port and redirects all requests to HTTPS.
        hosts:
          type: array
          description: List of hostnames this TLSContext applies to. Enables SNI-based TLS configuration selection.
          items:
            type: string
  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
externalDocs:
  description: Emissary-Ingress Documentation
  url: https://www.getambassador.io/docs/emissary/