»Service Splitter Configuration Entry

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.

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

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

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

{
  "Kind": "service-splitter",
  "Name": "web",
  "Splits": [
    {
      "Weight": 50
    },
    {
      "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

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