@ -55,7 +68,11 @@ The following list outlines field hierarchy, language-specific data types, and r
This section provides details about the fields you can configure in a `service-splitter` configuration entry.
### Kind (kind)
### `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`, `kind`
Specifies the type of configuration entry to implement.
@ -63,310 +80,243 @@ Specifies the type of configuration entry to implement.
- HCL: `Kind`
- YAML: `kind`
| Format | Path |
| --- | --- |
| HCL | `Kind' |
| YAML | `kind |
#### Values
Takes a string value that must be set to `service-splitter` in HCL or `serviceSplitter` in YAML. This field is required and does not have a default value.
### Name
- Default: none
- Required: Required
- Data type: String value that must be set to `service-splitter` in HCL or `serviceSplitter` in YAML.
| | |
|--- | --- |
| **Description** | Specifies a name for the configuration entry. The name is metadata that you can use to reference the configuration entry when performing operations, such as reading or writing configuration entry configuration entry settings. |
| <nobr>**HCL path**</nobr> | `Name` |
| **YAML path** | `metadata.name` |
| **Default** | Defaults to the node name |
| **Required** | Required |
| **Values** | Takes a string value. |
| | |
### `Name`, `name`
### Namespace <EnterpriseAlert inline />
Specifies a name for the configuration entry. The name is metadata that you can use to reference the configuration entry when performing operations, such as reading or writing configuration entry configuration entry settings.
Specifies the [namespace](/consul/docs/enterprise/namespaces) to apply the configuration entry.
- HCL path: `Namespace`
- YAML path: `metadata.namespace`
- Default: None
- Values: Takes a string value
#### Paths
- HCL: `Name`
- YAML: `metadata.name
### Partition <EnterpriseAlert inline />
Specifies the [admin partition](consul/docs/enterprise/admin-partitions) to apply the configuration entry.
Specifies key/value pairs to add to the K/V store.
Specifies the [namespace](/consul/docs/enterprise/namespaces) to apply the configuration entry.
|||
|--- | --- |
| **HCL path** | `Meta` |
| <nobr>**YAML path**</nobr> | `spec.meta` |
| **Default** | none |
| **Required** | Optional |
| **Values** | This field contains an object of or more key-value pairs. They key takes a string data type and values can take strings, integers, or floats. |
| | |
#### Paths
- HCL: `Namespace`
- YAML: `metadata.namespace`
<a name="splits"/>
#### Values
### Splits | splits
- Default: None
- Required: Optional
- Data type: String
Defines how much traffic to send to sets of service instances during a traffic split.
#### Paths
Declare the parameter according to your configuration format:
Specifies what percentage of the traffic is sent to the set of service instances specified in the [`splits.Service`](#splits-service) field.
### `Meta`, `meta`
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`.
Specifies key-value pairs to add to the KV store.
- JSON data type: `float32`
- Default: `null`
- Required: optional
#### Paths
### Splits.service
- HCL: `Meta`
- YAML: `spec.meta`
Specifies the name of the service to resolve. If undefined, this value defaults to the service with the same name as the configuration entry.
#### Values
- JSON data type: `array`
- Default: ""
- Required: optional
- Default: none
- Required: Optional
- Data type: Map of one or more key-value pairs
- keys: String
- values: String, integer, or float
### Splits.serviceSubset
### `spec`
Specifies a subset of the service to resolve. This field overrides the `DefaultSubset`. If empty, the `split` uses the default subset.
Kubernetes-only field that contains all of the configurations for service splitter pods.
- JSON data type: `string`
- Default: ""
- Required: optional
#### Values
### Splits.namespace <EnterpriseAlert inline />
- Default: none
- Required: Required
- Data type: Object containing [`splits`](#splits-splits) configuration
Specifies which [namespace](/consul/docs/enterprise/namespaces) to use for resolving the service. By default, the `service-splitter` uses the [namespace specified in the top-level configuration entry](#namespace).
### `Splits`, `splits`
- JSON data type: `string`
- Default: `null`
- Required: optional
Defines how much traffic to send to sets of service instances during a traffic split.
### Splits.partition <EnterpriseAlert inline />
#### Paths
Specifies which [admin partition](/consul/docs/enterprise/admin-partitions) to use for resolving the service. By default, the `service-splitter` uses the [admin partition specified in the top-level configuration entry](#partition).
- HCL: `Splits`
- YAML: `spec.splits`
- JSON data type: `string`
- Default: `null`
- Required: optional
#### Values
<a name="requestheaders"/>
- Default: None
- Required: Required for defining service splits
- Data type: Array of objects that can contain the following fields:
- [`Weight`](#weight-weight), `weight` in YAML: The sum of weights for a set of service instances must add up to 100.
- [`Service`](#service-service) , `service` in YAML: This field is required to direct split traffic
- [`ServiceSubset`](#servicesubset-servicesubset), `serviceSubset` in YAML
- [`Namespace`](#namespace-namespace), `namespace` in YAML <Enterprise inline/>
- [`Partition`](#partition-partition), `partition` in YAML <Enterprise inline/>
- [`RequestHeaders`](#requestheaders-requestheaders), `requestHeaders` in YAML
- [`ResponseHeaders`](#responseheaders-responseheaders), `responseHeaders` in YAML
### RequestHeaders | requestHeaders
### `Weight`, `weight`
Specifies a set of HTTP-specific header modification rules that apply to requests routed to the split. You cannot configure request headers if the listener protocol is set to `tcp`.
Specifies the percentage of traffic sent to the set of service instances specified in the [`Service`, `service`](#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`.
#### Paths
- HCL: `RequestHeaders`
- YAML: `spec.splits.requestHeaders`
- HCL: `Splits.Weight`
- YAML: `spec.splits.weight`
#### Values
This parameter contains an object that defines one or more rules for modifying request headers. Each rule contains one or more key-value pairs. The following table describes how to configure values for request headers. There are no default values:
| Rule | Description | Type | Required |
| --- | --- | --- | --- |
| `Add` <br/><nobr>`add` (Kubernetes)</nobr> | 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 | optional |
| `Set` <br/><nobr>`set` (Kubernetes)</nobr> | 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 | optional |
| `Remove` <br/><nobr>`remove` (Kubernetes)</nobr> | Defines an array of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | array of strings | optional |
#### Use variable placeholders
For `Add` and `Set`, if the service is configured to use Envoy as the proxy, the value may contain variable placeholders, for example, `%DOWNSTREAM_REMOTE_ADDRESS%` to interpolate dynamic metadata into the value added.
<!--
- JSON data type: `string`
- Default: `null`
- Required: optional
-->
<a name="responseheaders"/>
### ResponseHeaders | responseHeaders
Specifies a set of HTTP-specific header modification rules that apply to responses from the split. You cannot configure request headers if the listener protocol is set to `tcp`.
- Required: Required for defining service splits
- Data type: Floating integer from `.01` to `100`
- **HCL path**: `Splits.ResponseHeaders`
### `Service`, `service`
- **YAML path**: `spec.splits.responseHeaders`
- **Default**: None
- **Values**:
The following table describes how to configure values for response headers:
| Rule | Description | Type | Required |
| --- | --- | --- | --- |
| `Add` <br/><nobr>`add` (Kubernetes)</nobr> | 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 | optional |
| `Set` <br/><nobr>`set` (Kubernetes)</nobr> | 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 | optional |
| `Remove` <br/><nobr>`remove` (Kubernetes)</nobr> | Defines an array of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | array of strings | optional |
Specifies the name of the service to resolve.
#### Use variable placeholders
#### Paths
For `Add` and `Set`, if the service is configured to use Envoy as the proxy, the value may contain variable placeholders, for example, `%DOWNSTREAM_REMOTE_ADDRESS%` to interpolate dynamic metadata into the value added.
- HCL: `Splits.Service`
- YAML: `spec.splits.service`
#### Values
<!-- JSON data type: `string`
- Default: `null`
- Default: The service matching the configuration entry [`Name`](#name-name) field.
- Required: optional
- Data type: String
</Tab>
<Tab heading="YAML" group="yaml">
### apiVersion
### `ServiceSubset`, `serviceSubset`
Specifies the version of the Consul API for integrating with Kubernetes. The value must be `consul.hashicorp.com/v1alpha1`. The `apiVersion` field is not supported for non-Kubernetes deployments.
Specifies a subset of the service to resolve. This field overrides the `DefaultSubset`.
- JSON data type: `string`
- Default: ""
- Required: required
### kind
Specifies the type of configuration entry to implement. Must be set to `serviceSplitter`.
- JSON data type: `string`
- Default: ""
- Required: required
#### Paths
### metadata
- HCL: `Splits.ServiceSubset`
- YAML: `spec.splits.serviceSubset`
Kubernetes-only object that contains the service name, namespace, and admin partition that the configuration entry applies to.
#### Values
- JSON data type: `object`
- Default: ""
- Required: required
- Default: If empty, the `split` uses the default subset.
Specifies a name for the configuration entry. The name is metadata that you can use to reference the configuration entry when performing operations, such as reading or writing configuration entry configuration entry settings.
Specifies which [namespace](/consul/docs/enterprise/namespaces) to use in the FQDN when resolving the service.
- JSON data type: `string`
- Default: ""
- Required: required
#### Paths
### metadata.namespace <EnterpriseAlert inline />
- HCL: `Splits.Namespace`
- YAML: `spec.splits.namespace`
Specifies the [namespace](/consul/docs/enterprise/namespaces) to apply the configuration entry.
#### Values
- JSON data type: `string`
- Default: `null`
- Default: The namespace specified in the top-level configuration entry.
Kubernetes-only object that contains the details about the `service-defaults` configuration entry. The `apiVersion`, `kind`, and `metadata` fields are siblings of the `spec` field. All other configurations are children.
Specifies which [admin partition](/consul/docs/enterprise/admin-partitions) to use in the FQDN when resolving the service.
- JSON data type: `object`
- Default: `null`
- Required: required
#### Paths
### spec.splits
- HCL: `Splits.Partition`
- YAML: `spec.splits.partition`
Defines how much traffic to send to sets of service instances during a traffic split. The sum of weights for a set of service instances must add up to 100. Either [`Splits.service`]#splits-servicesubset) or `[Splits.serviceSubset`](#splits-servicesubset) must be defined to direct split traffic.
#### Values
- JSON data type: `array`
- Default: `null`
- Default: By default, the `service-splitter` uses the [admin partition specified in the top-level configuration entry](#partition-partition).
- Required: optional
- Data type: String
### spec.splits.weight
Specifies what percentage of the traffic is sent to the set of service instances specified in the [`splits.Service`](#splits-service) field.
### `RequestHeaders`, `requestHeaders`
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`.
Specifies a set of HTTP-specific header modification rules that apply to requests routed to the 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.
- JSON data type: `float32`
- Default: `null`
- Required: optional
#### Paths
### spec.splits.service
- HCL: `Splits.RequestHeaders`
- YAML: `spec.splits.requestHeaders`
Specifies the name of the service to resolve. If undefined, this value defaults to the service with the same name as the configuration entry.
#### Values
- JSON data type: `array`
- Default: ""
- Default: None
- Required: optional
- Values: Object containing one or more fields that define header modification rules
- `Add`, `add` in YAML: Map of one or more key-value pairs
- `Set`, `set` in YAML: Map of one or more key-value pairs
- `Remove`, `remove` in YAML: Map of one or more key-value pairs
### spec.splits.serviceSubset
Specifies a subset of the service to resolve. This field overrides the `DefaultSubset`. If empty, the `split` uses the default subset.
The following table describes how to configure values for request headers:
- JSON data type: `string`
- Default: ""
- Required: optional
| Rule | Description | Type | Required |
| --- | --- | --- | --- |
| `Add` <br/><nobr>`add` (Kubernetes)</nobr> | 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 | optional |
| `Set` <br/><nobr>`set` (Kubernetes)</nobr> | 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 | optional |
| `Remove` <br/><nobr>`remove` (Kubernetes)</nobr> | Defines an array of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | array of strings | optional |
Specifies which [namespace](/consul/docs/enterprise/namespaces) to use for resolving the service. By default, the `service-splitter` uses the [namespace specified in the top-level configuration entry](#namespace).
For `Add` and `Set`, if the service is configured to use Envoy as the proxy, the value may contain variable placeholders, for example, `%DOWNSTREAM_REMOTE_ADDRESS%` to interpolate dynamic metadata into the value added.
Specifies which [admin partition](/consul/docs/enterprise/admin-partitions) to use for resolving the service. By default, the `service-splitter` uses the [admin partition specified in the top-level configuration entry](#partition).
Specifies a set of HTTP-specific header modification rules that apply to responses from the 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.
- JSON data type: `string`
- Default: `null`
- Required: optional
#### Paths
### spec.splits.requestHeaders
- HCL: `Splits.ResponseHeaders`
- YAML: `spec.splits.responseHeaders`
A set of HTTP-specific header modification rules that apply to requests routed to this split. This field cannot be used with a tcp listener.
#### Values
- JSON data type: `string`
- Default: `null`
- Default: None
- Required: optional
- Values: Object containing one or more fields that define header modification rules
- `Add`, `add` in YAML: Map of one or more string key-value pairs
- `Set`, `set` in YAML: Map of one or more string key-value pairs
- `Remove`, `remove` in YAML: Map of one or more string key-value pairs
### spec.splits.responseHeaders
A set of HTTP-specific header modification rules that apply to responses from this split. This field cannot be used with a tcp listener.
The following table describes how to configure values for response headers:
| Rule | Description | Type | Required |
| --- | --- | --- | --- |
| `Add` <br/><nobr>`add` (Kubernetes)</nobr> | 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 | optional |
| `Set` <br/><nobr>`set` (Kubernetes)</nobr> | 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 | optional |
| `Remove` <br/><nobr>`remove` (Kubernetes)</nobr> | Defines an array of headers to remove. Consul removes only headers containing exact matches. Header names are not case-sensitive. | array of strings | optional |
- JSON data type: `string`
- Default: `null`
- Required: optional
#### Use variable placeholders
</Tab>
</Tabs>
-->
For `Add` and `Set`, if the service is configured to use Envoy as the proxy, the value may contain variable placeholders, for example, `%DOWNSTREAM_REMOTE_ADDRESS%` to interpolate dynamic metadata into the value added.
trujillo-adam
2 years ago