Service Splitter

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.

Sample Config Entries

Two subsets of same service

Split traffic between two subsets of the same service:

HCL

Service Splitter - 图1

  • HCL
  • Kubernetes YAML
  • JSON
  1. Kind = "service-splitter"
  2. Name = "web"
  3. Splits = [
  4.   {
  5.     Weight        = 90
  6.     ServiceSubset = "v1"
  7.   },
  8.   {
  9.     Weight        = 10
  10.     ServiceSubset = "v2"
  11.   },
  12. ]
  1. apiVersion: consul.hashicorp.com/v1alpha1
  2. kind: ServiceSplitter
  3. metadata:
  4.   name: web
  5. spec:
  6.   splits:
  7.     - weight: 90
  8.       serviceSubset: v1
  9.     - weight: 10
  10.       serviceSubset: v2
  1. {
  2.   "Kind": "service-splitter",
  3.   "Name": "web",
  4.   "Splits": [
  5.     {
  6.       "Weight": 90,
  7.       "ServiceSubset": "v1"
  8.     },
  9.     {
  10.       "Weight": 10,
  11.       "ServiceSubset": "v2"
  12.     }
  13.   ]
  14. }

Two different services

Split traffic between two services:

HCL

Service Splitter - 图2

  • HCL
  • Kubernetes YAML
  • JSON
  1. Kind = "service-splitter"
  2. Name = "web"
  3. Splits = [
  4.   {
  5.     Weight  = 50
  6.     # will default to service with same name as config entry ("web")
  7.   },
  8.   {
  9.     Weight  = 10
  10.     Service = "web-rewrite"
  11.   },
  12. ]
  1. apiVersion: consul.hashicorp.com/v1alpha1
  2. kind: ServiceSplitter
  3. metadata:
  4.   name: web
  5. spec:
  6.   splits:
  7.     - weight: 50
  8.       # will default to service with same name as config entry ("web")
  9.     - weight: 10
  10.       service: web-rewrite
  1. {
  2.   "Kind": "service-splitter",
  3.   "Name": "web",
  4.   "Splits": [
  5.     {
  6.       "Weight": 50
  7.     },
  8.     {
  9.       "Weight": 50,
  10.       "Service": "web-rewrite"
  11.     }
  12.   ]
  13. }

Available Fields

Service Splitter - 图3

Service Splitter - 图4

  • 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 the config entry will apply to.

  • 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 eight 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 assumed.

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: