openapi: 3.1.0
info:
  title: Kuma Dataplane MeshGateway API
  description: Kuma API
  version: v1alpha1
  x-ref-schema-name: DataplaneOverview
security:
- BasicAuth: []
- BearerAuth: []
- {}
tags:
- name: MeshGateway
paths:
  /meshes/{mesh}/meshgateways:
    get:
      operationId: getMeshGatewayList
      parameters:
      - description: offset in the list of entities
        example: 0
        in: query
        name: offset
        required: false
        schema:
          type: integer
      - description: the number of items per page
        in: query
        name: size
        required: false
        schema:
          default: 100
          maximum: 1000
          minimum: 1
          type: integer
      - description: filter by labels when multiple filters are present, they are ANDed
        example:
          label.k8s.kuma.io/namespace: my-ns
        in: query
        name: filter
        required: false
        schema:
          properties:
            key:
              type: string
            value:
              type: string
          type: object
      - description: name of the mesh
        in: path
        name: mesh
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/MeshGatewayList'
      summary: Returns a list of MeshGateway in the mesh.
      tags:
      - MeshGateway
  /meshes/{mesh}/meshgateways/{name}:
    delete:
      operationId: deleteMeshGateway
      parameters:
      - description: name of the mesh
        in: path
        name: mesh
        required: true
        schema:
          type: string
      - description: name of the MeshGateway
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/MeshGatewayDeleteSuccessResponse'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Deletes MeshGateway entity
      tags:
      - MeshGateway
    get:
      operationId: getMeshGateway
      parameters:
      - description: name of the mesh
        in: path
        name: mesh
        required: true
        schema:
          type: string
      - description: name of the MeshGateway
        in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/MeshGatewayItem'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Returns MeshGateway entity
      tags:
      - MeshGateway
    put:
      operationId: putMeshGateway
      parameters:
      - description: name of the mesh
        in: path
        name: mesh
        required: true
        schema:
          type: string
      - description: name of the MeshGateway
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeshGatewayItem'
        description: Put request
        required: true
      responses:
        '200':
          $ref: '#/components/responses/MeshGatewayCreateOrUpdateSuccessResponse'
        '201':
          $ref: '#/components/responses/MeshGatewayCreateOrUpdateSuccessResponse'
      summary: Creates or Updates MeshGateway entity
      tags:
      - MeshGateway
