openapi: 3.1.0
info:
  title: Kuma Dataplane MeshPassthrough API
  description: Kuma API
  version: v1alpha1
  x-ref-schema-name: DataplaneOverview
security:
- BasicAuth: []
- BearerAuth: []
- {}
tags:
- name: MeshPassthrough
paths:
  /meshes/{mesh}/meshpassthroughs/{name}:
    get:
      operationId: getMeshPassthrough
      summary: Returns MeshPassthrough entity
      tags:
      - MeshPassthrough
      parameters:
      - in: path
        name: mesh
        schema:
          type: string
        required: true
        description: name of the mesh
      - in: path
        name: name
        schema:
          type: string
        required: true
        description: name of the MeshPassthrough
      responses:
        '200':
          $ref: '#/components/responses/MeshPassthroughItem'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: putMeshPassthrough
      summary: Creates or Updates MeshPassthrough entity
      tags:
      - MeshPassthrough
      parameters:
      - in: path
        name: mesh
        schema:
          type: string
        required: true
        description: name of the mesh
      - in: path
        name: name
        schema:
          type: string
        required: true
        description: name of the MeshPassthrough
      requestBody:
        description: Put request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeshPassthroughItem'
      responses:
        '200':
          $ref: '#/components/responses/MeshPassthroughCreateOrUpdateSuccessResponse'
        '201':
          $ref: '#/components/responses/MeshPassthroughCreateOrUpdateSuccessResponse'
    delete:
      operationId: deleteMeshPassthrough
      summary: Deletes MeshPassthrough entity
      tags:
      - MeshPassthrough
      parameters:
      - in: path
        name: mesh
        schema:
          type: string
        required: true
        description: name of the mesh
      - in: path
        name: name
        schema:
          type: string
        required: true
        description: name of the MeshPassthrough
      responses:
        '200':
          $ref: '#/components/responses/MeshPassthroughDeleteSuccessResponse'
        '404':
          $ref: '#/components/responses/NotFound'
  /meshes/{mesh}/meshpassthroughs:
    get:
      operationId: getMeshPassthroughList
      summary: Returns a list of MeshPassthrough in the mesh.
      tags:
      - MeshPassthrough
      parameters:
      - in: query
        name: offset
        description: offset in the list of entities
        required: false
        schema:
          type: integer
        example: 0
      - in: query
        name: size
        description: the number of items per page
        required: false
        schema:
          type: integer
          default: 100
          maximum: 1000
          minimum: 1
      - in: query
        name: filter
        description: filter by labels when multiple filters are present, they are ANDed
        required: false
        schema:
          type: object
          properties:
            key:
              type: string
            value:
              type: string
        example:
          label.k8s.kuma.io/namespace: my-ns
      - in: path
        name: mesh
        schema:
          type: string
        required: true
        description: name of the mesh
      responses:
        '200':
          $ref: '#/components/responses/MeshPassthroughList'
