consul/website/pages/docs/agent/config-entries/service-splitter.mdx

118 lines
3.8 KiB
Plaintext

---
layout: docs
page_title: 'Configuration Entry Kind: Service Splitter'
sidebar_title: service-splitter
description: >-
The service-splitter config entry kind controls how to split incoming Connect
requests across different subsets of a single service (like during staged
canary rollouts), or perhaps across different services (like during a v2
rewrite or other type of codebase migration).
---
# Service Splitter
-> **1.6.0+:** This config entry is available in Consul versions 1.6.0 and newer.
The `service-splitter` config entry kind controls how to split incoming Connect
requests across different subsets of a single service (like during staged
canary rollouts), or perhaps across different services (like during a v2
rewrite or other type of codebase migration).
If no splitter config is defined for a service it is assumed 100% of traffic
flows to a service with the same name and discovery continues on to the
resolution stage.
## Interaction with other Config Entries
- Service splitter config entries are a component of [L7 Traffic
Management](/docs/connect/l7-traffic-management).
- Service splitter config entries are restricted to only services that define
their protocol as http-based via a corresponding
[`service-defaults`](/docs/agent/config-entries/service-defaults) config
entry or globally via
[`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) .
- Any split destination that specifies a different `Service` field and omits
the `ServiceSubset` field is eligible for further splitting should a splitter
be configured for that other service, otherwise resolution proceeds according
to any configured
[`service-resolver`](/docs/agent/config-entries/service-resolver).
## Sample Config Entries
Split traffic between two subsets of the same service:
```hcl
kind = "service-splitter"
name = "web"
splits = [
{
weight = 90
service_subset = "v1"
},
{
weight = 10
service_subset = "v2"
},
]
```
Split traffic between two services:
```hcl
kind = "service-splitter"
name = "web"
splits = [
{
weight = 50
# will default to service with same name as config entry ("web")
},
{
weight = 10
service = "web-rewrite"
},
]
```
## Available Fields
- `Kind` - Must be set to `service-splitter`
- `Name` `(string: <required>)` - Set to the name of the service being configured.
- `Namespace` `(string: "default")` <EnterpriseAlert inline /> - Specifies the namespace the config entry will apply to.
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.
- `Splits` `(array<ServiceSplit>)` - Defines how much traffic to send to which
set of service instances during a traffic split. The sum of weights across
all splits must add up to 100.
- `Weight` `(float32: 0)` - A value between 0 and 100 reflecting what portion
of traffic should be directed to this split. The smallest representable
weight is 1/10000 or .01%
- `Service` `(string: "")` - The service to resolve instead of the default.
- `ServiceSubset` `(string: "")` - A named subset of the given service to
resolve instead of one defined as that service's `DefaultSubset`. If empty
the default subset is used.
- `Namespace` `(string: "")` - The namespace to resolve the service from
instead of the current namespace. If empty the current namespace is
assumed.
## ACLs
Configuration entries may be protected by
[ACLs](https://learn.hashicorp.com/consul/security-networking/production-acls).
Reading a `service-splitter` config entry requires `service:read` on itself.
Creating, updating, or deleting a `service-splitter` config entry requires
`service:write` on itself and `service:read` on any other service referenced by
name in these fields:
- [`Splits[].Service`](#service)