openapi: 3.1.0
info:
  title: Kuma Dataplane MeshService API
  description: Kuma API
  version: v1alpha1
  x-ref-schema-name: DataplaneOverview
security:
- BasicAuth: []
- BearerAuth: []
- {}
tags:
- name: MeshService
paths:
  /meshes/{mesh}/meshservices/{name}:
    get:
      operationId: getMeshService
      summary: Returns MeshService entity
      tags:
      - MeshService
      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 MeshService
      responses:
        '200':
          $ref: '#/components/responses/MeshServiceItem'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: putMeshService
      summary: Creates or Updates MeshService entity
      tags:
      - MeshService
      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 MeshService
      requestBody:
        description: Put request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeshServiceItem'
      responses:
        '200':
          $ref: '#/components/responses/MeshServiceCreateOrUpdateSuccessResponse'
        '201':
          $ref: '#/components/responses/MeshServiceCreateOrUpdateSuccessResponse'
    delete:
      operationId: deleteMeshService
      summary: Deletes MeshService entity
      tags:
      - MeshService
      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 MeshService
      responses:
        '200':
          $ref: '#/components/responses/MeshServiceDeleteSuccessResponse'
        '404':
          $ref: '#/components/responses/NotFound'
  /meshes/{mesh}/meshservices:
    get:
      operationId: getMeshServiceList
      summary: Returns a list of MeshService in the mesh.
      tags:
      - MeshService
      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/MeshServiceList'
components:
  responses:
    NotFound:
      description: Not Found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    MeshServiceList:
      description: List
      content:
        application/json:
          schema:
            type: object
            properties:
              items:
                type: array
                items:
                  $ref: '#/components/schemas/MeshServiceItem'
              total:
                type: number
                description: The total number of entities
              next:
                type: string
                description: URL to the next page
    MeshServiceCreateOrUpdateSuccessResponse:
      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
    MeshServiceItem:
      description: Successful response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MeshServiceItem'
    MeshServiceDeleteSuccessResponse:
      description: Successful response
      content:
        application/json:
          schema:
            type: object
  schemas:
    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
    MeshServiceItem:
      type: object
      description: MeshService represents a service in the mesh with its connectivity and health information. It defines service endpoints by selecting data plane proxies through labels or direct references, configures service ports and protocols, tracks service availability and health status, and provides automatic VIP assignment and hostname generation for service discovery.
      required:
      - type
      - name
      - spec
      properties:
        type:
          description: the type of the resource
          type: string
          enum:
          - MeshService
        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_msvc_default_zone-east_kuma-demo_myresource1_
        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 MeshService resource.
          properties:
            identities:
              items:
                properties:
                  type:
                    enum:
                    - ServiceTag
                    - SpiffeID
                    type: string
                  value:
                    type: string
                required:
                - type
                - value
                type: object
              type: array
            ports:
              items:
                properties:
                  appProtocol:
                    default: tcp
                    description: Protocol identifies a protocol supported by a service.
                    type: string
                  name:
                    type: string
                  port:
                    format: int32
                    type: integer
                  targetPort:
                    anyOf:
                    - type: integer
                    - type: string
                    x-kubernetes-int-or-string: true
                required:
                - port
                type: object
              type: array
              x-kubernetes-list-map-keys:
              - port
              - appProtocol
              x-kubernetes-list-type: map
            selector:
              properties:
                dataplaneLabels:
                  properties:
                    matchLabels:
                      additionalProperties:
                        type: string
                      type: object
                  type: object
                dataplaneRef:
                  properties:
                    name:
                      type: string
                  type: object
                dataplaneTags:
                  additionalProperties:
                    type: string
                  type: object
              type: object
            state:
              default: Unavailable
              description: 'State of MeshService. Available if there is at least one healthy endpoint. Otherwise, Unavailable.

                It''s used for cross zone communication to check if we should send traffic to it, when MeshService is aggregated into MeshMultiZoneService.'
              enum:
              - Available
              - Unavailable
              type: string
          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'
        status:
          description: Status is the current status of the Kuma MeshService resource.
          properties:
            addresses:
              items:
                properties:
                  hostname:
                    type: string
                  hostnameGeneratorRef:
                    properties:
                      coreName:
                        type: string
                    required:
                    - coreName
                    type: object
                  origin:
                    type: string
                type: object
              type: array
            dataplaneProxies:
              description: Data plane proxies statistics selected by this MeshService.
              properties:
                connected:
                  description: Number of data plane proxies connected to the zone control plane
                  type: integer
                healthy:
                  description: Number of data plane proxies with all healthy inbounds selected by this MeshService.
                  type: integer
                total:
                  description: Total number of data plane proxies.
                  type: integer
              type: object
            hostnameGenerators:
              items:
                properties:
                  conditions:
                    description: Conditions is an array of hostname generator conditions.
                    items:
                      properties:
                        message:
                          description: 'message is a human readable message indicating details about the transition.

                            This may be an empty string.'
                          maxLength: 32768
                          type: string
                        reason:
                          description: 'reason contains a programmatic identifier indicating the reason for the condition''s last transition.

                            Producers of specific condition types may define expected values and meanings for this field,

                            and whether the values are considered a guaranteed API.

                            The value should be a CamelCase string.

                            This field may not be empty.'
                          maxLength: 1024
                          minLength: 1
                          pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
                          type: string
                        status:
                          description: status of the condition, one of True, False, Unknown.
                          enum:
                          - 'True'
                          - 'False'
                          - Unknown
                          type: string
                        type:
                          description: type of condition in CamelCase or in foo.example.com/CamelCase.
                          maxLength: 316
                          pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
                          type: string
                      required:
                      - message
                      - reason
                      - status
                      - type
                      type: object
                    type: array
                    x-kubernetes-list-map-keys:
                    - type
                    x-kubernetes-list-type: map
                  hostnameGeneratorRef:
                    properties:
                      coreName:
                        type: string
                    required:
                    - coreName
                    type: object
                required:
                - hostnameGeneratorRef
                type: object
              type: array
            tls:
              properties:
                status:
                  enum:
                  - Ready
                  - NotReady
                  type: string
              type: object
            vips:
              items:
                properties:
                  ip:
                    type: string
                type: object
              type: array
          type: object
          readOnly: true
    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