openapi: 3.1.0
info:
  title: Kuma Dataplane Inspect API
  description: Kuma API
  version: v1alpha1
  x-ref-schema-name: DataplaneOverview
security:
- BasicAuth: []
- BearerAuth: []
- {}
tags:
- name: Inspect
paths:
  /meshes/{mesh}/{resourceType}/{resourceName}/_rules:
    get:
      operationId: inspect-dataplanes-rules
      summary: Returns rules matching this dataplane
      description: Returns rules matching this dataplane
      tags:
      - Inspect
      parameters:
      - in: path
        name: mesh
        example: default
        schema:
          type: string
        required: true
        description: The mesh the policy is part of
      - in: path
        name: resourceType
        example: dataplanes
        required: true
        schema:
          type: string
          enum:
          - dataplanes
          - meshgateways
        description: The type of resource (only some resources support rules api)
      - in: path
        name: resourceName
        example: my-dp
        schema:
          type: string
        required: true
        description: The name of the resource
      responses:
        '200':
          $ref: '#/components/responses/InspectRulesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/Internal'
  /meshes/{mesh}/{policyType}/{policyName}/_resources/dataplanes:
    get:
      operationId: inspect-resources
      summary: Returns resources matched by this policy
      description: Returns resources matched by this policy. In the case of `targetRef` policies we'll match using the top level `targetRef`
      tags:
      - Inspect
      parameters:
      - in: path
        name: mesh
        example: default
        schema:
          type: string
        required: true
        description: The mesh the policy is part of
      - in: path
        name: policyType
        example: meshretries
        schema:
          type: string
        required: true
        description: The type of the policy
      - in: path
        name: policyName
        example: retry-all
        schema:
          type: string
        required: true
        description: The type of the policy
      - in: query
        name: size
        schema:
          type: integer
        required: false
        description: The max number of items to return
      - in: query
        name: offset
        schema:
          type: integer
        required: false
        description: The offset of result
      - in: query
        name: name
        schema:
          type: string
        required: false
        description: A sub string to filter resources by name
      responses:
        '200':
          $ref: '#/components/responses/InspectDataplanesForPolicyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/Internal'
  /meshes/{mesh}/meshservices/{name}/_dataplanes:
    get:
      operationId: inspect-meshservices-dataplanes
      summary: Returns dataplanes matched by a MeshService
      description: Returns dataplanes matched by a MeshService
      tags:
      - Inspect
      parameters:
      - in: path
        name: mesh
        example: default
        schema:
          type: string
        required: true
        description: The mesh the service is part of
      - in: path
        name: name
        example: redis
        schema:
          type: string
        required: true
        description: The name of the service
      - in: query
        name: size
        schema:
          type: integer
        required: false
        description: The max number of items to return
      - in: query
        name: offset
        schema:
          type: integer
        required: false
        description: The offset of result
      - in: query
        name: name
        schema:
          type: string
        required: false
        description: A sub string to filter resources by name
      responses:
        '200':
          $ref: '#/components/responses/InspectDataplanesForPolicyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/Internal'
  /meshes/{mesh}/{serviceType}/{serviceName}/_hostnames:
    get:
      operationId: inspect-hostnames
      summary: Returns hostnames for service
      description: Returns hostnames for a service
      tags:
      - Inspect
      parameters:
      - in: path
        name: mesh
        example: default
        schema:
          type: string
        required: true
        description: The mesh the service is part of
      - in: path
        name: serviceType
        example: meshservices
        schema:
          type: string
          enum:
          - meshservices
          - meshmultizoneservices
          - meshexternalservices
        required: true
        description: The type of the service
      - in: path
        name: serviceName
        example: redis
        schema:
          type: string
        required: true
        description: The name of the service
      responses:
        '200':
          $ref: '#/components/responses/InspectHostnamesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/Internal'
