openapi: 3.1.0
info:
  title: Kuma Dataplane MeshMultiZoneService API
  description: Kuma API
  version: v1alpha1
  x-ref-schema-name: DataplaneOverview
security:
- BasicAuth: []
- BearerAuth: []
- {}
tags:
- name: MeshMultiZoneService
paths:
  /meshes/{mesh}/meshmultizoneservices/{name}:
    get:
      operationId: getMeshMultiZoneService
      summary: Returns MeshMultiZoneService entity
      tags:
      - MeshMultiZoneService
      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 MeshMultiZoneService
      responses:
        '200':
          $ref: '#/components/responses/MeshMultiZoneServiceItem'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: putMeshMultiZoneService
      summary: Creates or Updates MeshMultiZoneService entity
      tags:
      - MeshMultiZoneService
      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 MeshMultiZoneService
      requestBody:
        description: Put request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeshMultiZoneServiceItem'
      responses:
        '200':
          $ref: '#/components/responses/MeshMultiZoneServiceCreateOrUpdateSuccessResponse'
        '201':
          $ref: '#/components/responses/MeshMultiZoneServiceCreateOrUpdateSuccessResponse'
    delete:
      operationId: deleteMeshMultiZoneService
      summary: Deletes MeshMultiZoneService entity
      tags:
      - MeshMultiZoneService
      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 MeshMultiZoneService
      responses:
        '200':
          $ref: '#/components/responses/MeshMultiZoneServiceDeleteSuccessResponse'
        '404':
          $ref: '#/components/responses/NotFound'
  /meshes/{mesh}/meshmultizoneservices:
    get:
      operationId: getMeshMultiZoneServiceList
      summary: Returns a list of MeshMultiZoneService in the mesh.
      tags:
      - MeshMultiZoneService
      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/MeshMultiZoneServiceList'
components:
  responses:
    MeshMultiZoneServiceItem:
      description: Successful response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MeshMultiZoneServiceItem'
    NotFound:
      description: Not Found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    MeshMultiZoneServiceDeleteSuccessResponse:
      description: Successful response
      content:
        application/json:
          schema:
            type: object
    MeshMultiZoneServiceCreateOrUpdateSuccessResponse:
      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
    MeshMultiZoneServiceList:
      description: List
      content:
        application/json:
          schema:
            type: object
            properties:
              items:
                type: array
                items:
                  $ref: '#/components/schemas/MeshMultiZoneServiceItem'
              total:
                type: number
                description: The total number of entities
              next:
                type: string
                description: URL to the next page
  schemas:
    MeshMultiZoneServiceItem:
      type: object
      description: 'MeshMultiZoneService provides global load balancing and service discovery across multiple zones in a multi-zone mesh deployment. It aggregates MeshServices from different zones by label selectors, creating a unified service endpoint with automatic VIP assignment and hostname generation for cross-zone communication and failover.

        MeshMultizoneServices are only created on global'
      required:
      - type
      - name
      - spec
      properties:
        type:
          description: the type of the resource
          type: string
          enum:
          - MeshMultiZoneService
        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_mzsvc_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 MeshMultiZoneService resource.
          properties:
            ports:
              description: Ports is a list of ports from selected MeshServices
              items:
                properties:
                  appProtocol:
                    default: tcp
                    description: Protocol identifies a protocol supported by a service.
                    type: string
                  name:
                    type: string
                  port:
                    format: int32
                    type: integer
                required:
                - port
                type: object
              minItems: 1
              type: array
            selector:
              description: Selector is a way to select multiple MeshServices
              properties:
                meshService:
                  description: MeshService selects MeshServices
                  properties:
                    matchLabels:
                      additionalProperties:
                        type: string
                      type: object
                  type: object
              required:
              - meshService
              type: object
          required:
          - ports
          - selector
          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 MeshMultiZoneService resource.
          properties:
            addresses:
              description: Addresses is a list of addresses generated by HostnameGenerator
              items:
                properties:
                  hostname:
                    type: string
                  hostnameGeneratorRef:
                    properties:
                      coreName:
                        type: string
                    required:
                    - coreName
                    type: object
                  origin:
                    type: string
                type: object
              type: array
            conditions:
              description: Conditions is an array of current 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
            hostnameGenerators:
              description: Status of hostnames generator applied on this resource
              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
            meshServices:
              description: MeshServices is a list of matched MeshServices
              items:
                properties:
                  mesh:
                    type: string
                  name:
                    description: Name is a core name of MeshService
                    type: string
                  namespace:
                    type: string
                  zone:
                    type: string
                required:
                - mesh
                - name
                - namespace
                - zone
                type: object
              type: array
            vips:
              description: VIPs is a list of assigned Kuma VIPs.
              items:
                properties:
                  ip:
                    type: string
                type: object
              type: array
          type: object
          readOnly: true
    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