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 | required
Name: string | required
Namespace: string Enterprise
Partition: string Enterprise
Meta: map
Splits: map | required
- Weight: number | required
- Service: string | required
- ServiceSubset: string
- Namespace: string Enterprise
- Partition: string Enterprise
- RequestHeaders: map
  - Add: map
  - Set: map
  - Remove: map
- ResponseHeaders: map
  - Add: map
  - Set: map
  - Remove: map

apiVersion: string | required
kind: string | required
metadata: object | required
- name: string | required
- namespace: string | optional Enterprise
spec: object | required
- splits: list | required
  - weight: float32 | required
  - service: string | required
  - serviceSubset: string
  - namespace: string Enterprise
  - partition: string Enterprise
  - requestHeaders: HTTPHeaderModifiers
    - add: map
    - set: map
    - remove: map
  - responseHeaders: HTTPHeaderModifiers
    - add: map
    - set: map
    - remove: map

Complete configuration

When every field is defined, a service splitter configuration entry has the following form:

Kind      = "service-splitter"           ## string  | required
Name      = "config-entry-name"          ## string  | required
Namespace = "main"                       ## string
Partition = "partition"                  ## string 
Meta = {                                 ## map
  key = "value"
}
Splits = [                               ## list    | required
  {                                      ## map
    Weight        = 90                   ## number  | required
    Service       = "service"            ## string
    ServiceSubset = "v1"                 ## string
    Namespace     = "target-namespace"   ## string
    Partition     = "target-partition"   ## string
    RequestHeaders = {                   ## map
      Set = {
        "X-Web-Version" : "from-v1"
      }
    }
    ResponseHeaders = {                  ## map
      Set = {
        "X-Web-Version" : "to-v1"
      }
    }
  },
  {
    Weight        = 10
    Service       = "service"
    ServiceSubset = "v2"
    Namespace     = "target-namespace"
    Partition     = "target-partition"
    RequestHeaders = {
      Set = {
        "X-Web-Version" : "from-v2"
      }
    }
    ResponseHeaders = {
      Set = {
        "X-Web-Version" : "to-v2"
      }
    }
  }
]

{
  "Kind" : "service-splitter",           ## string  | required
  "Name" : "config-entry-name",          ## string  | required
  "Namespace" : "main",                  ## string
  "Partition" : "partition",             ## string 
  "Meta" : {                             ## map
    "_key_" : "_value_"            
  },
  "Splits" : [                           ## list    | required
    {                                    ## map     
      "Weight" : 90,                     ## number  | required
      "Service" : "service",             ## string     
      "ServiceSubset" : "v1",            ## string
      "Namespace" : "target-namespace",  ## string
      "Partition" : "target-partition",  ## string
      "RequestHeaders" : {               ## map
        "Set" : {
          "X-Web-Version": "from-v1"
          }
      },
      "ResponseHeaders" : {              ## map
        "Set" : {
          "X-Web-Version": "to-v1"
          }
      }
    },
    {
      "Weight" : 10,            
      "Service" : "service",    
      "ServiceSubset" : "v2",          
      "Namespace" : "target-namespace",  
      "Partition" : "target-partition",  
      "RequestHeaders" : {
        "Set" : {
          "X-Web-Version": "from-v2"
          }
      },
      "ResponseHeaders" : {
        "Set" : {
          "X-Web-Version": "to-v2"
        }
      }
    }
  ]
}

apiVersion: consul.hashicorp.com/v1alpha1         # string | required
kind: ServiceSplitter                             # string | required
metadata:                                         # object | required
  name: config-entry-name                         # string | required
  namespace: main                                 # string
spec:
  splits:                                         # list
    - weight: 90                                  # floating point | required
      service: service                            # string 
      serviceSubset: v1                           # string 
      namespace: target-namespace                 # string 
      partition: target-partition                 # string 
      requestHeaders:  
        set:
          x-web-version: from-v1                  # string 
      responseHeaders:
        set:
          x-web-version: to-v1                    # string 
    - weight: 10
      service: service
      serviceSubset: v2
      namespace: target-namespace
      partition: target-partition
      requestHeaders:
        set:
          x-web-version: from-v2
      responseHeaders:
        set:
          x-web-version: to-v2

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 to 100.

