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

118 lines
3.8 KiB
Plaintext
Raw Normal View History

2019-07-09 02:11:19 +00:00
---
2020-04-07 18:55:19 +00:00
layout: docs
2020-04-06 20:27:35 +00:00
page_title: 'Configuration Entry Kind: Service Splitter'
sidebar_title: service-splitter
2020-04-07 18:55:19 +00:00
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).
2019-07-09 02:11:19 +00:00
---
# Service Splitter
2019-07-09 02:11:19 +00:00
-> **1.6.0+:** This config entry is available in Consul versions 1.6.0 and newer.
2019-07-09 02:11:19 +00:00
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
2020-04-09 23:46:54 +00:00
Management](/docs/connect/l7-traffic-management).
2019-07-09 02:11:19 +00:00
- Service splitter config entries are restricted to only services that define
their protocol as http-based via a corresponding
2020-04-09 23:46:54 +00:00
[`service-defaults`](/docs/agent/config-entries/service-defaults) config
2019-07-09 02:11:19 +00:00
entry or globally via
2020-04-09 23:46:54 +00:00
[`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) .
2019-07-09 02:11:19 +00:00
- 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
2020-04-09 23:46:54 +00:00
[`service-resolver`](/docs/agent/config-entries/service-resolver).
2019-07-09 02:11:19 +00:00
## Sample Config Entries
Split traffic between two subsets of the same service:
```hcl
Kind = "service-splitter"
Name = "web"
Splits = [
2019-07-09 02:11:19 +00:00
{
Weight = 90
ServiceSubset = "v1"
2019-07-09 02:11:19 +00:00
},
{
Weight = 10
ServiceSubset = "v2"
2019-07-09 02:11:19 +00:00
},
]
```
Split traffic between two services:
```hcl
Kind = "service-splitter"
Name = "web"
Splits = [
2019-07-09 02:11:19 +00:00
{
Weight = 50
2019-07-09 02:11:19 +00:00
# will default to service with same name as config entry ("web")
},
{
Weight = 10
Service = "web-rewrite"
2019-07-09 02:11:19 +00:00
},
]
```
## 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.
2019-07-09 02:11:19 +00:00
- `Splits` `(array<ServiceSplit>)` - Defines how much traffic to send to which
2020-04-06 20:27:35 +00:00
set of service instances during a traffic split. The sum of weights across
2019-07-09 02:11:19 +00:00
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
2020-08-17 16:17:51 +00:00
[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
2019-07-09 02:11:19 +00:00
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)