Service Splitter Configuration Entry

v1.8.4+: On Kubernetes, the ServiceSplitter custom resource is supported in Consul versions 1.8.4+.
v1.6.0+: On other platforms, this config entry is supported in Consul versions 1.6.0+.

The service-splitter config entry kind (ServiceSplitter on Kubernetes) 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.
Service splitter config entries are restricted to only services that define their protocol as http-based via a corresponding service-defaults config entry or globally via 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.

UI

Once a service-splitter is successfully entered, you can view it in the UI. Service routers, service splitters, and service resolvers can all be viewed by clicking on your service then switching to the routing tab.

screenshot of service splitter in the UI

Sample Config Entries

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
      # will default to service with same name as config 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"
      }
    }
  },
]

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

{
  "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"
        }
      }
    }
  ]
}

Available Fields

Kind - Must be set to service-splitter
Name (string: <required>) - Set to the name of the service being configured.
Namespace (string: "default")Enterprise - Specifies the namespace to which the configuration entry will apply.
Partition (string: "default")Enterprise - Specifies the admin partition to which the configuration entry will apply.
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: "")Enterprise - The namespace to resolve the service from instead of the current namespace. If empty, the current namespace is used.
- Partition (string: "")Enterprise - The admin partition to resolve the service from instead of the current partition. If empty, the current partition is used.
- RequestHeaders (HTTPHeaderModifiers: <optional>) - A set of HTTP-specific header modification rules that will be applied to requests routed to this split. This cannot be used with a tcp listener.
- ResponseHeaders (HTTPHeaderModifiers: <optional>) - A set of HTTP-specific header modification rules that will be applied to responses from this split. This cannot be used with a tcp listener.

apiVersion - Must be set to consul.hashicorp.com/v1alpha1
kind - Must be set to ServiceSplitter
metadata
- name - Set to the name of the service being configured.
- namespace - If running Consul Open Source, the namespace is ignored (see Kubernetes Namespaces in Consul OSS). If running Consul Enterprise see Kubernetes Namespaces in Consul Enterprise for more details.
spec
- 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: "")Enterprise - The namespace to resolve the service from instead of the current namespace. If empty, the current namespace is used.
  - partition (string: "")Enterprise - The admin partition to resolve the service from instead of the current partition. If empty, the current partition is used.
  - requestHeaders (HTTPHeaderModifiers: <optional>) - A set of HTTP-specific header modification rules that will be applied to requests routed to this split. This cannot be used with a tcp listener.
  - responseHeaders (HTTPHeaderModifiers: <optional>) - A set of HTTP-specific header modification rules that will be applied to responses from this split. This cannot be used with a tcp listener.

ACLs

Configuration entries may be protected by ACLs.

Reading a service-splitter config entry requires service:read on the resource.

Creating, updating, or deleting a service-splitter config entry requires service:write on the resource and service:read on any other service referenced by name in these fields:

Splits[].Service