`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
- 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.	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
- 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.	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

`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`

Values

Default: Inherits name from the host node
This field is required.
Data type: String

`metadata.namespace` Enterprise

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 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 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.

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. The total defined value must add up to 100.
- service: This field is required.
- serviceSubset
- namespace
- partition
- requestHeaders
- responseHeaders

`spec.splits[].weight`

Specifies the percentage of traffic sent to the set of service instances specified in the 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.

Values

Default: null
This field is required.
Data type: Floating integer from .01 to 100

`spec.splits[].service`

Specifies the name of the service to resolve.

Values

Default: The service matching the configuration entry meta.name field.
Data type: String

`spec.splits[].serviceSubset`

Specifies a subset of the service to resolve. This field overrides the DefaultSubset.

Values

Default: Inherits the name of the default subset.
Data type: String

`spec.splits[].namespace` Enterprise

Specifies the namespace to use when resolving the service.

Values

Default: The namespace specified in the top-level configuration entry.
Data type: String

`spec.splits[].partition` Enterprise

Specifies which admin partition to use in the FQDN when resolving the service.

Values

Default: default
Data type: String

`spec.splits[].requestHeaders`

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.	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.

`spec.splits[].responseHeaders`

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.	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

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:

Kind = "service-splitter"
Name = "web"
Splits = [
  {
    Weight        = 90
    ServiceSubset = "v1"
  },
  {
    Weight        = 10
    ServiceSubset = "v2"
  },
]

Two different services

Split traffic between two services:

Kind = "service-splitter"
Name = "web"
Splits = [
  {
    Weight  = 50
    # will default to service with same name as config entry ("web")
  },
  {
    Weight  = 50
    Service = "web-rewrite"
  },
]

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceSplitter
metadata:
  name: web
spec:
  splits:
    - weight: 50
      # defaults to the service with same name as the configuration entry ("web")
    - weight: 50
      service: web-rewrite

Set HTTP Headers

Split traffic between two subsets with extra headers added so clients can tell which version:

Kind = "service-splitter"
Name = "web"
Splits = [
  {
    Weight        = 90
    ServiceSubset = "v1"
    ResponseHeaders {
      Set {
        "X-Web-Version": "v1"
      }
    }
  },
  {
    Weight        = 10
    ServiceSubset = "v2"
    ResponseHeaders {
      Set {
        "X-Web-Version": "v2"
      }
    }
  },
]

{
  "Kind": "service-splitter",
  "Name": "web",
  "Splits": [
    {
      "Weight": 90,
      "ServiceSubset": "v1",
      "ResponseHeaders": {
        "Set": {
          "X-Web-Version": "v1"
        }
      }
    },
    {
      "Weight": 10,
      "ServiceSubset": "v2",
      "ResponseHeaders": {
        "Set": {
          "X-Web-Version": "v2"
        }
      }
    }
  ]
}

apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceSplitter
metadata:
  name: web
spec:
  splits:
    - weight: 90
      serviceSubset: v1
      responseHeaders:
        set:
          x-web-version: v1
    - weight: 10
      serviceSubset: v2
      responseHeaders:
        set:
          x-web-version: v2

Service Splitter configuration reference

Configuration model

Complete configuration

Specification

Kind

Values

Name

Values

Namespace EnterpriseEnterprise

Values

Partition EnterpriseEnterprise

Values

Meta

Values

Splits

Values

Splits[].Weight

Values

Splits[].Service

Values

Splits[].ServiceSubset

Values

Splits[].Namespace EnterpriseEnterprise

Values

Splits[].Partition EnterpriseEnterprise

Values

Splits[].RequestHeaders

Values

Use variable placeholders

Splits[].ResponseHeaders

Values

Use variable placeholders

Examples

Two subsets of same service

Two different services

Set HTTP Headers

`Kind`

`Name`

`Namespace` Enterprise

`Partition` Enterprise

`Meta`

`Splits`

`Splits[].Weight`

`Splits[].Service`

`Splits[].ServiceSubset`

`Splits[].Namespace` Enterprise

`Splits[].Partition` Enterprise

`Splits[].RequestHeaders`

`Splits[].ResponseHeaders`