components:
  responses:
    NotFound:
      description: Not Found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    MeshPassthroughItem:
      description: Successful response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MeshPassthroughItem'
    MeshPassthroughDeleteSuccessResponse:
      description: Successful response
      content:
        application/json:
          schema:
            type: object
    MeshPassthroughCreateOrUpdateSuccessResponse:
      description: Successful response
      content:
        application/json:
          schema:
            type: object
            properties:
              warnings:
                type: array
                readOnly: true
                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
    MeshPassthroughList:
      description: List
      content:
        application/json:
          schema:
            type: object
            properties:
              items:
                type: array
                items:
                  $ref: '#/components/schemas/MeshPassthroughItem'
              total:
                type: number
                description: The total number of entities
              next:
                type: string
                description: URL to the next page
  schemas:
    MeshPassthroughItem:
      type: object
      description: MeshPassthrough controls how traffic to external services (outside the mesh) is handled by the sidecar proxy. It allows you to configure passthrough mode to permit, deny, or selectively allow traffic to specific external destinations based on domain names, IPs, or CIDR ranges.
      required:
      - type
      - name
      - spec
      properties:
        type:
          description: the type of the resource
          type: string
          enum:
          - MeshPassthrough
        mesh:
          description: Mesh is the name of the Kuma mesh this resource belongs to. It may be omitted for cluster-scoped resources.
          type: string
          default: default
        kri:
          description: A unique identifier for this resource instance used by internal tooling and integrations. Typically derived from resource attributes and may be used for cross-references or indexing
          type: string
          readOnly: true
          example: kri_mp_default_zone-east_kuma-demo_mypolicy1_
        name:
          description: Name of the Kuma resource
          type: string
        labels:
          additionalProperties:
            type: string
          description: The labels to help identity resources
          type: object
        spec:
          description: Spec is the specification of the Kuma MeshPassthrough resource.
          properties:
            default:
              description: MeshPassthrough configuration.
              properties:
                appendMatch:
                  description: AppendMatch is a list of destinations that should be allowed through the sidecar.
                  items:
                    properties:
                      port:
                        description: Port defines the port to which a user makes a request.
                        format: int32
                        type: integer
                      protocol:
                        default: tcp
                        description: 'Protocol defines the communication protocol. Possible values: `tcp`, `tls`, `grpc`, `http`, `http2`, `mysql`.'
                        enum:
                        - tcp
                        - tls
                        - grpc
                        - http
                        - http2
                        - mysql
                        type: string
                      type:
                        description: Type of the match, one of `Domain`, `IP` or `CIDR` is available.
                        enum:
                        - Domain
                        - IP
                        - CIDR
                        type: string
                      value:
                        description: Value for the specified Type.
                        type: string
                    required:
                    - type
                    - value
                    type: object
                  type: array
                passthroughMode:
                  description: 'Defines the passthrough behavior. Possible values: `All`, `None`, `Matched`

                    When `All` or `None` `appendMatch` has no effect.

                    If not specified then the default value is "Matched".'
                  enum:
                  - All
                  - Matched
                  - None
                  type: string
              type: object
            targetRef:
              description: 'TargetRef is a reference to the resource the policy takes an effect on.

                The resource could be either a real store object or virtual resource

                defined in-place.'
              properties:
                kind:
                  description: Kind of the referenced resource
                  enum:
                  - Mesh
                  - MeshSubset
                  - MeshGateway
                  - MeshService
                  - MeshExternalService
                  - MeshMultiZoneService
                  - MeshServiceSubset
                  - MeshHTTPRoute
                  - Dataplane
                  type: string
                labels:
                  additionalProperties:
                    type: string
                  description: 'Labels are used to select group of MeshServices that match labels. Either Labels or

                    Name and Namespace can be used.'
                  type: object
                mesh:
                  description: Mesh is reserved for future use to identify cross mesh resources.
                  type: string
                name:
                  description: 'Name of the referenced resource. Can only be used with kinds: `MeshService`,

                    `MeshServiceSubset` and `MeshGatewayRoute`'
                  type: string
                namespace:
                  description: 'Namespace specifies the namespace of target resource. If empty only resources in policy namespace

                    will be targeted.'
                  type: string
                proxyTypes:
                  description: 'ProxyTypes specifies the data plane types that are subject to the policy. When not specified,

                    all data plane types are targeted by the policy.'
                  items:
                    enum:
                    - Sidecar
                    - Gateway
                    type: string
                  type: array
                sectionName:
                  description: 'SectionName is used to target specific section of resource.

                    For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.'
                  type: string
                tags:
                  additionalProperties:
                    type: string
                  description: 'Tags used to select a subset of proxies by tags. Can only be used with kinds

                    `MeshSubset` and `MeshServiceSubset`'
                  type: object
              required:
              - kind
              type: object
          type: object
        creationTime:
          readOnly: true
          type: string
          description: Time at which the resource was created
          format: date-time
          example: '0001-01-01T00:00:00Z'
        modificationTime:
          readOnly: true
          type: string
          description: Time at which the resource was updated
          format: date-time
          example: '0001-01-01T00:00:00Z'
    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
    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
    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'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer