Kuma Inspect API
The Inspect API from Kuma — 4 operation(s) for inspect.
Documentation
Documentation
https://kuma.io/docs/latest/reference/http-api/
GettingStarted
https://kuma.io/docs/latest/installation/
OpenAPI Specification
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