components:
  responses:
    Internal:
      description: Internal Server Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    InspectRulesResponse:
      description: A response containing policies that match a resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InspectRules'
    InspectHostnamesResponse:
      description: A response containing hostnames that match a service.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InspectHostnames'
          examples:
            ResponseForHostnames:
              $ref: '#/components/examples/InspectHostnamesExample'
    InspectDataplanesForPolicyResponse:
      description: A response containing dataplanes that match a policy.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InspectDataplanesForPolicy'
          examples:
            ResponseForDataplane:
              $ref: '#/components/examples/InspectDataplanesForPolicyExample'
    NotFound:
      description: Not Found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    BadRequest:
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Meta:
      type: object
      required:
      - type
      - mesh
      - name
      - labels
      properties:
        type:
          type: string
          example: Dataplane
          description: the type of this resource
        mesh:
          type: string
          example: default
          description: the mesh this resource is part of
        name:
          type: string
          example: my-resource
          description: the name of the resource
        kri:
          type: string
          readOnly: true
          x-go-name: KRI
          example: kri_mtp_default_zone-east_kuma-demo_mypolicy1_
          description: Kuma Resource Identifier (KRI) of the given resource
        labels:
          type: object
          additionalProperties:
            type: string
          example:
            k8s.kuma.io/namespace: kuma-system
            kuma.io/display-name: mtp
            kuma.io/mesh: default
            kuma.io/origin: zone
          description: 'Labels of the resource. Note: certain system labels are immutable after creation:

            - `kuma.io/origin`: Resource origin (zone/global). Immutable.

            - `kuma.io/zone`: Zone where resource originated. Immutable.

            - `kuma.io/display-name`: Display name for the resource. Immutable.

            '
    Rule:
      type: object
      required:
      - matchers
      - conf
      - origin
      properties:
        matchers:
          type: array
          items:
            $ref: '#/components/schemas/RuleMatcher'
        conf:
          description: The actual conf generated
          type: object
          additionalProperties: true
          x-go-type: interface{}
        origin:
          type: array
          items:
            $ref: '#/components/schemas/Meta'
    InspectDataplanesForPolicy:
      type: object
      title: InspectDataplanesForPolicy
      description: A list of proxies
      required:
      - total
      - items
      properties:
        total:
          type: integer
          example: 200
        next:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/Meta'
    ResourceRuleOrigin:
      type: object
      properties:
        resourceMeta:
          $ref: '#/components/schemas/Meta'
        ruleIndex:
          description: index of the to-item in the policy
          type: integer
    ProxyRule:
      description: a rule that affects the entire proxy
      type: object
      required:
      - conf
      - origin
      properties:
        conf:
          description: The actual conf generated
          type: object
          additionalProperties: true
          x-go-type: interface{}
        origin:
          type: array
          items:
            $ref: '#/components/schemas/Meta'
    ResourceRule:
      type: object
      required:
      - resourceMeta
      - conf
      - origin
      properties:
        resourceMeta:
          $ref: '#/components/schemas/Meta'
        resourceSectionName:
          type: string
        conf:
          description: The actual conf generated
          type: array
          items:
            type: object
            additionalProperties: true
            x-go-type: interface{}
        origin:
          type: array
          description: The list of policies that contributed to the 'conf'. The order is important as it reflects in what order confs were merged to get the resulting 'conf'.
          items:
            $ref: '#/components/schemas/ResourceRuleOrigin'
    InspectRules:
      type: object
      title: InspectRules
      description: A list of rules for a dataplane
      required:
      - rules
      - resource
      - httpMatches
      properties:
        resource:
          $ref: '#/components/schemas/Meta'
        rules:
          type: array
          items:
            $ref: '#/components/schemas/InspectRule'
        httpMatches:
          type: array
          items:
            $ref: '#/components/schemas/HttpMatch'
    FromRule:
      type: object
      required:
      - rules
      - inbound
      properties:
        inbound:
          $ref: '#/components/schemas/Inbound'
        rules:
          type: array
          items:
            $ref: '#/components/schemas/Rule'
    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
    HttpMatch:
      type: object
      required:
      - hash
      - match
      properties:
        hash:
          type: string
        match:
          type: object
          x-go-type: interface{}
    InboundRule:
      type: object
      required:
      - conf
      - origin
      properties:
        conf:
          description: The final computed configuration for the data plane proxy, derived by merging all policies whose 'targetRef' field matches the proxy. The merging process follows [RFC 7396 (JSON Merge Patch)](https://datatracker.ietf.org/doc/html/rfc7396), with the order of merging influenced by factors such as where the policy was applied (e.g., custom namespace, system, or global control plane), policy role, and targetRef specificity.
          type: array
          items:
            type: object
            additionalProperties: true
            x-go-type: interface{}
        origin:
          type: array
          description: The list of policies that contributed to the 'conf'. The order is important as it reflects in what order confs were merged to get the resulting 'conf'.
          items:
            $ref: '#/components/schemas/ResourceRuleOrigin'
    Inbound:
      type: object
      required:
      - tags
      - port
      properties:
        name:
          type: string
        tags:
          type: object
          additionalProperties:
            type: string
          x-go-type: map[string]string
        port:
          type: integer
    InspectHostnames:
      type: object
      title: InspectHostnames
      description: A list of hostnames
      required:
      - total
      - items
      properties:
        total:
          type: integer
          example: 200
        items:
          type: array
          items:
            $ref: '#/components/schemas/InspectHostname'
    InspectHostnameZone:
      type: object
      title: InspectHostnameZone
      description: A name of the zone in which the hostname is available
      required:
      - name
      properties:
        name:
          type: string
          example: east
    InspectRule:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          example: MeshRetry
          description: the type of the policy
        proxyRule:
          $ref: '#/components/schemas/ProxyRule'
        toRules:
          type: array
          description: a set of rules for the outbounds of this proxy. The field is not set when 'meshService.mode' on Mesh is set to 'Exclusive'.
          items:
            $ref: '#/components/schemas/Rule'
        toResourceRules:
          type: array
          description: a set of rules for the outbounds produced by real resources (i.e MeshService, MeshExternalService, MeshMultiZoneService).
          items:
            $ref: '#/components/schemas/ResourceRule'
        fromRules:
          type: array
          description: a set of rules for each inbound of this proxy
          items:
            $ref: '#/components/schemas/FromRule'
        inboundRules:
          type: array
          description: a set of rules for each inbound port of the proxy. When the policy descriptor has 'isFromAsRules' set to true, this field supersedes 'fromRules' and should be used instead.
          items:
            $ref: '#/components/schemas/InboundRulesEntry'
        warnings:
          type: array
          description: a set of warnings to show in policy matching
          example:
          - Mesh is not Mtls enabled this policy will have no effect
          items:
            type: string
    InboundRulesEntry:
      type: object
      required:
      - inbound
      - rules
      properties:
        inbound:
          $ref: '#/components/schemas/Inbound'
        rules:
          type: array
          description: The 'rules' field is an array to allow for future expansion when 'matches' conditions are added. Currently, it contains a single item.
          items:
            $ref: '#/components/schemas/InboundRule'
    InspectHostname:
      type: object
      title: InspectHostname
      description: An supported hostname along with the zones it exists in
      required:
      - hostname
      - zones
      properties:
        hostname:
          type: string
          description: Generated hostname
          example: redis.redis-system.svc.east.mesh.local
        zones:
          type: array
          items:
            $ref: '#/components/schemas/InspectHostnameZone'
    RuleMatcher:
      type: object
      required:
      - key
      - value
      - not
      description: A matcher to select which traffic this conf applies to
      properties:
        key:
          type: string
          description: the key to match against
          example: kuma.io/service
        value:
          type: string
          description: the value for the key to match against
          example: my-cool-service
        not:
          type: boolean
          description: whether we check on the absence of this key:value pair
    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'
  examples:
    InspectHostnamesExample:
      value:
        total: 100
        items:
        - hostname: redis.redis-system.svc.east.mesh.local
          zones:
          - name: east
          - name: west
    InspectDataplanesForPolicyExample:
      value:
        total: 100
        next: http://localhost:5681/meshes/default/meshretries/_resources/dataplanes?offset=100
        items:
        - type: Dataplane
          mesh: default
          name: dp-1
          labels:
            k8s.kuma.io/namespace: kuma-system
        - type: Dataplane
          mesh: default
          name: dp-2
          labels:
            k8s.kuma.io/namespace: kuma-system
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer