Docs/reformat service splitters conf entry (#16264)
* for tab testing * updates * Update * adding sandbox to test conf ref types * testing tweaks to the conf ref template * reintroduce tabbed specification * applied feedback from MKO session * applied feedback on format from luke and jared * Apply suggestions from code review Co-authored-by: Dan Upton <daniel@floppy.co> * fixed some minor HCL formatting in complete conf * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * fixed bad link * resolving conflicts --------- Co-authored-by: boruszak <jeffrey.boruszak@hashicorp.com> Co-authored-by: Dan Upton <daniel@floppy.co> Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
This commit is contained in:
trujillo-adam
GitHub
parent
8ea5b575d9
commit
9b7fc8cdf7
|
|
@ -1,54 +1,575 @@
|
||||||
---
|
---
|
||||||
layout: docs
|
layout: docs
|
||||||
page_title: Service Splitter - Configuration Entry Reference
|
page_title: Service Splitter Configuration Entry Reference
|
||||||
description: >-
|
description: >-
|
||||||
The service splitter configuration entry kind defines how to divide service mesh traffic between service instances. Use the reference guide to learn about `""service-splitter""` config entry parameters and how it can be used for traffic management behaviors like canary rollouts, blue green deployment, and load balancing across environments.
|
Service splitter configuration entries are L7 traffic management tools for redirecting requests for a service to
|
||||||
|
multiple instances. Learn how to write `service-splitter` config entries in HCL or YAML with a specification
|
||||||
|
reference, configuration model, a complete example, and example code by use case.
|
||||||
---
|
---
|
||||||
|
|
||||||
# Service Splitter Configuration Entry
|
# Service Splitter Configuration Reference
|
||||||
|
|
||||||
-> **v1.8.4+:** On Kubernetes, the `ServiceSplitter` custom resource is supported in Consul versions 1.8.4+.<br />
|
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.
|
||||||
**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
|
## Configuration model
|
||||||
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
|
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.
|
||||||
flows to a service with the same name and discovery continues on to the
|
|
||||||
resolution stage.
|
|
||||||
|
|
||||||
## Interaction with other Config Entries
|
<Tabs>
|
||||||
|
|
||||||
- Service splitter config entries are a component of [L7 Traffic
|
<Tab heading="HCL and JSON" group="hcl">
|
||||||
Management](/consul/docs/connect/l7-traffic).
|
|
||||||
|
|
||||||
- Service splitter config entries are restricted to only services that define
|
- [`Kind`](#kind): string | required
|
||||||
their protocol as http-based via a corresponding
|
- [`Name`](#name): string | required
|
||||||
[`service-defaults`](/consul/docs/connect/config-entries/service-defaults) config
|
- [`Namespace`](#namespace): string <EnterpriseAlert inline />
|
||||||
entry or globally via
|
- [`Partition`](#partition): string <EnterpriseAlert inline />
|
||||||
[`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults) .
|
- [`Meta`](#meta): map
|
||||||
|
- [`Splits`](#splits): map | required
|
||||||
|
- [`Weight`](#splits-weight): number | required
|
||||||
|
- [`Service`](#splits-service): string | required
|
||||||
|
- [`ServiceSubset`](#splits-servicesubset): string
|
||||||
|
- [`Namespace`](#splits-namespace): string <EnterpriseAlert inline />
|
||||||
|
- [`Partition`](#splits-partition): string <EnterpriseAlert inline />
|
||||||
|
- [`RequestHeaders`](#splits-requestheaders): map
|
||||||
|
- [`Add`](#splits-requestheaders): map
|
||||||
|
- [`Set`](#splits-requestheaders): map
|
||||||
|
- [`Remove`](#splits-requestheaders): map
|
||||||
|
- [`ResponseHeaders`](#splits-responseheaders): map
|
||||||
|
- [`Add`](#splits-responseheaders): map
|
||||||
|
- [`Set`](#splits-responseheaders): map
|
||||||
|
- [`Remove`](#splits-responseheaders): map
|
||||||
|
|
||||||
- Any split destination that specifies a different `Service` field and omits
|
</Tab>
|
||||||
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`](/consul/docs/connect/config-entries/service-resolver).
|
|
||||||
|
|
||||||
## UI
|
<Tab heading="YAML" group="yaml">
|
||||||
|
|
||||||
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.
|
- [`apiVersion`](#apiversion): string | required
|
||||||
|
- [`kind`](#kind): string | required
|
||||||
|
- [`metadata`](#metadata): object | required
|
||||||
|
- [`name`](#metadata-name): string | required
|
||||||
|
- [`namespace`](#metadata-namespace): string | optional <EnterpriseAlert inline />
|
||||||
|
- [`spec`](#spec): object | required
|
||||||
|
- [`splits`](#spec-splits): list | required
|
||||||
|
- [`weight`](#spec-splits-weight): float32 | required
|
||||||
|
- [`service`](#spec-splits-service): string | required
|
||||||
|
- [`serviceSubset`](#spec-splits-servicesubset): string
|
||||||
|
- [`namespace`](#spec-splits-namespace): string <EnterpriseAlert inline />
|
||||||
|
- [`partition`](#spec-splits-partition): string <EnterpriseAlert inline />
|
||||||
|
- [`requestHeaders`](#spec-splits-requestheaders): HTTPHeaderModifiers
|
||||||
|
- [`add`](#spec-splits-requestheaders): map
|
||||||
|
- [`set`](#spec-splits-requestheaders): map
|
||||||
|
- [`remove`](#spec-splits-requestheaders): map
|
||||||
|
- [`responseHeaders`](#spec-splits-responseheaders): HTTPHeaderModifiers
|
||||||
|
- [`add`](#spec-splits-responseheaders): map
|
||||||
|
- [`set`](#spec-splits-responseheaders): map
|
||||||
|
- [`remove`](#spec-splits-responseheaders): map
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
## Sample Config Entries
|
## Complete configuration
|
||||||
|
|
||||||
|
When every field is defined, a service splitter configuration entry has the following form:
|
||||||
|
|
||||||
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="HCL" group="hcl">
|
||||||
|
|
||||||
|
```hcl
|
||||||
|
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"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="JSON" group="json">
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="YAML" group="yaml">
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
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
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
## Specification
|
||||||
|
|
||||||
|
This section provides details about the fields you can configure in the service splitter configuration entry.
|
||||||
|
|
||||||
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="HCL" group="hcl">
|
||||||
|
|
||||||
|
### `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` <EnterpriseAlert inline />
|
||||||
|
|
||||||
|
Specifies the [namespace](/consul/docs/enterprise/namespaces) to apply the configuration entry.
|
||||||
|
|
||||||
|
#### Values
|
||||||
|
|
||||||
|
- Default: None
|
||||||
|
- Data type: String
|
||||||
|
|
||||||
|
### `Partition` <EnterpriseAlert inline />
|
||||||
|
|
||||||
|
Specifies the [admin partition](/consul/docs/enterprise/admin-partitions) 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` <Enterprise inline/>
|
||||||
|
- `Partition` <Enterprise inline/>
|
||||||
|
- `RequestHeaders`
|
||||||
|
- `ResponseHeaders`
|
||||||
|
|
||||||
|
### `Splits[].Weight`
|
||||||
|
|
||||||
|
Specifies the percentage of traffic sent to the set of service instances specified in the [`Service`](#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`](#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](/consul/docs/connect/config-entries/service-resolver), 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` <EnterpriseAlert inline />
|
||||||
|
|
||||||
|
Specifies the [namespace](/consul/docs/enterprise/namespaces) to use in the FQDN when resolving the service.
|
||||||
|
|
||||||
|
#### Values
|
||||||
|
|
||||||
|
- Default: Inherits the value of [`Namespace`](#Namespace) from the top-level of the configuration entry.
|
||||||
|
- Data type: String
|
||||||
|
|
||||||
|
### `Splits[].Partition` <EnterpriseAlert inline />
|
||||||
|
|
||||||
|
Specifies the [admin partition](/consul/docs/enterprise/admin-partitions) 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](#partition).
|
||||||
|
- 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](#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](#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](#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](#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](#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](#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.
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="YAML" group="yaml">
|
||||||
|
|
||||||
|
### `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`
|
||||||
|
|
||||||
|
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: Inherits name from the host node
|
||||||
|
- This field is required.
|
||||||
|
- Data type: String
|
||||||
|
|
||||||
|
|
||||||
|
### `metadata.namespace` <EnterpriseAlert inline />
|
||||||
|
|
||||||
|
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](/consul/docs/k8s/crds#consul-enterprise) 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`](#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` <Enterprise inline/>
|
||||||
|
- `partition` <Enterprise inline/>
|
||||||
|
- `requestHeaders`
|
||||||
|
- `responseHeaders`
|
||||||
|
|
||||||
|
### `spec.splits[].weight`
|
||||||
|
|
||||||
|
Specifies the percentage of traffic sent to the set of service instances specified in the [`spec.splits.service`](#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`](#metadata-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` <EnterpriseAlert inline />
|
||||||
|
|
||||||
|
Specifies the [namespace](/consul/docs/enterprise/namespaces) to use when resolving the service.
|
||||||
|
|
||||||
|
#### Values
|
||||||
|
|
||||||
|
- Default: The namespace specified in the top-level configuration entry.
|
||||||
|
- Data type: String
|
||||||
|
|
||||||
|
### `spec.splits[].partition` <EnterpriseAlert inline />
|
||||||
|
|
||||||
|
Specifies which [admin partition](/consul/docs/enterprise/admin-partitions) to use in the FQDN when resolving the service.
|
||||||
|
|
||||||
|
#### Values
|
||||||
|
|
||||||
|
- Default: `default`
|
||||||
|
- Data type: String
|
||||||
|
|
||||||
|
### `spec.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](#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](#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](#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`
|
||||||
|
|
||||||
|
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](#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](#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](#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.
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
The following examples demonstrate common service splitter configuration patterns for specific use cases.
|
||||||
|
|
||||||
### Two subsets of same service
|
### Two subsets of same service
|
||||||
|
|
||||||
Split traffic between two subsets of the same service:
|
Split traffic between two subsets of the same service:
|
||||||
|
|
||||||
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="HCL" group="hcl">
|
||||||
|
|
||||||
```hcl
|
```hcl
|
||||||
Kind = "service-splitter"
|
Kind = "service-splitter"
|
||||||
|
|
@ -65,18 +586,9 @@ Splits = [
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
```yaml
|
</Tab>
|
||||||
apiVersion: consul.hashicorp.com/v1alpha1
|
|
||||||
kind: ServiceSplitter
|
<Tab heading="JSON" group="json">
|
||||||
metadata:
|
|
||||||
name: web
|
|
||||||
spec:
|
|
||||||
splits:
|
|
||||||
- weight: 90
|
|
||||||
serviceSubset: v1
|
|
||||||
- weight: 10
|
|
||||||
serviceSubset: v2
|
|
||||||
```
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
|
|
@ -95,13 +607,34 @@ spec:
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
</CodeTabs>
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="YAML" group="yaml">
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: consul.hashicorp.com/v1alpha1
|
||||||
|
kind: ServiceSplitter
|
||||||
|
metadata:
|
||||||
|
name: web
|
||||||
|
spec:
|
||||||
|
splits:
|
||||||
|
- weight: 90
|
||||||
|
serviceSubset: v1
|
||||||
|
- weight: 10
|
||||||
|
serviceSubset: v2
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
### Two different services
|
### Two different services
|
||||||
|
|
||||||
Split traffic between two services:
|
Split traffic between two services:
|
||||||
|
|
||||||
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="HCL" group="hcl">
|
||||||
|
|
||||||
```hcl
|
```hcl
|
||||||
Kind = "service-splitter"
|
Kind = "service-splitter"
|
||||||
|
|
@ -118,18 +651,9 @@ Splits = [
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
```yaml
|
</Tab>
|
||||||
apiVersion: consul.hashicorp.com/v1alpha1
|
|
||||||
kind: ServiceSplitter
|
<Tab heading="JSON" group="json">
|
||||||
metadata:
|
|
||||||
name: web
|
|
||||||
spec:
|
|
||||||
splits:
|
|
||||||
- weight: 50
|
|
||||||
# will default to service with same name as config entry ("web")
|
|
||||||
- weight: 50
|
|
||||||
service: web-rewrite
|
|
||||||
```
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
|
|
@ -147,14 +671,35 @@ spec:
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
</CodeTabs>
|
</Tab>
|
||||||
|
|
||||||
|
<Tab heading="YAML" group="yaml">
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
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
|
||||||
|
```
|
||||||
|
|
||||||
|
</Tab>
|
||||||
|
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
### Set HTTP Headers
|
### Set HTTP Headers
|
||||||
|
|
||||||
Split traffic between two subsets with extra headers added so clients can tell
|
Split traffic between two subsets with extra headers added so clients can tell
|
||||||
which version:
|
which version:
|
||||||
|
|
||||||
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
<Tabs>
|
||||||
|
|
||||||
|
<Tab heading="HCL" group="hcl">
|
||||||
|
|
||||||
```hcl
|
```hcl
|
||||||
Kind = "service-splitter"
|
Kind = "service-splitter"
|
||||||
|
|
@ -181,24 +726,9 @@ Splits = [
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
```yaml
|
</Tab>
|
||||||
apiVersion: consul.hashicorp.com/v1alpha1
|
|
||||||
kind: ServiceSplitter
|
<Tab heading="JSON" group="json">
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
|
|
@ -227,136 +757,31 @@ spec:
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
</CodeTabs>
|
</Tab>
|
||||||
|
|
||||||
## Available Fields
|
|
||||||
|
|
||||||
<ConfigEntryReference
|
|
||||||
keys={[
|
|
||||||
{
|
|
||||||
name: 'apiVersion',
|
|
||||||
description: 'Must be set to `consul.hashicorp.com/v1alpha1`',
|
|
||||||
hcl: false,
|
|
||||||
},
|
|
||||||
{
|
|
||||||
name: 'Kind',
|
|
||||||
description: {
|
|
||||||
hcl: 'Must be set to `service-splitter`',
|
|
||||||
yaml: 'Must be set to `ServiceSplitter`',
|
|
||||||
},
|
|
||||||
},
|
|
||||||
{
|
|
||||||
name: 'Name',
|
|
||||||
description: 'Set to the name of the service being configured.',
|
|
||||||
type: 'string: <required>',
|
|
||||||
yaml: false,
|
|
||||||
},
|
|
||||||
{
|
|
||||||
name: 'Namespace',
|
|
||||||
type: `string: "default"`,
|
|
||||||
enterprise: true,
|
|
||||||
description:
|
|
||||||
'Specifies the namespace to which the configuration entry will apply.',
|
|
||||||
yaml: false,
|
|
||||||
},
|
|
||||||
{
|
|
||||||
name: 'Partition',
|
|
||||||
type: `string: "default"`,
|
|
||||||
enterprise: true,
|
|
||||||
description:
|
|
||||||
'Specifies the admin partition to which the configuration entry will apply.',
|
|
||||||
yaml: false,
|
|
||||||
},
|
|
||||||
{
|
|
||||||
name: 'Meta',
|
|
||||||
type: 'map<string|string>: nil',
|
|
||||||
description:
|
|
||||||
'Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.',
|
|
||||||
yaml: false,
|
|
||||||
},
|
|
||||||
{
|
|
||||||
name: 'metadata',
|
|
||||||
children: [
|
|
||||||
{
|
|
||||||
name: 'name',
|
|
||||||
description: 'Set to the name of the service being configured.',
|
|
||||||
},
|
|
||||||
{
|
|
||||||
name: 'namespace',
|
|
||||||
description:
|
|
||||||
'If running Consul Open Source, the namespace is ignored (see [Kubernetes Namespaces in Consul OSS](/consul/docs/k8s/crds#consul-oss)). If running Consul Enterprise see [Kubernetes Namespaces in Consul Enterprise](/consul/docs/k8s/crds#consul-enterprise) for more details.',
|
|
||||||
},
|
|
||||||
],
|
|
||||||
hcl: false,
|
|
||||||
},
|
|
||||||
{
|
|
||||||
name: 'Splits',
|
|
||||||
type: 'array<ServiceSplit>',
|
|
||||||
description:
|
|
||||||
'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.',
|
|
||||||
children: [
|
|
||||||
{
|
|
||||||
name: 'weight',
|
|
||||||
type: 'float32: 0',
|
|
||||||
description:
|
|
||||||
'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%',
|
|
||||||
},
|
|
||||||
{
|
|
||||||
name: 'Service',
|
|
||||||
type: 'string: ""',
|
|
||||||
description: 'The service to resolve instead of the default.',
|
|
||||||
},
|
|
||||||
{
|
|
||||||
name: 'ServiceSubset',
|
|
||||||
type: 'string: ""',
|
|
||||||
description: {
|
|
||||||
hcl:
|
|
||||||
"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.",
|
|
||||||
yaml:
|
|
||||||
"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.",
|
|
||||||
},
|
|
||||||
},
|
|
||||||
{
|
|
||||||
name: 'Namespace',
|
|
||||||
enterprise: true,
|
|
||||||
type: 'string: ""',
|
|
||||||
description:
|
|
||||||
'The namespace to resolve the service from instead of the current namespace. If empty, the current namespace is used.',
|
|
||||||
},
|
|
||||||
{
|
|
||||||
name: 'Partition',
|
|
||||||
enterprise: true,
|
|
||||||
type: 'string: ""',
|
|
||||||
description:
|
|
||||||
'The admin partition to resolve the service from instead of the current partition. If empty, the current partition is used.',
|
|
||||||
},
|
|
||||||
{
|
|
||||||
name: 'RequestHeaders',
|
|
||||||
type: 'HTTPHeaderModifiers: <optional>',
|
|
||||||
description: `A set of [HTTP-specific header modification rules](/consul/docs/connect/config-entries/service-router#httpheadermodifiers)
|
|
||||||
that will be applied to requests routed to this split.
|
|
||||||
This cannot be used with a \`tcp\` listener.`,
|
|
||||||
},
|
|
||||||
{
|
|
||||||
name: 'ResponseHeaders',
|
|
||||||
type: 'HTTPHeaderModifiers: <optional>',
|
|
||||||
description: `A set of [HTTP-specific header modification rules](/consul/docs/connect/config-entries/service-router#httpheadermodifiers)
|
|
||||||
that will be applied to responses from this split.
|
|
||||||
This cannot be used with a \`tcp\` listener.`,
|
|
||||||
},
|
|
||||||
],
|
|
||||||
},
|
|
||||||
]}
|
|
||||||
/>
|
|
||||||
|
|
||||||
## ACLs
|
<Tab heading="YAML" group="yaml">
|
||||||
|
|
||||||
Configuration entries may be protected by [ACLs](/consul/docs/security/acl).
|
```yaml
|
||||||
|
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
|
||||||
|
```
|
||||||
|
|
||||||
Reading a `service-splitter` config entry requires `service:read` on the resource.
|
</Tab>
|
||||||
|
|
||||||
Creating, updating, or deleting a `service-splitter` config entry requires
|
</Tabs>
|
||||||
`service:write` on the resource and `service:read` on any other service referenced by
|
|
||||||
name in these fields:
|
|
||||||
|
|
||||||
- [`Splits[].Service`](#service)
|
|
||||||
Loading…
Reference in New Issue