The MeshLoadBalancingStrategy API from Kuma — 2 operation(s) for meshloadbalancingstrategy.
openapi: 3.1.0
info:
title: Kuma Dataplane MeshLoadBalancingStrategy API
description: Kuma API
version: v1alpha1
x-ref-schema-name: DataplaneOverview
security:
- BasicAuth: []
- BearerAuth: []
- {}
tags:
- name: MeshLoadBalancingStrategy
paths:
/meshes/{mesh}/meshloadbalancingstrategies/{name}:
get:
operationId: getMeshLoadBalancingStrategy
summary: Returns MeshLoadBalancingStrategy entity
tags:
- MeshLoadBalancingStrategy
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 MeshLoadBalancingStrategy
responses:
'200':
$ref: '#/components/responses/MeshLoadBalancingStrategyItem'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: putMeshLoadBalancingStrategy
summary: Creates or Updates MeshLoadBalancingStrategy entity
tags:
- MeshLoadBalancingStrategy
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 MeshLoadBalancingStrategy
requestBody:
description: Put request
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MeshLoadBalancingStrategyItem'
responses:
'200':
$ref: '#/components/responses/MeshLoadBalancingStrategyCreateOrUpdateSuccessResponse'
'201':
$ref: '#/components/responses/MeshLoadBalancingStrategyCreateOrUpdateSuccessResponse'
delete:
operationId: deleteMeshLoadBalancingStrategy
summary: Deletes MeshLoadBalancingStrategy entity
tags:
- MeshLoadBalancingStrategy
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 MeshLoadBalancingStrategy
responses:
'200':
$ref: '#/components/responses/MeshLoadBalancingStrategyDeleteSuccessResponse'
'404':
$ref: '#/components/responses/NotFound'
/meshes/{mesh}/meshloadbalancingstrategies:
get:
operationId: getMeshLoadBalancingStrategyList
summary: Returns a list of MeshLoadBalancingStrategy in the mesh.
tags:
- MeshLoadBalancingStrategy
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/MeshLoadBalancingStrategyList'
components:
responses:
NotFound:
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/NotFoundError'
MeshLoadBalancingStrategyDeleteSuccessResponse:
description: Successful response
content:
application/json:
schema:
type: object
MeshLoadBalancingStrategyList:
description: List
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/MeshLoadBalancingStrategyItem'
total:
type: number
description: The total number of entities
next:
type: string
description: URL to the next page
MeshLoadBalancingStrategyItem:
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/MeshLoadBalancingStrategyItem'
MeshLoadBalancingStrategyCreateOrUpdateSuccessResponse:
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
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
MeshLoadBalancingStrategyItem:
type: object
description: MeshLoadBalancingStrategy configures how traffic is distributed across service instances. It supports multiple load balancing algorithms (round-robin, least request, ring hash, random, maglev), locality-aware routing to prefer nearby instances, and cross-zone failover strategies for high availability.
required:
- type
- name
- spec
properties:
type:
description: the type of the resource
type: string
enum:
- MeshLoadBalancingStrategy
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_mlbs_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 MeshLoadBalancingStrategy resource.
properties:
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 inplace.'
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:
hashPolicies:
description: 'HashPolicies specify a list of request/connection properties that are used to calculate a hash.
These hash policies are executed in the specified order. If a hash policy has the “terminal” attribute
set to true, and there is already a hash generated, the hash is returned immediately,
ignoring the rest of the hash policy list.'
items:
properties:
connection:
properties:
sourceIP:
description: Hash on source IP address.
type: boolean
type: object
cookie:
properties:
name:
description: The name of the cookie that will be used to obtain the hash key.
minLength: 1
type: string
path:
description: The name of the path for the cookie.
type: string
ttl:
description: If specified, a cookie with the TTL will be generated if the cookie is not present.
type: string
required:
- name
type: object
filterState:
properties:
key:
description: 'The name of the Object in the per-request filterState, which is
an Envoy::Hashable object. If there is no data associated with the key,
or the stored object is not Envoy::Hashable, no hash will be produced.'
minLength: 1
type: string
required:
- key
type: object
header:
properties:
name:
description: The name of the request header that will be used to obtain the hash key.
minLength: 1
type: string
required:
- name
type: object
queryParameter:
properties:
name:
description: 'The name of the URL query parameter that will be used to obtain the hash key.
If the parameter is not present, no hash will be produced. Query parameter names
are case-sensitive.'
minLength: 1
type: string
required:
- name
type: object
terminal:
description: 'Terminal is a flag that short-circuits the hash computing. This field provides
a ‘fallback’ style of configuration: “if a terminal policy doesn’t work, fallback
to rest of the policy list”, it saves time when the terminal policy works.
If true, and there is already a hash computed, ignore rest of the list of hash polices.'
type: boolean
type:
enum:
- Header
- Cookie
- Connection
- SourceIP
- QueryParameter
- FilterState
type: string
required:
- type
type: object
type: array
loadBalancer:
description: LoadBalancer allows to specify load balancing algorithm.
properties:
leastRequest:
description: 'LeastRequest selects N random available hosts as specified in ''choiceCount'' (2 by default)
and picks the host which has the fewest active requests'
properties:
activeRequestBias:
anyOf:
- type: integer
- type: string
description: 'ActiveRequestBias refers to dynamic weights applied when hosts have varying load
balancing weights. A higher value here aggressively reduces the weight of endpoints
that are currently handling active requests. In essence, the higher the ActiveRequestBias
value, the more forcefully it reduces the load balancing weight of endpoints that are
actively serving requests.'
x-kubernetes-int-or-string: true
choiceCount:
description: 'ChoiceCount is the number of random healthy hosts from which the host with
the fewest active requests will be chosen. Defaults to 2 so that Envoy performs
two-choice selection if the field is not set.'
format: int32
minimum: 2
type: integer
type: object
maglev:
description: 'Maglev implements consistent hashing to upstream hosts. Maglev can be used as
a drop in replacement for the ring hash load balancer any place in which
consistent hashing is desired.'
properties:
hashPolicies:
description: 'HashPolicies specify a list of request/connection properties that are used to calculate a hash.
These hash policies are executed in the specified order. If a hash policy has the “terminal” attribute
set to true, and there is already a hash generated, the hash is returned immediately,
ignoring the rest of the hash policy list.'
items:
properties:
connection:
properties:
sourceIP:
description: Hash on source IP address.
type: boolean
type: object
cookie:
properties:
name:
description: The name of the cookie that will be used to obtain the hash key.
minLength: 1
type: string
path:
description: The name of the path for the cookie.
type: string
ttl:
description: If specified, a cookie with the TTL will be generated if the cookie is not present.
type: string
required:
- name
type: object
filterState:
properties:
key:
description: 'The name of the Object in the per-request filterState, which is
an Envoy::Hashable object. If there is no data associated with the key,
or the stored object is not Envoy::Hashable, no hash will be produced.'
minLength: 1
type: string
required:
- key
type: object
header:
properties:
name:
description: The name of the request header that will be used to obtain the hash key.
minLength: 1
type: string
required:
- name
type: object
queryParameter:
properties:
name:
description: 'The name of the URL query parameter that will be used to obtain the hash key.
If the parameter is not present, no hash will be produced. Query parameter names
are case-sensitive.'
minLength: 1
type: string
required:
- name
type: object
terminal:
description: 'Terminal is a flag that short-circuits the hash computing. This field provides
a ‘fallback’ style of configuration: “if a terminal policy doesn’t work, fallback
to rest of the policy list”, it saves time when the terminal policy works.
If true, and there is already a hash computed, ignore rest of the list of hash polices.'
type: boolean
type:
enum:
- Header
- Cookie
- Connection
- SourceIP
- QueryParameter
- FilterState
type: string
required:
- type
type: object
type: array
tableSize:
description: 'The table size for Maglev hashing. Maglev aims for “minimal disruption”
rather than an absolute guarantee. Minimal disruption means that when
the set of upstream hosts change, a connection will likely be sent
to the same upstream as it was before. Increasing the table size reduces
the amount of disruption. The table size must be prime number limited to 5000011.
If it is not specified, the default is 65537.'
format: int32
maximum: 5000011
minimum: 1
type: integer
type: object
random:
description: 'Random selects a random available host. The random load balancer generally
performs better than round-robin if no health checking policy is configured.
Random selection avoids bias towards the host in the set that comes after a failed host.'
type: object
ringHash:
description: 'RingHash implements consistent hashing to upstream hosts. Each host is mapped
onto a circle (the “ring”) by hashing its address; each request is then routed
to a host by hashing some property of the request, and finding the nearest
corresponding host clockwise around the ring.'
properties:
hashFunction:
description: 'HashFunction is a function used to hash hosts onto the ketama ring.
The value defaults to XX_HASH. Available values – XX_HASH, MURMUR_HASH_2.'
enum:
- XXHash
- MurmurHash2
type: string
hashPolicies:
description: 'HashPolicies specify a list of request/connection properties that are used to calculate a hash.
These hash policies are executed in the specified order. If a hash policy has the “terminal” attribute
set to true, and there is already a hash generated, the hash is returned immediately,
ignoring the rest of the hash policy list.'
items:
properties:
connection:
properties:
sourceIP:
description: Hash on source IP address.
type: boolean
type: object
cookie:
properties:
name:
description: The name of the cookie that will be used to obtain the hash key.
minLength: 1
type: string
path:
description: The name of the path for the cookie.
type: string
ttl:
description: If specified, a cookie with the TTL will be generated if the cookie is not present.
type: string
required:
- name
type: object
filterState:
properties:
key:
description: 'The name of the Object in the per-request filterState, which is
an Envoy::Hashable object. If there is no data associated with the key,
or the stored object is not Envoy::Hashable, no hash will be produced.'
minLength: 1
type: string
required:
- key
type: object
header:
properties:
name:
description: The name of the request header that will be used to obtain the hash key.
minLength: 1
type: string
required:
- name
type: object
queryParameter:
properties:
name:
description: 'The name of the URL query parameter that will be used to obtain the hash key.
If the parameter is not present, no hash will be produced. Query parameter names
are case-sensitive.'
minLength: 1
type: string
required:
- name
type: object
terminal:
description: 'Terminal is a flag that short-circuits the hash computing. This field provides
a ‘fallback’ style of configuration: “if a terminal policy doesn’t work, fallback
to rest of the policy list”, it saves time when the terminal policy works.
If true, and there is already a hash computed, ignore rest of the list of hash polices.'
type: boolean
type:
enum:
- Header
- Cookie
- Connection
- SourceIP
- QueryParameter
- FilterState
type: string
required:
- type
type: object
type: array
maxRingSize:
description: 'Maximum hash ring size. Defaults to 8M entries, and limited to 8M entries,
but can be lowered to further constrain resource use.'
format: int32
maximum: 8000000
minimum: 1
type: integer
minRingSize:
description: 'Minimum hash ring size. The larger the ring is (that is,
the more hashes there are for each provided host) the better the request distribution
will reflect the desired weights. Defaults to 1024 entries, and limited to 8M entries.'
format: int32
maximum: 8000000
minimum: 1
type: integer
type: object
roundRobin:
description: 'RoundRobin is a load balancing algorithm that distributes requests
across available upstream hosts in round-robin order.'
type: object
type:
enum:
- RoundRobin
- LeastRequest
- RingHash
- Random
- Maglev
type: string
required:
- type
type: object
localityAwareness:
description: LocalityAwareness contains configuration for locality aware load balancing.
properties:
crossZone:
description: 'CrossZone defines locality aware load balancing priorities when dataplane proxies inside local zone
are unavailable'
properties:
failover:
description: Failover defines list of load balancing rules in order of priority
items:
properties:
from:
description: From defines the list of zones to which the rule applies
properties:
zones:
items:
type: string
type: array
required:
- zones
type: object
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kuma/refs/heads/main/openapi/kuma-meshloadbalancingstrategy-api-openapi.yml