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.
This section provides details about the fields you can configure in the service splitter configuration entry.
<Tabs>
<Tab heading="HCL" group="hcl">
### `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` <EnterpriseAlert inline />
Specifies the [namespace](/consul/docs/enterprise/namespaces) to apply the configuration entry.
#### Values
- Default: None
- Data type: String
### `Partition` <EnterpriseAlert inline />
Specifies the [admin partition](/consul/docs/enterprise/admin-partitions) 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` <Enterprise inline/>
- `Partition` <Enterprise inline/>
- `RequestHeaders`
- `ResponseHeaders`
### `Splits[].Weight`
Specifies the percentage of traffic sent to the set of service instances specified in the [`Service`](#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` to `100`.
### `Splits[].Service`
Specifies the name of the service to resolve.
#### Values
- Default: Inherits the value of the [`Name`](#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](/consul/docs/connect/config-entries/service-resolver), 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.
Specifies the [admin partition](/consul/docs/enterprise/admin-partitions) 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](#partition).
- 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](#set-http-headers) for an example configuration.
#### Values
- Default: None
- Values: Object containing one or more fields that define header modification rules
- `Add`: Map of one or more key-value pairs
- `Set`: Map of one or more key-value pairs
- `Remove`: Map of one or more key-value pairs
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](#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](#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](#set-http-headers) for an example configuration.
#### Values
- Default: None
- Values: Object containing one or more fields that define header modification rules
- `Add`: Map of one or more string key-value pairs
- `Set`: Map of one or more string key-value pairs
- `Remove`: Map of one or more string key-value pairs
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](#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](#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.
</Tab>
<Tab heading="YAML" group="yaml">
### `apiVersion`
Kubernetes-only parameter that specifies the version of the Consul API that the configuration entry maps to Kubernetes configurations. The value must be `consul.hashicorp.com/v1alpha1`.
### `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 `serviceSplitter`.
### `metadata.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.
Specifies the Consul namespace to use for resolving the service. You can map Consul namespaces to Kubernetes Namespaces in different ways. Refer to [Custom Resource Definitions (CRDs) for Consul on Kubernetes](/consul/docs/k8s/crds#consul-enterprise) for additional information.
#### Values
- Default: None
- Data type: String
### `spec`
Kubernetes-only field that contains all of the configurations for service splitter pods.
#### Values
- Default: none
- This field is required.
- Data type: Object containing [`spec.splits`](#spec-splits) configuration
### `spec.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
### `spec.splits`
Defines how much traffic to send to sets of service instances during a traffic split.
Specifies the percentage of traffic sent to the set of service instances specified in the [`spec.splits.service`](#spec-splits-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`.
Specifies which [admin partition](/consul/docs/enterprise/admin-partitions) to use in the FQDN when resolving the service.
#### Values
- Default: `default`
- Data type: String
### `spec.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](#set-http-headers) for an example configuration.
#### Values
- Default: None
- Values: Object containing one or more fields that define header modification rules
- `add`: Map of one or more key-value pairs
- `set`: Map of one or more key-value pairs
- `remove`: Map of one or more key-value pairs
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](#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](#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.
### `spec.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](#set-http-headers) for an example configuration.
#### Values
- Default: None
- Values: Object containing one or more fields that define header modification rules
- `add`: Map of one or more string key-value pairs
- `set`: Map of one or more string key-value pairs
- `remove`: Map of one or more string key-value pairs
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](#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](#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.
</Tab>
</Tabs>
## Examples
The following examples demonstrate common service splitter configuration patterns for specific use cases.
