• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Consul
  • Install
  • Tutorials
  • Documentation
  • API
  • CLI
  • Try Cloud(opens in new tab)
  • Sign up
Consul Home

Documentation

Skip to main content
  • Documentation
  • What is Consul?


    • Overview
    • How Service Mesh Works
    • Configuration
      • Overview
      • Ingress Gateway
      • Mesh
      • Exported Services
      • Proxy Defaults
      • Service Defaults
      • Service Intentions
      • Service Resolver
      • Service Router
      • Service Splitter
      • Terminating Gateway
    • Service-to-service permissions - Intentions
    • Service-to-service permissions - Intentions (Legacy Mode)
    • Transparent Proxy
    • Connectivity Tasks
    • Distributed Tracing
    • Nomad
    • Kubernetes
    • Develop and Debug


  • HCP Consul


  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Consul
  3. Documentation
  4. Service Mesh
  5. Configuration Entries
  6. Service Splitter
  • Consul
  • v1.13.x
  • v1.12.x
  • v1.11.x
  • v1.10.x
  • v1.9.x
  • v1.8.x

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

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

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
Edit this page on GitHub

On this page

  1. Service Splitter Configuration Entry
  2. Interaction with other Config Entries
  3. UI
  4. Sample Config Entries
  5. Available Fields
  6. ACLs
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)