Service Splitter Configuration Reference
This reference page describes the structure and contents of service splitter configuration entries. Configure and apply service splitters to redirect a percentage of incoming traffic requests for a service to one or more specific service instances.
Configuration model
The following list outlines field hierarchy, language-specific data types, and requirements in a service splitter configuration entry. Click on a property name to view additional details, including default values.
Kind
: string | requiredName
: string | requiredNamespace
: string EnterprisePartition
: string EnterpriseMeta
: mapSplits
: map | requiredWeight
: number | requiredService
: string | requiredServiceSubset
: stringNamespace
: string EnterprisePartition
: string EnterpriseRequestHeaders
: mapResponseHeaders
: map
Complete configuration
When every field is defined, a service splitter configuration entry has the following form:
Specification
This section provides details about the fields you can configure in the service splitter configuration entry.
Kind
Specifies the type of configuration entry to implement.
Values
- Default: none
- This field is required.
- Data type: String value that must be set to
service-splitter
.
Name
Specifies a name for the configuration entry. The name is metadata that you can use to reference the configuration entry when performing Consul operations, such as applying a configuration entry to a specific cluster.
Values
- Default: Defaults to the name of the node after writing the entry to the Consul server.
- This field is required.
- Data type: String
Namespace
Enterprise
Specifies the namespace to apply the configuration entry.
Values
- Default: None
- Data type: String
Partition
Enterprise
Specifies the admin partition to apply the configuration entry.
Values
- Default:
Default
- Data type: String
Meta
Specifies key-value pairs to add to the KV store.
Values
- Default: none
- Data type: Map of one or more key-value pairs
- keys: String
- values: String, integer, or float
Splits
Defines how much traffic to send to sets of service instances during a traffic split.
Values
- Default: None
- This field is required.
- Data type: list of objects that can contain the following fields:
Weight
: The sum of weights for a set of service instances must add up to 100.Service
: This field is required.ServiceSubset
Namespace
Partition
RequestHeaders
ResponseHeaders
Splits[].Weight
Specifies the percentage of traffic sent to the set of service instances specified in the Service
field. Each weight must be a floating integer between 0
and 100
. The smallest representable value is .01
. The sum of weights across all splits must add up to 100
.
Values
- Default:
null
- This field is required.
- Data type: Floating number from
.01
to100
.
Splits[].Service
Specifies the name of the service to resolve.
Values
- Default: Inherits the value of the
Name
field. - Data type: String
Splits[].ServiceSubset
Specifies a subset of the service to resolve. A service subset assigns a name to a specific subset of discoverable service instances within a datacenter, such as version2
or canary
. All services have an unnamed default subset that returns all healthy instances.
You can define service subsets in a service resolver configuration entry, which are referenced by their names throughout the other configuration entries. This field overrides the default subset value in the service resolver configuration entry.
Values
- Default: If empty, the
split
uses the default subset. - Data type: String
Splits[].Namespace
Enterprise
Specifies the namespace to use in the FQDN when resolving the service.
Values
- Default: Inherits the value of
Namespace
from the top-level of the configuration entry. - Data type: String
Splits[].Partition
Enterprise
Specifies the admin partition to use in the FQDN when resolving the service.
Values
- Default: By default, the
service-splitter
uses the admin partition specified in the top-level configuration entry. - Data type: String
Splits[].RequestHeaders
Specifies a set of HTTP-specific header modification rules applied to requests routed with the service split. You cannot configure request headers if the listener protocol is set to tcp
. Refer to Set HTTP Headers for an example configuration.
Values
- Default: None
- Values: Object containing one or more fields that define header modification rules
The following table describes how to configure values for request headers:
Rule | Description | Type |
---|---|---|
Add | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can use variable placeholders. | map of strings |
Set | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can use variable placeholders. | map of strings |
Remove | Defines an list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings |
Use variable placeholders
For Add
and Set
, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable %DOWNSTREAM_REMOTE_ADDRESS%
in your configuration entry allows you to pass a value that is generated when the split occurs.
Splits[].ResponseHeaders
Specifies a set of HTTP-specific header modification rules applied to responses routed with the service split. You cannot configure request headers if the listener protocol is set to tcp
. Refer to Set HTTP Headers for an example configuration.
Values
- Default: None
- Values: Object containing one or more fields that define header modification rules
The following table describes how to configure values for response headers:
Rule | Description | Type |
---|---|---|
Add | Defines a set of key-value pairs to add to the header. Use header names as the keys. Header names are not case-sensitive. If header values with the same name already exist, the value is appended and Consul applies both headers. You can use variable placeholders. | map of strings |
Set | Defines a set of key-value pairs to add to the request header or to replace existing header values with. Use header names as the keys. Header names are not case-sensitive. If header values with the same names already exist, Consul replaces the header values. You can use variable placeholders. | map of strings |
Remove | Defines an list of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | list of strings |
Use variable placeholders
For Add
and Set
, if the service is configured to use Envoy as the proxy, the value may contain variables to interpolate dynamic metadata into the value. For example, using the variable %DOWNSTREAM_REMOTE_ADDRESS%
in your configuration entry allows you to pass a value that is generated when the split occurs.
Examples
The following examples demonstrate common service splitter configuration patterns for specific use cases.
Two subsets of same service
Split traffic between two subsets of the same service:
Two different services
Split traffic between two services:
Set HTTP Headers
Split traffic between two subsets with extra headers added so clients can tell which version: