The MeshAccessLog API from Kuma — 2 operation(s) for meshaccesslog.
openapi: 3.1.0
info:
title: Kuma Dataplane MeshAccessLog API
description: Kuma API
version: v1alpha1
x-ref-schema-name: DataplaneOverview
security:
- BasicAuth: []
- BearerAuth: []
- {}
tags:
- name: MeshAccessLog
paths:
/meshes/{mesh}/meshaccesslogs/{name}:
get:
operationId: getMeshAccessLog
summary: Returns MeshAccessLog entity
tags:
- MeshAccessLog
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 MeshAccessLog
responses:
'200':
$ref: '#/components/responses/MeshAccessLogItem'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: putMeshAccessLog
summary: Creates or Updates MeshAccessLog entity
tags:
- MeshAccessLog
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 MeshAccessLog
requestBody:
description: Put request
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MeshAccessLogItem'
responses:
'200':
$ref: '#/components/responses/MeshAccessLogCreateOrUpdateSuccessResponse'
'201':
$ref: '#/components/responses/MeshAccessLogCreateOrUpdateSuccessResponse'
delete:
operationId: deleteMeshAccessLog
summary: Deletes MeshAccessLog entity
tags:
- MeshAccessLog
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 MeshAccessLog
responses:
'200':
$ref: '#/components/responses/MeshAccessLogDeleteSuccessResponse'
'404':
$ref: '#/components/responses/NotFound'
/meshes/{mesh}/meshaccesslogs:
get:
operationId: getMeshAccessLogList
summary: Returns a list of MeshAccessLog in the mesh.
tags:
- MeshAccessLog
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/MeshAccessLogList'
components:
responses:
NotFound:
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundError'
MeshAccessLogCreateOrUpdateSuccessResponse:
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
MeshAccessLogDeleteSuccessResponse:
description: Successful response
content:
application/json:
schema:
type: object
MeshAccessLogItem:
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/MeshAccessLogItem'
MeshAccessLogList:
description: List
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/MeshAccessLogItem'
total:
type: number
description: The total number of entities
next:
type: string
description: URL to the next page
schemas:
MeshAccessLogItem:
type: object
description: MeshAccessLog configures access logging for traffic between services in the mesh. It allows you to capture and export request/response logs to various backends (file, TCP, or OpenTelemetry) for monitoring, debugging, and auditing purposes.
required:
- type
- name
- spec
properties:
type:
description: the type of the resource
type: string
enum:
- MeshAccessLog
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_mal_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 MeshAccessLog resource.
properties:
from:
description: From list makes a match between clients and corresponding configurations
items:
properties:
default:
description: 'Default is a configuration specific to the group of clients referenced in
''targetRef'''
properties:
backends:
items:
properties:
file:
description: FileBackend defines configuration for file based access logs
properties:
format:
description: 'Format of access logs. Placeholders available on
https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators'
properties:
json:
example:
- key: start_time
value: '%START_TIME%'
- key: bytes_received
value: '%BYTES_RECEIVED%'
items:
properties:
key:
type: string
value:
type: string
required:
- key
- value
type: object
type: array
omitEmptyValues:
default: false
type: boolean
plain:
example: '[%START_TIME%] %KUMA_MESH% %UPSTREAM_HOST%'
type: string
type:
enum:
- Plain
- Json
type: string
required:
- type
type: object
path:
description: Path to a file that logs will be written to
example: /tmp/access.log
minLength: 1
type: string
required:
- path
type: object
openTelemetry:
description: Defines an OpenTelemetry logging backend.
properties:
attributes:
description: 'Attributes can contain placeholders available on
https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators'
example:
- key: mesh
value: '%KUMA_MESH%'
items:
properties:
key:
type: string
value:
type: string
required:
- key
- value
type: object
type: array
backendRef:
description: 'BackendRef is a reference to a MeshOpenTelemetryBackend resource that
defines the collector endpoint. Mutually exclusive with Endpoint.'
properties:
kind:
description: Kind of the backend resource.
enum:
- MeshOpenTelemetryBackend
type: string
labels:
additionalProperties:
type: string
description: 'Labels to match the referenced resource. Use for cross-zone references
where KDS adds a hash suffix to metadata.name. Mutually exclusive with
Name. When multiple resources match, the oldest by creation time wins.'
type: object
name:
description: 'Name of the referenced resource (metadata.name). Use for same-cluster
references. Mutually exclusive with Labels.'
type: string
required:
- kind
type: object
body:
description: 'Body is a raw string or an OTLP any value as described at
https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-body
It can contain placeholders available on
https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators'
example:
kvlistValue:
values:
- key: mesh
value:
stringValue: '%KUMA_MESH%'
x-kubernetes-preserve-unknown-fields: true
endpoint:
default: ''
description: 'Endpoint of OpenTelemetry collector. An empty port defaults to 4317.
Deprecated: use BackendRef instead.'
example: otel-collector:4317
type: string
type: object
tcp:
description: TCPBackend defines a TCP logging backend.
properties:
address:
description: Address of the TCP logging backend
example: 127.0.0.1:5000
minLength: 1
type: string
format:
description: 'Format of access logs. Placeholders available on
https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators'
properties:
json:
example:
- key: start_time
value: '%START_TIME%'
- key: bytes_received
value: '%BYTES_RECEIVED%'
items:
properties:
key:
type: string
value:
type: string
required:
- key
- value
type: object
type: array
omitEmptyValues:
default: false
type: boolean
plain:
example: '[%START_TIME%] %KUMA_MESH% %UPSTREAM_HOST%'
type: string
type:
enum:
- Plain
- Json
type: string
required:
- type
type: object
required:
- address
type: object
type:
enum:
- Tcp
- File
- OpenTelemetry
type: string
required:
- type
type: object
type: array
type: object
targetRef:
description: 'TargetRef is a reference to the resource that represents a group of
clients.'
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
required:
- default
- targetRef
type: object
type: array
rules:
description: 'Rules defines inbound access log configurations. Currently limited to
selecting all inbound traffic, as L7 matching is not yet implemented.'
items:
properties:
default:
description: Default contains configuration of the inbound access logging
properties:
backends:
items:
properties:
file:
description: FileBackend defines configuration for file based access logs
properties:
format:
description: 'Format of access logs. Placeholders available on
https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators'
properties:
json:
example:
- key: start_time
value: '%START_TIME%'
- key: bytes_received
value: '%BYTES_RECEIVED%'
items:
properties:
key:
type: string
value:
type: string
required:
- key
- value
type: object
type: array
omitEmptyValues:
default: false
type: boolean
plain:
example: '[%START_TIME%] %KUMA_MESH% %UPSTREAM_HOST%'
type: string
type:
enum:
- Plain
- Json
type: string
required:
- type
type: object
path:
description: Path to a file that logs will be written to
example: /tmp/access.log
minLength: 1
type: string
required:
- path
type: object
openTelemetry:
description: Defines an OpenTelemetry logging backend.
properties:
attributes:
description: 'Attributes can contain placeholders available on
https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators'
example:
- key: mesh
value: '%KUMA_MESH%'
items:
properties:
key:
type: string
value:
type: string
required:
- key
- value
type: object
type: array
backendRef:
description: 'BackendRef is a reference to a MeshOpenTelemetryBackend resource that
defines the collector endpoint. Mutually exclusive with Endpoint.'
properties:
kind:
description: Kind of the backend resource.
enum:
- MeshOpenTelemetryBackend
type: string
labels:
additionalProperties:
type: string
description: 'Labels to match the referenced resource. Use for cross-zone references
where KDS adds a hash suffix to metadata.name. Mutually exclusive with
Name. When multiple resources match, the oldest by creation time wins.'
type: object
name:
description: 'Name of the referenced resource (metadata.name). Use for same-cluster
references. Mutually exclusive with Labels.'
type: string
required:
- kind
type: object
body:
description: 'Body is a raw string or an OTLP any value as described at
https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-body
It can contain placeholders available on
https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators'
example:
kvlistValue:
values:
- key: mesh
value:
stringValue: '%KUMA_MESH%'
x-kubernetes-preserve-unknown-fields: true
endpoint:
default: ''
description: 'Endpoint of OpenTelemetry collector. An empty port defaults to 4317.
Deprecated: use BackendRef instead.'
example: otel-collector:4317
type: string
type: object
tcp:
description: TCPBackend defines a TCP logging backend.
properties:
address:
description: Address of the TCP logging backend
example: 127.0.0.1:5000
minLength: 1
type: string
format:
description: 'Format of access logs. Placeholders available on
https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators'
properties:
json:
example:
- key: start_time
value: '%START_TIME%'
- key: bytes_received
value: '%BYTES_RECEIVED%'
items:
properties:
key:
type: string
value:
type: string
required:
- key
- value
type: object
type: array
omitEmptyValues:
default: false
type: boolean
plain:
example: '[%START_TIME%] %KUMA_MESH% %UPSTREAM_HOST%'
type: string
type:
enum:
- Plain
- Json
type: string
required:
- type
type: object
required:
- address
type: object
type:
enum:
- Tcp
- File
- OpenTelemetry
type: string
required:
- type
type: object
type: array
type: object
required:
- default
type: object
type: array
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
to:
description: To list makes a match between the consumed services and corresponding configurations
items:
properties:
default:
description: 'Default is a configuration specific to the group of destinations referenced in
''targetRef'''
properties:
backends:
items:
properties:
file:
description: FileBackend defines configuration for file based access logs
# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kuma/refs/heads/main/openapi/kuma-meshaccesslog-api-openapi.yml