components:
  schemas:
    DataSource_File:
      properties:
        file:
          description: 'Data source is a path to a file.

            Deprecated, use other sources of a data.'
          type: string
      type: object
    NotFoundError:
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        properties:
          status:
            type: integer
            enum:
            - 404
            example: 404
            description: 'The HTTP status code for NotFoundError MUST be 404.

              '
          title:
            type: string
            example: Not Found
          type:
            type: string
            example: https://httpstatuses.com/404
          detail:
            type: string
            example: The requested resource was not found
    DataSource_Inline:
      properties:
        inline:
          description: Data source is inline bytes.
          format: byte
          type: string
      type: object
    MeshGatewayItem:
      properties:
        conf:
          description: The desired configuration of the MeshGateway.
          properties:
            listeners:
              description: 'Listeners define logical endpoints that are bound on this MeshGateway''s

                address(es).'
              items:
                properties:
                  crossMesh:
                    description: 'CrossMesh enables traffic to flow to this listener only from other

                      meshes.'
                    type: boolean
                  hostname:
                    description: 'Hostname specifies the virtual hostname to match for protocol types that

                      define this concept. When unspecified, "", or `*`, all hostnames are

                      matched. This field can be omitted for protocols that don''t require

                      hostname based matching.'
                    type: string
                  port:
                    description: 'Port is the network port. Multiple listeners may use the

                      same port, subject to the Listener compatibility rules.'
                    type: integer
                  protocol:
                    description: Protocol specifies the network protocol this listener expects to receive.
                    oneOf:
                    - type: string
                    - type: integer
                  resources:
                    description: Resources is used to specify listener-specific resource settings.
                    properties:
                      connectionLimit:
                        type: integer
                    type: object
                  tags:
                    additionalProperties:
                      type: string
                    description: 'Tags specifies a unique combination of tags that routes can use

                      to match themselves to this listener.


                      When matching routes to listeners, the control plane constructs a

                      set of matching tags for each listener by forming the union of the

                      gateway tags and the listener tags. A route will be attached to the

                      listener if all of the route''s tags are preset in the matching tags'
                    type: object
                  tls:
                    description: 'TLS is the TLS configuration for the Listener. This field

                      is required if the Protocol field is "HTTPS" or "TLS" and

                      ignored otherwise.'
                    properties:
                      certificates:
                        description: 'Certificates is an array of datasources that contain TLS

                          certificates and private keys.  Each datasource must contain a

                          sequence of PEM-encoded objects. The server certificate and private

                          key are required, but additional certificates are allowed and will

                          be added to the certificate chain.  The server certificate must

                          be the first certificate in the datasource.


                          When multiple certificate datasources are configured, they must have

                          different key types. In practice, this means that one datasource

                          should contain an RSA key and certificate, and the other an

                          ECDSA key and certificate.'
                        items:
                          oneOf:
                          - $ref: '#/components/schemas/DataSource_File'
                          - $ref: '#/components/schemas/DataSource_Inline'
                          - $ref: '#/components/schemas/DataSource_InlineString'
                          - $ref: '#/components/schemas/DataSource_Secret'
                        type: array
                      mode:
                        description: 'Mode defines the TLS behavior for the TLS session initiated

                          by the client.'
                        oneOf:
                        - type: string
                        - type: integer
                      options:
                        description: 'Options should eventually configure how TLS is configured. This

                          is where cipher suite and version configuration can be specified,

                          client certificates enforced, and so on.'
                        properties: {}
                        type: object
                    type: object
                type: object
              type: array
          type: object
        labels:
          additionalProperties:
            type: string
          type: object
        mesh:
          type: string
        name:
          type: string
        selectors:
          description: 'Selectors is a list of selectors that are used to match builtin

            gateway dataplanes that will receive this MeshGateway configuration.'
          items:
            description: Selector defines structure for selecting tags for given dataplane
            properties:
              match:
                additionalProperties:
                  type: string
                description: Tags to match, can be used for both source and destinations
                type: object
            type: object
          type: array
        tags:
          additionalProperties:
            type: string
          description: 'Tags is the set of tags common to all of the gateway''s listeners.


            This field must not include a `kuma.io/service` tag (the service is always

            defined on the dataplanes).'
          type: object
        type:
          type: string
      required:
      - type
      - name
      - mesh
      type: object
    DataSource_Secret:
      properties:
        secret:
          description: Data source is a secret with given Secret key.
          type: string
      type: object
    InvalidParameters:
      type: object
      title: Invalid Parameters
      required:
      - field
      - reason
      - source
      properties:
        field:
          type: string
          description: The name of the field that caused the error.
        reason:
          type: string
          description: 'A short, human-readable description of the problem.

            _Should_ be provided as "Sentence case" for direct use in a UI.

            '
        rule:
          type: string
          description: 'May be provided as a hint to the user to help understand the type of failure.

            Additional guidance may be provided in additional fields, i.e. `choices`.

            '
        choices:
          type: array
          description: 'Optional field to provide a list of valid choices for the field that caused the error.

            '
          items:
            type: string
        source:
          type: string
          description: 'The location of the field that caused the error.

            '
          enum:
          - body
          - query
          - header
          - path
    DataSource_InlineString:
      properties:
        inlineString:
          description: Data source is inline string
          type: string
      type: object
    Error:
      type: object
      title: Error
      description: 'Standard error. Follows the [AIP #193 - Errors](https://kong-aip.netlify.app/aip/193/) specification.

        '
      x-examples:
        Example 1:
          status: 404
          title: Not Found
          type: https://kongapi.info/konnect/not-found
          instance: portal:trace:2287285207635123011
          detail: The requested document was not found
      required:
      - status
      - title
      - instance
      - type
      - detail
      properties:
        status:
          type: integer
          description: The HTTP status code.
          example: 404
        title:
          type: string
          description: 'A short, human-readable summary of the problem.

            It **should not** change between occurrences of a problem, except for localization.

            Should be provided as "Sentence case" for potential direct use in a UI

            '
          example: Not Found
        type:
          type: string
          description: 'A unique identifier for this error. When dereferenced it must provide human-readable documentation for the problem.

            '
          example: Not Found
        instance:
          type: string
          example: portal:trace:2287285207635123011
          description: 'Used to return the correlation ID back to the user, in the format `<app>:trace:<correlation_id>`.

            '
        detail:
          type: string
          example: The requested team was not found
          description: 'A human readable explanation specific to this occurrence of the problem.

            This field may contain request/entity data to help the user understand what went wrong.

            Enclose variable values in square brackets.

            _Should_ be provided as "Sentence case" for direct use in a UI

            '
        invalid_parameters:
          type: array
          description: 'All 400 errors **MUST** return an `invalid_parameters` key in the response.

            Used to indicate which fields have invalid values when validated.

            '
          items:
            $ref: '#/components/schemas/InvalidParameters'
  responses:
    MeshGatewayList:
      content:
        application/json:
          schema:
            properties:
              items:
                items:
                  $ref: '#/components/schemas/MeshGatewayItem'
                type: array
              next:
                description: URL to the next page
                type: string
              total:
                description: The total number of entities
                type: number
            type: object
      description: List
    NotFound:
      description: Not Found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    MeshGatewayItem:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MeshGatewayItem'
      description: Successful response
    MeshGatewayDeleteSuccessResponse:
      content:
        application/json:
          schema:
            type: object
      description: Successful response
    MeshGatewayCreateOrUpdateSuccessResponse:
      content:
        application/json:
          schema:
            properties:
              warnings:
                description: 'warnings is a list of warning messages to return to the requesting Kuma API clients.

                  Warning messages describe a problem the client making the API request should correct or be aware of.

                  '
                items:
                  type: string
                readOnly: true
                type: array
            type: object
      description: Successful response
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer