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 to: description: To defines to which zones the traffic should be load balanced properties: type: description: Type defines how target zones will be picked from available zones enum: - None - Only - Any - AnyExcept type: string zones: items: type: string type: array required: - type type: object required: - to type: object type: array failoverThreshold: description: 'FailoverThreshold defines the percentage of live destination dataplane proxies below which load balancing to the next priority starts. Example: If you configure failoverThreshold to 70, and you have deployed 10 destination dataplane proxies. Load balancing to next priority will start when number of live destination dataplane proxies drops below 7. Default 50' properties: percentage: anyOf: - type: integer - type: string x-kubernetes-int-or-string: true required: - percentage type: object type: object disabled: description: 'Disabled allows to disable locality-aware load balancing. When disabled requests are distributed across all endpoints regardless of locality.' type: boolean localZone: description: LocalZone defines locality aware load balancing priorities between dataplane proxies inside a zone properties: affinityTags: description: AffinityTags list of tags for local zone load balancing. items: properties: key: description: Key defines tag for which affinity is configured type: string weight: description: 'Weight of the tag used for load balancing. The bigger the weight the bigger the priority. Percentage of local traffic load balanced to tag is computed by dividing weight by sum of weights from all tags. For example with two affinity tags first with weight 80 and second with weight 20, then 80% of traffic will be redirected to the first tag, and 20% of traffic will be redirected to second one. Setting weights is not mandatory. When weights are not set control plane will compute default weight based on list order. Default: If you do not specify weight we will adjust them so that 90% traffic goes to first tag, 9% to next, and 1% to third and so on.' format: int32 type: integer required: - key type: object type: array type: object type: object type: object targetRef: description: 'TargetRef is a reference to the resource that represents a group of destinations.' 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: - targetRef type: object type: array 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' 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 `:trace:`. ' 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