github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Document Kube CRDs alongside config entry docs 

* Adds a new react component `ConfigEntryReference` that allows us to
document config entries for both HCL and Kubernetes CRDs.
* Rewrites config entry docs to use new component
* Add CRD examples alongside HCL examples
* Removes examples from Kube CRD doc because the examples are now in the
main CRD docs
pull/9502/head
Luke Kysow 2020-12-16 08:57:43 -08:00
parent d32e7f0857
commit 517cfa7918
No known key found for this signature in database
GPG Key ID: FA168D4DC3F04307
12 changed files with 2662 additions and 989 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

265
website/components/config-entry-reference/index.jsx Normal file
View File

@ -0,0 +1,265 @@
import TabsBase from '@hashicorp/react-tabs'
import s from '@hashicorp/nextjs-scripts/lib/providers/docs/style.module.css'
import EnterpriseAlertBase from '@hashicorp/react-enterprise-alert'
/**
* ConfigEntryReference renders the reference docs for a config entry.
* It creates two tabs, one for HCL docs and one for Kubernetes docs.
*
* @param {array<object>} keys Array of objects, that describe all
* keys that can be set for this config entry.
* @param {boolean} topLevel Indicates this is a reference block that contains
* the top level keys vs a reference block that documents
* nested keys and that is separated out for clarity.
*
* The objects in the keys array support the following keys:
* - name <required>: the name of the HCL key, e.g. Name, Listener. This case sensitive.
* - description <required>: the description of the key. If this key has different descriptions
* for HCL vs. Kube YAML then description can be an object:
* description: {
* hcl: 'HCL description',
* yaml: 'YAML description'
* }
* - hcl <optional>: a boolean to indicate if this key should be shown in the HCL
* documentation. Defaults to true.
* - yaml <optional>: a boolean to indicate if this key should be shown in the YAML
* documentation. Defaults to true.
* - enterprise <optional>: a boolean to indicate if this key is Consul Enterprise
* only. Defaults to false.
* - children <optional>: accepts an array of keys that must be set under this key.
* The schema for these keys is the same as the top level keys.
* - type <optional>: the type and default of this key, e.g. string: "default".
*/
export default function ConfigEntryReference({ keys, topLevel = true }) {
let kubeKeys = keys
if (topLevel) {
// Kube needs to have its non-top-level keys nested under a "spec" key.
kubeKeys = toKubeKeys(keys)
}
return (
<Tabs>
<Tab heading="HCL">{renderKeys(keys, true)}</Tab>
<Tab heading="Kubernetes YAML">{renderKeys(kubeKeys, false)}</Tab>
</Tabs>
)
}
/**
* Renders keys as HTML. It works recursively through all keys.
* @param {array} keys
* @param {boolean} isHCLTab
* @returns {JSX.Element|null}
*/
function renderKeys(keys, isHCLTab) {
if (!keys) {
return null
}
return (
<ul>
{keys.map((key) => {
return renderKey(key, isHCLTab)
})}
</ul>
)
}
/**
* Renders a single key as its HTML element.
*
* @param {object} key
* @param {boolea} isHCLTab
* @returns {JSX.Element|null}
*/
function renderKey(key, isHCLTab) {
let keyName = key.name
if (!keyName) {
return null
}
if (!isHCLTab) {
keyName = toYAMLKeyName(keyName)
}
if (isHCLTab && key.hcl === false) {
return null
}
if (!isHCLTab && key.yaml === false) {
return null
}
let description = ''
if (key.description) {
if (typeof key.description === 'string') {
description = key.description
} else if (!isHCLTab && key.description.yaml) {
description = key.description.yaml
} else if (key.description.hcl) {
description = key.description.hcl
}
}
let htmlDescription = ''
if (description !== '') {
htmlDescription = markdownToHtml(' - ' + description)
}
let type = ''
if (key.type) {
type = <code>{'(' + key.type + ')'}</code>
}
let enterpriseAlert = ''
if (key.enterprise) {
enterpriseAlert = <EnterpriseAlert inline />
}
const keyLower = keyName.toLowerCase()
return (
<li key={keyLower} className="g-type-long-body">
<a id={keyLower} className="__target-lic" aria-hidden="" />
<p>
<a
href={'#' + keyLower}
aria-label={keyLower + ' permalink'}
className="__permalink-lic"
>
<code>{keyName}</code>
</a>{' '}
{type}
{enterpriseAlert}
<span dangerouslySetInnerHTML={{ __html: htmlDescription }} />
</p>
{renderKeys(key.children, isHCLTab)}
</li>
)
}
/**
* Constructs a keys object for Kubernetes out of HCL keys.
* Really all this entails is nesting the correct keys under the Kubernetes
* 'spec' key since in HCL there is no 'spec' key.
*
* @param {array} keys
* @returns {array}
*/
function toKubeKeys(keys) {
const topLevelKeys = keys.filter((key) => {
return isTopLevelKubeKey(key.name)
})
const keysUnderSpec = keys.filter((key) => {
return !isTopLevelKubeKey(key.name)
})
return topLevelKeys.concat([{ name: 'spec', children: keysUnderSpec }])
}
/**
* Converts an HCL key name to a kube yaml key name.
*
* Examples:
* - Protocol => protocol
* - MeshGateway => meshGateway
* - ACLToken => aclToken
* - HTTP => http
*
* @param {string} hclKey
* @returns {string}
*/
function toYAMLKeyName(hclKey) {
// Handle something like HTTP.
if (hclKey.toUpperCase() === hclKey) {
return hclKey.toLowerCase()
}
let indexFirstLowercaseChar = 0
for (let i = 0; i < hclKey.length; i++) {
if (hclKey[i].toLowerCase() === hclKey[i]) {
indexFirstLowercaseChar = i
break
}
}
// Special case to handle something like ACLToken => aclToken.
if (indexFirstLowercaseChar > 1) {
indexFirstLowercaseChar--
}
let yamlKey = ''
for (let i = 0; i < indexFirstLowercaseChar; i++) {
yamlKey += hclKey[i].toLowerCase()
}
yamlKey += hclKey.split('').slice(indexFirstLowercaseChar).join('')
return yamlKey
}
/**
* Converts a markdown string to its HTML representation.
* Currently it only supports inline code blocks (e.g. `code here`) and
* links (e.g. [link text](http://link-url) because these were the most
* commonly used markdown features in the key descriptions.
*
* @param {string} markdown the input markdown
* @returns {string}
*/
function markdownToHtml(markdown) {
let html = markdown
// Replace inline code blocks defined by backticks with <code></code>.
while (html.indexOf('`') > 0) {
html = html.replace('`', '<code>')
if (html.indexOf('`') <= 0) {
throw new Error(`'${markdown} does not have matching '\`' characters`)
}
html = html.replace('`', '</code>')
}
// Replace links, e.g. [link text](http://link-url),
// with <a href="http://link-url">link text</a>.
return html.replace(/\[(.*?)]\((.*?)\)/g, '<a href="$2">$1</a>')
}
/**
* Returns true if key is a key used at the top level of a CRD. By top level we
* mean not nested under any other key.
*
* @param {string} name name of the key
*
* @return {boolean}
*/
function isTopLevelKubeKey(name) {
return (
name.toLowerCase() === 'metadata' ||
name.toLowerCase() === 'kind' ||
name.toLowerCase() === 'apiversion'
)
}
// Copied from https://github.com/hashicorp/nextjs-scripts/blob/04917da2191910d490182250d2828372aa1221c0/lib/providers/docs/index.jsx
// because there's no way to import it right now.
function Tabs({ children }) {
if (!Array.isArray(children))
throw new Error('Multiple <Tab> elements required')
return (
<span className={s.tabsRoot}>
<TabsBase
items={children.map((Block) => ({
heading: Block.props.heading,
// eslint-disable-next-line react/display-name
tabChildren: () => Block,
}))}
/>
</span>
)
}
// Copied from https://github.com/hashicorp/nextjs-scripts/blob/04917da2191910d490182250d2828372aa1221c0/lib/providers/docs/index.jsx
// because there's no way to import it right now.
function Tab({ children }) {
return <>{children}</>
}
function EnterpriseAlert(props) {
return <EnterpriseAlertBase product={'consul'} {...props} />
}

50
website/content/docs/agent/config-entries/index.mdx
View File

@ -10,11 +10,16 @@ description: >-
# Configuration Entries # Configuration Entries
Configuration entries can be created to provide cluster-wide defaults for Configuration entries can be created to provide cluster-wide defaults for
various aspects of Consul. Every configuration entry has at least two fields: various aspects of Consul.
Outside of Kubernetes, configuration entries can be specified in HCL or JSON using either
`snake_case` or `CamelCase` for key names. On Kubernetes, configuration
entries can be managed by custom resources in YAML.
Outside of Kubernetes, every configuration entry specified in HCL or JSON has at least two fields:
`Kind` and `Name`. Those two fields are used to uniquely identify a `Kind` and `Name`. Those two fields are used to uniquely identify a
configuration entry. When put into configuration files, configuration entries configuration entry. Configuration entries specified as HCL or JSON objects
can be specified as HCL or JSON objects using either `snake_case` or `CamelCase` use either `snake_case` or `CamelCase` for key names.
for key names.
Example: Example:
@ -23,35 +28,64 @@ Kind = "<supported kind>"
Name = "<name of entry>" Name = "<name of entry>"
``` ```
The supported `Kind` names for configuration entries are: On Kubernetes, `Kind` is set as the custom resource `kind` and `Name` is set
as `metadata.name`:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: <supported kind>
metadata:
name: <name of entry>
```
The supported `Kind`/`kind` names for configuration entries are:
- [`ingress-gateway`](/docs/agent/config-entries/ingress-gateway) - defines the - [`ingress-gateway`](/docs/agent/config-entries/ingress-gateway) - defines the
configuration for an ingress gateway configuration for an ingress gateway
- Kubernetes kind: [`IngressGateway`](/docs/agent/config-entries/ingress-gateway)
- [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) - controls - [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) - controls
proxy configuration proxy configuration
- Kubernetes kind: [`ProxyDefaults`](/docs/agent/config-entries/proxy-defaults)
- [`service-defaults`](/docs/agent/config-entries/service-defaults) - configures - [`service-defaults`](/docs/agent/config-entries/service-defaults) - configures
defaults for all the instances of a given service defaults for all the instances of a given service
- Kubernetes kind: [`ServiceDefaults`](/docs/agent/config-entries/service-defaults)
- [`service-intentions`](/docs/agent/config-entries/service-intentions) - defines - [`service-intentions`](/docs/agent/config-entries/service-intentions) - defines
the [intentions](/docs/connect/intentions) for a destination service the [intentions](/docs/connect/intentions) for a destination service
- Kubernetes kind: [`ServiceIntentions`](/docs/agent/config-entries/service-intentions)
- [`service-resolver`](/docs/agent/config-entries/service-resolver) - matches - [`service-resolver`](/docs/agent/config-entries/service-resolver) - matches
service instances with a specific Connect upstream discovery requests service instances with a specific Connect upstream discovery requests
- Kubernetes kind: [`ServiceResolver`](/docs/agent/config-entries/service-resolver)
- [`service-router`](/docs/agent/config-entries/service-router) - defines - [`service-router`](/docs/agent/config-entries/service-router) - defines
where to send layer 7 traffic based on the HTTP route where to send layer 7 traffic based on the HTTP route
- Kubernetes kind: [`ServiceRouter`](/docs/agent/config-entries/service-router)
- [`service-splitter`](/docs/agent/config-entries/service-splitter) - defines - [`service-splitter`](/docs/agent/config-entries/service-splitter) - defines
how to divide requests for a single HTTP route based on percentages how to divide requests for a single HTTP route based on percentages
- Kubernetes kind: [`ServiceSplitter`](/docs/agent/config-entries/service-splitter)
- [`terminating-gateway`](/docs/agent/config-entries/terminating-gateway) - defines the - [`terminating-gateway`](/docs/agent/config-entries/terminating-gateway) - defines the
services associated with terminating gateway services associated with terminating gateway
- Kubernetes kind: [`TerminatingGateway`](/docs/agent/config-entries/terminating-gateway)
## Managing Configuration Entries ## Managing Configuration Entries In Kubernetes
Configuration entries should be managed with the Consul See [Kubernetes Custom Resource Definitions](/docs/k8s/crds).
## Managing Configuration Entries Outside Of Kubernetes
Configuration entries outside of Kubernetes should be managed with the Consul
[CLI](/commands/config) or [API](/api/config). Additionally, as a [CLI](/commands/config) or [API](/api/config). Additionally, as a
convenience for initial cluster bootstrapping, configuration entries can be convenience for initial cluster bootstrapping, configuration entries can be
specified in all of the Consul servers's specified in all of the Consul servers's
@ -163,7 +197,7 @@ matches both `kind` and `name`, then the server will do nothing.
## Using Configuration Entries For Service Defaults ## Using Configuration Entries For Service Defaults
When the agent is Outside of Kubernetes, when the agent is
[configured](/docs/agent/options#enable_central_service_config) to enable [configured](/docs/agent/options#enable_central_service_config) to enable
central service configurations, it will look for service configuration defaults central service configurations, it will look for service configuration defaults
that match a registering service instance. If it finds any, the agent will merge that match a registering service instance. If it finds any, the agent will merge

402
website/content/docs/agent/config-entries/ingress-gateway.mdx
View File

@ -9,16 +9,18 @@ description: >-
# Ingress Gateway # Ingress Gateway
-> **1.8.0+:** This config entry is available in Consul versions 1.8.0 and newer. -> **v1.8.4+:** On Kubernetes, the `IngressGateway` custom resource is supported in Consul versions 1.8.4+.<br />
**v1.8.0+:** On other platforms, this config entry is supported in Consul versions 1.8.0+.
The `ingress-gateway` config entry kind allows you to configure ingress gateways The `ingress-gateway` config entry kind (`IngressGateway` on Kubernetes) allows you to configure ingress gateways
with listeners that expose a set of services outside the Consul service mesh. with listeners that expose a set of services outside the Consul service mesh.
See [Ingress Gateway](/docs/connect/ingress-gateway) for more information.
~> [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies For Kubernetes, see [Kubernetes Ingress Gateway](/docs/k8s/connect/ingress-gateways) for more information.
For other platforms, see [Ingress Gateway](/docs/connect/ingress-gateway).
~> **Note:** [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies
across all federated Consul datacenters. If ingress gateways in different Consul datacenters need to route to different across all federated Consul datacenters. If ingress gateways in different Consul datacenters need to route to different
sets of services within their datacenter then the ingress gateways **must** be registered with different names. sets of services within their datacenter then the ingress gateways **must** be registered with different names.<br />
See [Ingress Gateway](/docs/connect/ingress-gateway) for more information. See [Ingress Gateway](/docs/connect/ingress-gateway) for more information.
## Wildcard service specification ## Wildcard service specification
@ -93,6 +95,45 @@ Listeners = [
] ]
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Set up a TCP listener on an ingress gateway named "us-east-ingress" to proxy traffic to the "db" service:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: IngressGateway
metadata:
name: us-east-ingress
spec:
listeners:
- port: 3456
protocol: tcp
services:
- name: db
```
</Tab>
<Tab heading="Kubernetes YAML (Consul Enterprise)">
Set up a TCP listener on an ingress gateway named "us-east-ingress" in the default namespace
to proxy traffic to the "db" service in the ops namespace:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: IngressGateway
metadata:
name: us-east-ingress
namespace: default
spec:
listeners:
- port: 3456
protocol: tcp
services:
- name: db
namespace: ops
```
</Tab> </Tab>
<Tab heading="JSON"> <Tab heading="JSON">
@ -233,6 +274,66 @@ Listeners = [
] ]
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Set up a wildcard HTTP listener on an ingress gateway named "us-east-ingress" to proxy traffic to all services in the datacenter.
Also make two services available over a custom port with user-provided hosts, and enable TLS on every listener:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: IngressGateway
metadata:
name: us-east-ingress
spec:
tls:
enabled: true
listeners:
- port: 8080
protocol: http
services:
- name: '*'
- port: 4567
protocol: http
services:
- name: api
hosts: ['foo.example.com', 'foo.example.com:4567']
- name: web
hosts: ['website.example.com', 'website.example.com:4567']
```
</Tab>
<Tab heading="Kubernetes YAML (Consul Enterprise)">
Set up a wildcard HTTP listener on an ingress gateway named "us-east-ingress" to proxy traffic to all services in the frontend namespace.
Also make two services in the frontend namespace available over a custom port with user-provided hosts, and enable TLS on every listener:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: IngressGateway
metadata:
name: us-east-ingress
namespace: default
spec:
tls:
enabled: true
listeners:
- port: 8080
protocol: http
services:
- name: '*'
namespace: frontend
- port: 4567
protocol: http
services:
- name: api
namespace: frontend
hosts: ['foo.example.com', 'foo.example.com:4567']
- name: web
namespace: frontend
hosts: ['website.example.com', 'website.example.com:4567']
```
</Tab> </Tab>
<Tab heading="JSON"> <Tab heading="JSON">
@ -372,6 +473,46 @@ Listeners = [
] ]
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Set up a HTTP listener on an ingress gateway named "us-east-ingress" to proxy
traffic to a virtual service named "api".
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: IngressGateway
metadata:
name: us-east-ingress
spec:
listeners:
- port: 80
protocol: http
services:
- name: api
```
</Tab>
<Tab heading="Kubernetes YAML (Consul Enterprise)">
Set up a HTTP listener on an ingress gateway named "us-east-ingress" in the
default namespace to proxy traffic to a virtual service named "api".
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: IngressGateway
metadata:
name: us-east-ingress
namespace: default
spec:
listeners:
- port: 80
protocol: http
services:
- name: api
namespace: frontend
```
</Tab> </Tab>
<Tab heading="JSON"> <Tab heading="JSON">
@ -426,9 +567,9 @@ default namespace to proxy traffic to a virtual service named "api".
</Tabs> </Tabs>
The `api` service is not an actual registered service. It exist as a "virtual" The `api` service is not an actual registered service. It exist as a "virtual"
service for L7 configuration only. A `service-router` is defined for this service for L7 configuration only. A `service-router` (`ServiceRouter` on Kubernetes) is defined for this
virtual service which uses path-based routing to route requests to different virtual service which uses path-based routing to route requests to different
backend services. backend services:
<Tabs> <Tabs>
<Tab heading="HCL"> <Tab heading="HCL">
@ -497,6 +638,53 @@ Routes = [
] ]
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceRouter
metadata:
name: api
spec:
routes:
- match:
http:
pathPrefix: '/billing'
destination:
service: billing-api
- match:
http:
pathPrefix: '/payments'
destination:
service: payments-api
```
</Tab>
<Tab heading="Kubernetes YAML (Consul Enterprise)">
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceRouter
metadata:
name: api
namespace: default
spec:
routes:
- match:
http:
pathPrefix: '/billing'
destination:
service: billing-api
namespace: frontend
- match:
http:
pathPrefix: '/payments'
destination:
service: payments-api
namespace: frontend
```
</Tab> </Tab>
<Tab heading="JSON"> <Tab heading="JSON">
@ -569,71 +757,139 @@ Routes = [
## Available Fields ## Available Fields
- `Kind` - Must be set to `ingress-gateway` <ConfigEntryReference
keys={[
- `Name` `(string: <required>)` - Set to the name of the gateway being configured. {
name: 'apiVersion',
- `Namespace` `(string: "default")` - <EnterpriseAlert inline /> Specifies description: 'Must be set to `consul.hashicorp.com/v1alpha1`',
the namespace the config entry will apply to. This must be the namespace hcl: false,
the gateway is registered in. If omitted, the namespace will be inherited },
from [the request](/api/config#ns) or will default to the `default` namespace. {
name: 'Kind',
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4. description: {
hcl: 'Must be set to `ingress-gateway`',
- `TLS` `(TLSConfig: <optional>)` - TLS configuration for this gateway. yaml: 'Must be set to `IngressGateway`',
},
- `Enabled` `(bool: false)` - Set this configuration to enable TLS for },
every listener on the gateway. {
name: 'Name',
If TLS is enabled, then each host defined in the `Host` field will be added description: 'Set to the name of the gateway being configured.',
as a DNSSAN to the gateway's x509 certificate. type: 'string: <required>',
yaml: false,
- `Listeners` `(array<IngressListener>: <optional>)` - A list of listeners that },
the ingress gateway should setup, uniquely identified by their port number. {
name: 'Namespace',
- `Port` `(int: 0)` - The port that the listener should receive traffic on. type: `string: "default"`,
enterprise: true,
- `Protocol` `(string: "tcp")` - The protocol associated with the listener. description:
One of `tcp`, `http`, `http2`, or `grpc`. 'Specifies the namespace the config entry will apply to. This must be the namespace the gateway is registered in.' +
' If omitted, the namespace will be inherited from [the request](/api/config#ns)' +
- `Services` `(array<IngressService>: <optional>)` - A list of services to be ' or will default to the `default` namespace.',
exposed via this listener. For "tcp" listeners, only a single service is yaml: false,
allowed. },
{
- `Name` `(string: "")` - The name of the service that should be exposed name: 'Meta',
through this listener. This can be either a service registered in the type: 'map<string|string>: nil',
catalog, or a service defined only by [other config description:
entries](/docs/connect/l7-traffic-management). If the wildcard specifier, 'Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.',
`*`, is provided, then ALL services will be exposed through the listener. yaml: false,
This is not supported for listener's with protocol "tcp". },
{
- `Namespace` `(string: "")` - <EnterpriseAlert inline /> The namespace to resolve the service from name: 'metadata',
instead of the current namespace. If empty the current namespace is children: [
assumed. {
name: 'name',
- `Hosts` `(array<string>: <optional>)` - A list of hosts that specify what description: 'Set to the name of the service being configured.',
requests will match this service. This cannot be used with a `tcp` },
listener, and cannot be specified alongside a `*` service name. If not ],
specified, the default domain `<service-name>.ingress.*` will be used to hcl: false,
match services. Requests **must** send the correct host to be routed to },
the defined service. {
name: 'TLS',
The wildcard specifier, `*`, can be used by itself to match all traffic type: 'TLSConfig: <optional>',
coming to the ingress gateway, if TLS is not enabled. This allows a user description: 'TLS configuration for this gateway.',
to route all traffic to a single service without specifying a host, children: [
allowing simpler tests and demos. Otherwise, the wildcard specifier can {
be used as part of the host to match multiple hosts, but only in the name: 'Enabled',
leftmost DNS label. This ensures that all defined hosts are valid DNS type: 'bool: false',
records. For example, `*.example.com` is valid, while `example.*` and description: {
`*-suffix.example.com` are not. hcl:
"Set this configuration to enable TLS for every listener on the gateway.<br><br>If TLS is enabled, then each host defined in the `Host` field will be added as a DNSSAN to the gateway's x509 certificate.",
~> **Note:** If a well-known port is not used, i.e. a port other than 80 yaml:
(http) or 443 (https), then the port must be appended to the host to "Set this configuration to enable TLS for every listener on the gateway.<br><br>If TLS is enabled, then each host defined in the `host` field will be added as a DNSSAN to the gateway's x509 certificate.",
correctly match traffic. This is defined in the [HTTP/1.1 },
RFC](https://tools.ietf.org/html/rfc2616#section-14.23). If TLS is },
enabled, then the host **without** the port must be added to the `Hosts` ],
field as well. TLS verification only matches against the hostname of the },
incoming connection, and thus does not take into account the port. {
name: 'Listeners',
type: 'array<IngressListener>: <optional>)',
description:
'A list of listeners that the ingress gateway should setup, uniquely identified by their port number.',
children: [
{
name: 'Port',
type: 'int: 0',
description: 'The port that the listener should receive traffic on.',
},
{
name: 'Protocol',
type: 'string: "tcp"',
description:
'The protocol associated with the listener. One of `tcp`, `http`, `http2`, or `grpc`.',
},
{
name: 'Services',
type: 'array<IngressService>: <optional>',
description:
'A list of services to be exposed via this listener. For "tcp" listeners, only a single service is allowed.',
children: [
{
name: 'Name',
type: 'string: ""',
description: `The name of the service that should be exposed
through this listener. This can be either a service registered in the
catalog, or a service defined only by [other config entries](/docs/connect/l7-traffic-management). If the wildcard specifier,
\`*\`, is provided, then ALL services will be exposed through the listener.
This is not supported for listener's with protocol "tcp".`,
},
{
name: 'Namespace',
type: 'string: ""',
enterprise: true,
description:
'The namespace to resolve the service from instead of the current namespace. If empty the current namespace is assumed.',
},
{
name: 'Hosts',
type: 'array<string>: <optional>',
description: `A list of hosts that specify what
requests will match this service. This cannot be used with a \`tcp\`
listener, and cannot be specified alongside a \`*\` service name. If not
specified, the default domain \`\<service-name>.ingress.*\` will be used to
match services. Requests <b>must</b> send the correct host to be routed to
the defined service.<br><br>
The wildcard specifier, \`*\`, can be used by itself to match all traffic
coming to the ingress gateway, if TLS is not enabled. This allows a user
to route all traffic to a single service without specifying a host,
allowing simpler tests and demos. Otherwise, the wildcard specifier can
be used as part of the host to match multiple hosts, but only in the
leftmost DNS label. This ensures that all defined hosts are valid DNS
records. For example, \`*.example.com\` is valid, while \`example.*\` and
\`*-suffix.example.com\` are not.<br><br>
<b>Note:</b> If a well-known port is not used, i.e. a port other than 80
(http) or 443 (https), then the port must be appended to the host to
correctly match traffic. This is defined in the [HTTP/1.1 RFC](https://tools.ietf.org/html/rfc2616#section-14.23). If TLS is
enabled, then the host <b>without</b> the port must be added to the \`Hosts\`
field as well. TLS verification only matches against the hostname of the
incoming connection, and thus does not take into account the port.`,
},
],
},
],
},
]}
/>
## ACLs ## ACLs

253
website/content/docs/agent/config-entries/proxy-defaults.mdx
View File

@ -10,79 +10,234 @@ description: >-
# Proxy Defaults # Proxy Defaults
The `proxy-defaults` config entry kind allows for configuring global config -> **v1.8.4+:** On Kubernetes, the `ProxyDefaults` custom resource is supported in Consul versions 1.8.4+.<br />
**v1.5.0+:** On other platforms, this config entry is supported in Consul versions 1.5.0+.
The `proxy-defaults` config entry kind (`ProxyDefaults` on Kubernetes) allows for configuring global config
defaults across all services for Connect proxy configuration. Currently, only defaults across all services for Connect proxy configuration. Currently, only
one global entry is supported. one global entry is supported.
## Sample Config Entries ## Sample Config Entries
Set the default protocol for all sidecar proxies in the default namespace: ### Default protocol
<Tabs>
<Tab heading="HCL">
Set the default protocol for all sidecar proxies:
```hcl ```hcl
Kind = "proxy-defaults" Kind = "proxy-defaults"
Name = "global" Name = "global"
Namespace = "default"
Config { Config {
protocol = "http" protocol = "http"
} }
``` ```
Set proxy-specific defaults : </Tab>
<Tab heading="HCL (Consul Enterprise)">
Set the default protocol for all sidecar proxies.
**NOTE:** The `proxy-defaults` config entry can only be created in the `default`
namespace and it will configure proxies in **all** namespaces.
```hcl ```hcl
Kind = "proxy-defaults" Kind = "proxy-defaults"
Name = "global" Name = "global"
Namespace = "default" # Can only be set to "default".
Config {
protocol = "http"
}
```
</Tab>
<Tab heading="Kubernetes YAML">
Set the default protocol for all sidecar proxies:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
name: global
spec:
config:
protocol: http
```
</Tab>
<Tab heading="Kubernetes YAML (Consul Enterprise)">
Set the default protocol for all sidecar proxies:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
name: global
spec:
config:
protocol: http
```
</Tab>
</Tabs>
### Proxy-specific defaults
<Tabs>
<Tab heading="HCL">
Set proxy-specific defaults:
```hcl
Kind = "proxy-defaults"
Name = "global"
Config { Config {
local_connect_timeout_ms = 1000 local_connect_timeout_ms = 1000
handshake_timeout_ms = 10000 handshake_timeout_ms = 10000
} }
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Set proxy-specific defaults:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
name: global
spec:
config:
local_connect_timeout_ms: 1000
handshake_timeout_ms: 10000
```
</Tab>
</Tabs>
## Available Fields ## Available Fields
- `Kind` - Must be set to `proxy-defaults` <ConfigEntryReference
keys={[
- `Name` - Must be set to `global` {
name: 'apiVersion',
- `Namespace` `(string: "default")` <EnterpriseAlert inline /> - Specifies the namespace the config entry will apply to. description: 'Must be set to `consul.hashicorp.com/v1alpha1`',
hcl: false,
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4. },
{
- `Config` `(map[string]arbitrary)` - An arbitrary map of configuration values used by Connect proxies. name: 'Kind',
The available configurations depend on the Connect proxy you use. Any values description: {
that your proxy allows can be configured globally here. To hcl: 'Must be set to `proxy-defaults`',
explore these options please see the documentation for your chosen proxy. yaml: 'Must be set to `ProxyDefaults`',
},
- [Envoy](/docs/connect/proxies/envoy#bootstrap-configuration) },
- [Consul's built-in proxy](/docs/connect/proxies/built-in) {
name: 'Name',
- `MeshGateway` `(MeshGatewayConfig: <optional>)` - Controls the default description: 'Must be set to `global`',
[mesh gateway configuration](/docs/connect/mesh-gateway#connect-proxy-configuration) yaml: false,
for all proxies. Added in v1.6.0. },
{
- `Mode` `(string: "")` - One of `none`, `local`, or `remote`. name: 'Namespace',
type: `string: "default"`,
- `Expose` `(ExposeConfig: <optional>)` - Controls the default enterprise: true,
[expose path configuration](/docs/connect/registration/service-registration#expose-paths-configuration-reference) description: 'Specifies the namespace the config entry will apply to.',
for Envoy. Added in v1.6.2. yaml: false,
},
Exposing paths through Envoy enables a service to protect itself by only listening on localhost, while still allowing {
non-Connect-enabled applications to contact an HTTP endpoint. name: 'Meta',
Some examples include: exposing a `/metrics` path for Prometheus or `/healthz` for kubelet liveness checks. type: 'map<string|string>: nil',
description:
- `Checks` `(bool: false)` - If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy. 'Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.',
Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's yaml: false,
[advertise address](/docs/agent/options#advertise). The port for these listeners are dynamically allocated from },
[expose_min_port](/docs/agent/options#expose_min_port) to [expose_max_port](/docs/agent/options#expose_max_port). {
This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running name: 'metadata',
Consul on Kubernetes, and Consul agents run in their own pods. children: [{ name: 'name', description: 'Must be set to `global`' }],
- `Paths` `array<Path>: []` - A list of paths to expose through Envoy. hcl: false,
- `Path` `(string: "")` - The HTTP path to expose. The path must be prefixed by a slash. ie: `/metrics`. },
- `LocalPathPort` `(int: 0)` - The port where the local service is listening for connections to the path. {
- `ListenerPort` `(int: 0)` - The port where the proxy will listen for connections. This port must be available name: 'Config',
for the listener to be set up. If the port is not free then Envoy will not expose a listener for the path, type: 'map[string]arbitrary',
but the proxy registration will not fail. description: `An arbitrary map of configuration values used by Connect proxies.
- `Protocol` `(string: "http")` - Sets the protocol of the listener. One of `http` or `http2`. For gRPC use `http2`. The available configurations depend on the Connect proxy you use.
Any values that your proxy allows can be configured globally here. To explore these options please see the documentation for your chosen proxy.
<ul><li>[Envoy](/docs/connect/proxies/envoy#bootstrap-configuration)</li>
<li>[Consul's built-in proxy](/docs/connect/proxies/built-in)</li></ul>`,
},
{
name: 'MeshGateway',
type: 'MeshGatewayConfig: <optional>',
description: `Controls the default
[mesh gateway configuration](/docs/connect/mesh-gateway#connect-proxy-configuration)
for all proxies. Added in v1.6.0.`,
children: [
{
name: 'Mode',
type: 'string: ""',
description: 'One of `none`, `local`, or `remote`.',
},
],
},
{
name: 'Expose',
type: 'ExposeConfig: <optional>',
description: `Controls the default
[expose path configuration](/docs/connect/registration/service-registration#expose-paths-configuration-reference)
for Envoy. Added in v1.6.2.<br><br>
Exposing paths through Envoy enables a service to protect itself by only listening on localhost, while still allowing
non-Connect-enabled applications to contact an HTTP endpoint.
Some examples include: exposing a \`/metrics\` path for Prometheus or \`/healthz\` for kubelet liveness checks.`,
children: [
{
name: 'Checks',
type: 'bool: false',
description: `If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy.
Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's
[advertise address](/docs/agent/options#advertise). The port for these listeners are dynamically allocated from
[expose_min_port](/docs/agent/options#expose_min_port) to [expose_max_port](/docs/agent/options#expose_max_port).
This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running
Consul on Kubernetes, and Consul agents run in their own pods.`,
},
{
name: 'Paths',
type: 'array<Path>: []',
description: 'A list of paths to expose through Envoy.',
children: [
{
name: 'Path',
type: 'string: ""',
description:
'The HTTP path to expose. The path must be prefixed by a slash. ie: `/metrics`.',
},
{
name: 'LocalPathPort',
type: 'int: 0',
description:
'The port where the local service is listening for connections to the path.',
},
{
name: 'ListenerPort',
type: 'int: 0',
description: `The port where the proxy will listen for connections. This port must be available
for the listener to be set up. If the port is not free then Envoy will not expose a listener for the path,
but the proxy registration will not fail.`,
},
{
name: 'Protocol',
type: 'string: "http"',
description:
'Sets the protocol of the listener. One of `http` or `http2`. For gRPC use `http2`.',
},
],
},
],
},
]}
/>
## ACLs ## ACLs

208
website/content/docs/agent/config-entries/service-defaults.mdx
View File

@ -9,11 +9,19 @@ description: >-
# Service Defaults # Service Defaults
The `service-defaults` config entry kind controls default global values for a -> **v1.8.4+:** On Kubernetes, the `ServiceDefaults` custom resource is supported in Consul versions 1.8.4+.<br />
**v1.5.0+:** On other platforms, this config entry is supported in Consul versions 1.5.0+.
The `service-defaults` config entry kind (`ServiceDefaults` on Kubernetes) controls default global values for a
service, such as its protocol. service, such as its protocol.
## Sample Config Entries ## Sample Config Entries
### Default protocol
<Tabs>
<Tab heading="HCL">
Set the default protocol for a service in the default namespace to HTTP: Set the default protocol for a service in the default namespace to HTTP:
```hcl ```hcl
@ -23,56 +31,158 @@ Namespace = "default"
Protocol = "http" Protocol = "http"
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Set the default protocol for a service in the default namespace to HTTP:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
name: web
spec:
protocol: http
```
</Tab>
</Tabs>
## Available Fields ## Available Fields
- `Kind` - Must be set to `service-defaults` <ConfigEntryReference
keys={[
- `Name` `(string: <required>)` - Set to the name of the service being configured. {
name: 'apiVersion',
- `Namespace` `(string: "default")` <EnterpriseAlert inline /> - Specifies the namespace the config entry will apply to. description: 'Must be set to `consul.hashicorp.com/v1alpha1`',
hcl: false,
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4. },
{
- `Protocol` `(string: "tcp")` - Sets the protocol of the service. This is used name: 'Kind',
by Connect proxies for things like observability features and to unlock usage description: {
of the [`service-splitter`](/docs/agent/config-entries/service-splitter) and hcl: 'Must be set to `service-defaults`',
[`service-router`](/docs/agent/config-entries/service-router) config entries yaml: 'Must be set to `ServiceDefaults`',
for a service. It also unlocks the ability to define L7 intentions via },
[`service-intentions`](/docs/agent/config-entries/service-intentions). },
Supported values are one of `tcp`, `http`, `http2`, or `grpc`. {
name: 'Name',
- `MeshGateway` `(MeshGatewayConfig: <optional>)` - Controls the default description: 'Set to the name of the service being configured.',
[mesh gateway configuration](/docs/connect/mesh-gateway#connect-proxy-configuration) type: 'string: <required>',
for this service. Added in v1.6.0. yaml: false,
},
- `Mode` `(string: "")` - One of `none`, `local`, or `remote`. {
name: 'Namespace',
- `ExternalSNI` `(string: "")` - This is an optional setting that allows for type: `string: "default"`,
the TLS [SNI](https://en.wikipedia.org/wiki/Server_Name_Indication) value to enterprise: true,
be changed to a non-connect value when federating with an external system. description: 'Specifies the namespace the config entry will apply to.',
Added in v1.6.0. yaml: false,
},
- `Expose` `(ExposeConfig: <optional>)` - Controls the default {
[expose path configuration](/docs/connect/registration/service-registration#expose-paths-configuration-reference) name: 'Meta',
for Envoy. Added in v1.6.2. type: 'map<string|string>: nil',
description:
Exposing paths through Envoy enables a service to protect itself by only listening on localhost, while still allowing 'Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.',
non-Connect-enabled applications to contact an HTTP endpoint. yaml: false,
Some examples include: exposing a `/metrics` path for Prometheus or `/healthz` for kubelet liveness checks. },
{
- `Checks` `(bool: false)` - If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy. name: 'metadata',
Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's children: [
[advertise address](/docs/agent/options#advertise). The port for these listeners are dynamically allocated from {
[expose_min_port](/docs/agent/options#expose_min_port) to [expose_max_port](/docs/agent/options#expose_max_port). name: 'name',
This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running description: 'Set to the name of the service being configured.',
Consul on Kubernetes, and Consul agents run in their own pods. },
- `Paths` `array<Path>: []` - A list of paths to expose through Envoy. ],
- `Path` `(string: "")` - The HTTP path to expose. The path must be prefixed by a slash. ie: `/metrics`. hcl: false,
- `LocalPathPort` `(int: 0)` - The port where the local service is listening for connections to the path. },
- `ListenerPort` `(int: 0)` - The port where the proxy will listen for connections. This port must be available for {
the listener to be set up. If the port is not free then Envoy will not expose a listener for the path, name: 'Protocol',
but the proxy registration will not fail. type: `string: "tcp"`,
- `Protocol` `(string: "http")` - Sets the protocol of the listener. One of `http` or `http2`. For gRPC use `http2`. description: `Sets the protocol of the service. This is used
by Connect proxies for things like observability features and to unlock usage
of the [\`service-splitter\`](/docs/agent/config-entries/service-splitter) and
[\`service-router\`](/docs/agent/config-entries/service-router) config entries
for a service. It also unlocks the ability to define L7 intentions via
[\`service-intentions\`](/docs/agent/config-entries/service-intentions).
Supported values are one of \`tcp\`, \`http\`, \`http2\`, or \`grpc\`.`,
},
{
name: 'MeshGateway',
type: 'MeshGatewayConfig: <optional>',
description: `Controls the default
[mesh gateway configuration](/docs/connect/mesh-gateway#connect-proxy-configuration)
for this service. Added in v1.6.0.`,
children: [
{
name: 'Mode',
type: 'string: ""',
description: 'One of `none`, `local`, or `remote`.',
},
],
},
{
name: 'ExternalSNI',
type: 'string: ""',
description: `This is an optional setting that allows for
the TLS [SNI](https://en.wikipedia.org/wiki/Server_Name_Indication) value to
be changed to a non-connect value when federating with an external system.
Added in v1.6.0.`,
},
{
name: 'Expose',
type: 'ExposeConfig: <optional>',
description: `Controls the default
[expose path configuration](/docs/connect/registration/service-registration#expose-paths-configuration-reference)
for Envoy. Added in v1.6.2.<br><br>
Exposing paths through Envoy enables a service to protect itself by only listening on localhost, while still allowing
non-Connect-enabled applications to contact an HTTP endpoint.
Some examples include: exposing a \`/metrics\` path for Prometheus or \`/healthz\` for kubelet liveness checks.`,
children: [
{
name: 'Checks',
type: 'bool: false',
description: `If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy.
Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's
[advertise address](/docs/agent/options#advertise). The port for these listeners are dynamically allocated from
[expose_min_port](/docs/agent/options#expose_min_port) to [expose_max_port](/docs/agent/options#expose_max_port).
This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running
Consul on Kubernetes, and Consul agents run in their own pods.`,
},
{
name: 'Paths',
type: 'array<Path>: []',
description: 'A list of paths to expose through Envoy.',
children: [
{
name: 'Path',
type: 'string: ""',
description:
'The HTTP path to expose. The path must be prefixed by a slash. ie: `/metrics`.',
},
{
name: 'LocalPathPort',
type: 'int: 0',
description:
'The port where the local service is listening for connections to the path.',
},
{
name: 'ListenerPort',
type: 'int: 0',
description: `The port where the proxy will listen for connections. This port must be available
for the listener to be set up. If the port is not free then Envoy will not expose a listener for the path,
but the proxy registration will not fail.`,
},
{
name: 'Protocol',
type: 'string: "http"',
description:
'Sets the protocol of the listener. One of `http` or `http2`. For gRPC use `http2`.',
},
],
},
],
},
]}
/>
## ACLs ## ACLs

601
website/content/docs/agent/config-entries/service-intentions.mdx
View File

@ -12,7 +12,7 @@ description: >-
-> **1.9.0+:** This config entry is available in Consul versions 1.9.0 and newer. -> **1.9.0+:** This config entry is available in Consul versions 1.9.0 and newer.
The `service-intentions` config entry kind controls Connect traffic The `service-intentions` config entry kind (`ServiceIntentions` on Kubernetes) controls Connect traffic
authorization for both networking layer 4 (e.g. TCP) and networking layer 7 authorization for both networking layer 4 (e.g. TCP) and networking layer 7
(e.g. HTTP). (e.g. HTTP).
@ -35,6 +35,11 @@ or globally via [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) .
## Sample Config Entries ## Sample Config Entries
### REST Access
<Tabs>
<Tab heading="HCL">
Grant some clients more REST access than others: Grant some clients more REST access than others:
```hcl ```hcl
@ -70,6 +75,44 @@ Sources = [
] ]
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Grant some clients more REST access than others:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceIntentions
metadata:
name: api
spec:
destination:
name: api
sources:
- name: admin-dashboard
permissions:
- action: allow
http:
pathPrefix: /v2
methods: ['GET', 'PUT', 'POST', 'DELETE', 'HEAD']
- name: report-generator
permissions:
- action: allow
http:
pathPrefix: /v2/widgets
methods: ['GET']
# NOTE: a default catch-all based on the default ACL policy will apply to
# unmatched connections and requests. Typically this will be DENY.
```
</Tab>
</Tabs>
## gRPC
<Tabs>
<Tab heading="HCL">
Selectively deny some gRPC service methods. Since gRPC method calls [are Selectively deny some gRPC service methods. Since gRPC method calls [are
HTTP/2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can HTTP/2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can
use an HTTP path match rule to control traffic: use an HTTP path match rule to control traffic:
@ -114,6 +157,50 @@ Sources = [
] ]
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Selectively deny some gRPC service methods. Since gRPC method calls [are
HTTP/2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can
use an HTTP path match rule to control traffic:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceIntentions
metadata:
name: billing
spec:
destination:
name: billing
sources:
# The frontend website can execute all billing service methods except
# issuing refunds.
- name: frontend-web
permissions:
- action: deny
http:
pathExact: /mycompany.BillingService/IssueRefund
- action: allow
http:
pathPrefix: '/mycompany.BillingService/'
- name: support-protocol
# But the support team portal page can execute all methods.
permissions:
- action: allow
http:
pathPrefix: '/mycompany.BillingService/'
# NOTE: a default catch-all based on the default ACL policy will apply to
# unmatched connections and requests. Typically this will be DENY.
```
</Tab>
</Tabs>
## L4 and L7
<Tabs>
<Tab heading="HCL">
You can mix and match L4 and L7 intentions per source: You can mix and match L4 and L7 intentions per source:
```hcl ```hcl
@ -145,167 +232,379 @@ Sources = [
] ]
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
You can mix and match L4 and L7 intentions per source:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceIntentions
metadata:
name: api
spec:
destination:
name: api
sources:
- name: hackathon-project
action: deny
- name: web
action: allow
- name: nightly-reconciler
permissions:
- action: allow
http:
pathExact: /v1/reconcile-data
methods: ['POST']
# NOTE: a default catch-all based on the default ACL policy will apply to
# unmatched connections and requests. Typically this will be DENY.
```
</Tab>
</Tabs>
## Available Fields ## Available Fields
- `Kind` - Must be set to `service-intentions`. <ConfigEntryReference
keys={[
- `Name` `(string: <required>)` - The destination of all intentions defined in {
this config entry. This may be set to the wildcard character (`*`) to match name: 'apiVersion',
all services that don't otherwise have intentions defined. description: 'Must be set to `consul.hashicorp.com/v1alpha1`',
hcl: false,
- `Namespace` `(string: "default")` <EnterpriseAlert inline /> - Specifies the namespace the config entry will apply to. },
This may be set to the wildcard character (`*`) to match {
all services in all namespaces that don't otherwise have intentions defined. name: 'Kind',
description: {
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs. hcl: 'Must be set to `service-intentions`',
yaml: 'Must be set to `ServiceIntentions`',
- `Sources` `(array<SourceIntention>)` - The list of all [intention sources and },
the authorization granted to those sources](#sourceintention). The order of },
this list does not matter, but out of convenience Consul will always store {
this reverse sorted by intention precedence, as that is the order that they name: 'Name',
will be evaluated at enforcement time. description:
"The name of the destination service for all intentions defined in this config entry. This may be set to the wildcard character (`*`) to match all services that don't otherwise have intentions defined.",
type: 'string: <required>',
yaml: false,
},
{
name: 'Namespace',
type: `string: "default"`,
enterprise: true,
description:
"Specifies the namespaces the config entry will apply to. This may be set to the wildcard character (`*`) to match all services in all namespaces that don't otherwise have intentions defined.",
yaml: false,
},
{
name: 'Meta',
type: 'map<string|string>: nil',
description: 'Specifies arbitrary KV metadata pairs.',
yaml: false,
},
{
name: 'metadata',
children: [
{
name: 'name',
description:
'Unlike other config entries, the `metadata.name` field is not used to set the name of the service being configured. Instead, that is set in `spec.destination.name`. Thus this name can be set to anything.',
},
],
hcl: false,
},
{
name: 'destination',
hcl: false,
children: [
{
name: 'name',
hcl: false,
type: 'string: <required>',
description:
"The name of the destination service for all intentions defined in this config entry. This may be set to the wildcard character (`*`) to match all services that don't otherwise have intentions defined.",
},
{
name: 'namespace',
hcl: false,
enterprise: true,
type: 'string: <required>',
description:
"Specifies the namespaces the config entry will apply to. This may be set to the wildcard character (`*`) to match all services in all namespaces that don't otherwise have intentions defined.",
},
],
},
{
name: 'Sources',
type: 'array<SourceIntention>',
description: `The list of all [intention sources and the authorization granted to those sources](#sourceintention). The order of
this list does not matter, but out of convenience Consul will always store
this reverse sorted by intention precedence, as that is the order that they
will be evaluated at enforcement time.`,
},
]}
/>
### `SourceIntention` ### `SourceIntention`
- `Name` `(string: <required>)` - The source of the intention. <ConfigEntryReference
For a `Type` of `consul` this is the name of a Consul service. The service topLevel={false}
doesn't need to be registered. keys={[
{
- `Namespace` `(string: "default")` <EnterpriseAlert inline /> - The namespace name: 'Name',
for the `Name` parameter. type: 'string: <required>',
description: {
- `Action` `(string: "")` - For an L4 intention this is required, and should be hcl:
set to one of `"allow"` or `"deny"` for the action that should be taken if "The source of the intention. For a `Type` of `consul` this is the name of a Consul service. The service doesn't need to be registered.",
this intention matches a request. yaml:
"The source of the intention. For a `type` of `consul` this is the name of a Consul service. The service doesn't need to be registered.",
This should be omitted for an L7 intention as it is mutually exclusive with },
the `Permissions` field. },
{
- `Permissions` `(array<IntentionPermission>)` - The list of all [additional L7 name: 'Namespace',
attributes](#intentionpermission) that extend the intention match criteria. type: 'string',
description: {
Permission precedence is applied top to bottom. For any given request the hcl:
first permission to match in the list is terminal and stops further "The namespace of the source service. Defaults to the namespace of the destination service (i.e. the config entry's namespace)",
evaluation. As with L4 intentions, traffic that fails to match any of the yaml:
provided permissions in this intention will be subject to the default 'The namespace of the source service. Defaults to the namespace of the destination service (i.e. `spec.destination.namespace`)',
intention behavior is defined by the default [ACL },
policy](/docs/agent/options#acl_default_policy). enterprise: true,
},
This should be omitted for an L4 intention as it is mutually exclusive with {
the `Action` field. name: 'Action',
type: 'string: ""',
- `Precedence` `(int: <read-only>)` - An [integer precedence description: {
value](/docs/connect/intentions#precedence-and-match-order) computed from the hcl:
source and destination naming components. 'For an L4 intention this is required, and should be set to one of `"allow"` or `"deny"` for the action that should be taken if this intention matches a request.' +
'<br><br>This should be omitted for an L7 intention as it is mutually exclusive with the `Permissions` field.',
- `Type` `(string: "")` - The type for the `Name` value. This can be yaml:
only "consul" today to represent a Consul service. If not provided, this 'For an L4 intention this is required, and should be set to one of `"allow"` or `"deny"` for the action that should be taken if this intention matches a request.' +
will be defaulted to "consul". '<br><br>This should be omitted for an L7 intention as it is mutually exclusive with the `permissions` field.',
},
- `Description` `(string: "")` - Description for the intention. This is not },
used by Consul, but is presented in API responses to assist tooling. {
name: 'Permissions',
- `LegacyID` `(string: <read-only>)` - This is the UUID to uniquely identify type: 'array<IntentionPermission>',
this intention in the system. Cannot be set directly and is exposed here as description: {
an artifact of the config entry migration and is primarily used to allow hcl: `The list of all [additional L7 attributes](#intentionpermission) that extend the intention match criteria.<br><br>
legacy intention [API](/api-docs/connect/intentions#update-intention-by-id) Permission precedence is applied top to bottom. For any given request the
[endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to first permission to match in the list is terminal and stops further
continue to function for a period of time after [upgrading to evaluation. As with L4 intentions, traffic that fails to match any of the
1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0). provided permissions in this intention will be subject to the default
intention behavior is defined by the default [ACL policy](/docs/agent/options#acl_default_policy).<br><br>
- `LegacyMeta` `(map<string|string>: <read-only>)` - Specified arbitrary KV This should be omitted for an L4 intention as it is mutually exclusive with
metadata pairs attached to the intention, rather than to the enclosing config the \`Action\` field.`,
entry. Cannot be set directly and is exposed here as an artifact of the yaml: `The list of all [additional L7 attributes](#intentionpermission) that extend the intention match criteria.<br><br>
config entry migration and is primarily used to allow legacy intention Permission precedence is applied top to bottom. For any given request the
[API](/api-docs/connect/intentions#update-intention-by-id) first permission to match in the list is terminal and stops further
[endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to evaluation. As with L4 intentions, traffic that fails to match any of the
continue to function for a period of time after [upgrading to provided permissions in this intention will be subject to the default
1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0). intention behavior is defined by the default [ACL policy](/docs/agent/options#acl_default_policy).<br><br>
This should be omitted for an L4 intention as it is mutually exclusive with
- `LegacyCreateTime` `(time: optional)` - The timestamp that this intention was the \`action\` field.`,
created. Cannot be set directly and is exposed here as an artifact of the },
config entry migration and is primarily used to allow legacy intention },
[API](/api-docs/connect/intentions#update-intention-by-id) {
[endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to name: 'Precedence',
continue to function for a period of time after [upgrading to type: 'int: <read-only>',
1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0). description:
'An [integer precedence value](/docs/connect/intentions#precedence-and-match-order) computed from the source and destination naming components.',
- `LegacyUpdateTime` `(time: optional)` - The timestamp that this intention was yaml: false,
last updated. Cannot be set directly and is exposed here as an artifact of },
the config entry migration and is primarily used to allow legacy intention {
[API](/api-docs/connect/intentions#update-intention-by-id) name: 'Type',
[endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to type: 'string: "consul"',
continue to function for a period of time after [upgrading to description: {
1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0). hcl:
'The type for the `Name` value. This can be only "consul" today to represent a Consul service. If not provided, this will be defaulted to "consul".',
yaml:
'The type for the `name` value. This can be only "consul" today to represent a Consul service. If not provided, this will be defaulted to "consul".',
},
},
{
name: 'Description',
type: 'string: ""',
description:
'Description for the intention. This is not used by Consul, but is presented in API responses to assist tooling.',
},
{
name: 'LegacyID',
type: 'string: <read-only>',
description: `This is the UUID to uniquely identify
this intention in the system. Cannot be set directly and is exposed here as
an artifact of the config entry migration and is primarily used to allow
legacy intention [API](/api-docs/connect/intentions#update-intention-by-id)
[endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to
continue to function for a period of time after [upgrading to 1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0).`,
yaml: false,
},
{
name: 'LegacyMeta',
type: 'map<string|string>: <read-only>',
description: `Specified arbitrary KV
metadata pairs attached to the intention, rather than to the enclosing config
entry. Cannot be set directly and is exposed here as an artifact of the
config entry migration and is primarily used to allow legacy intention
[API](/api-docs/connect/intentions#update-intention-by-id)
[endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to
continue to function for a period of time after [upgrading to 1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0).`,
yaml: false,
},
{
name: 'LegacyCreateTime',
type: 'time: optional',
description: `The timestamp that this intention was
created. Cannot be set directly and is exposed here as an artifact of the
config entry migration and is primarily used to allow legacy intention
[API](/api-docs/connect/intentions#update-intention-by-id)
[endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to
continue to function for a period of time after [upgrading to 1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0).`,
yaml: false,
},
{
name: 'LegacyUpdateTime',
type: 'time: optional',
description: `The timestamp that this intention was
last updated. Cannot be set directly and is exposed here as an artifact of the
config entry migration and is primarily used to allow legacy intention
[API](/api-docs/connect/intentions#update-intention-by-id)
[endpoints](/api-docs/connect/intentions#read-specific-intention-by-id) to
continue to function for a period of time after [upgrading to 1.9.0](/docs/upgrading/upgrade-specific#consul-1-9-0).`,
yaml: false,
},
]}
/>
### `IntentionPermission` ### `IntentionPermission`
- `Action` `(string: <required>)` - This is one of "allow" or "deny" for <ConfigEntryReference
the action that should be taken if this permission matches a request. topLevel={false}
keys={[
- `HTTP` `(IntentionHTTPPermission: <required>)` - A set of {
[HTTP-specific authorization criteria](#intentionhttppermission). name: 'Action',
type: 'string: <required>',
description:
'This is one of "allow" or "deny" for the action that should be taken if this permission matches a request.',
},
{
name: 'HTTP',
type: 'IntentionHTTPPermission: <required>',
description:
'A set of [HTTP-specific authorization criteria](#intentionhttppermission)',
},
]}
/>
### `IntentionHTTPPermission` ### `IntentionHTTPPermission`
- `PathExact` `(string: "")` - Exact path to match on the HTTP request path. <ConfigEntryReference
topLevel={false}
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured. keys={[
{
- `PathPrefix` `(string: "")` - Path prefix to match on the HTTP request path. name: 'PathExact',
type: 'string: ""',
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured. description: {
hcl:
- `PathRegex` `(string: "")` - Regular expression to match on the HTTP 'Exact path to match on the HTTP request path.<br><br>At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.',
request path. yaml:
'Exact path to match on the HTTP request path.<br><br>At most only one of `pathExact`, `pathPrefix`, or `pathRegex` may be configured.',
The syntax is [described below](#regular-expression-syntax). },
},
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured. {
name: 'PathPrefix',
- `Methods` `(array<string>)` - A list of HTTP methods for which this match type: 'string: ""',
applies. If unspecified all HTTP methods are matched. description: {
If provided the names must be a valid [method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). hcl:
'Path prefix to match on the HTTP request path.<br><br>At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.',
- `Header` `(array<IntentionHTTPHeaderPermission>)` - A set of criteria that can yaml:
match on HTTP request headers. If more than one is configured all must match 'Path prefix to match on the HTTP request path.<br><br>At most only one of `pathExact`, `pathPrefix`, or `pathRegex` may be configured.',
for the overall match to apply. },
},
- `Name` `(string: <required>)` - Name of the header to match. {
name: 'PathRegex',
- `Present` `(bool: false)` - Match if the header with the given name is type: 'string: ""',
present with any value. description: {
hcl:
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` 'Regular expression to match on the HTTP request path.<br><br>The syntax is [described below](#regular-expression-syntax).<br><br>At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.',
may be configured. yaml:
'Regular expression to match on the HTTP request path.<br><br>The syntax is [described below](#regular-expression-syntax).<br><br>At most only one of `pathExact`, `pathPrefix`, or `pathRegex` may be configured.',
- `Exact` `(string: "")` - Match if the header with the given name is this },
value. },
{
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` name: 'Methods',
may be configured. type: 'array<string>',
description:
- `Prefix` `(string: "")` - Match if the header with the given name has 'A list of HTTP methods for which this match applies. If unspecified all HTTP methods are matched. If provided the names must be a valid [method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods).',
this prefix. },
{
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` name: 'Header',
may be configured. type: 'array<IntentionHTTPHeaderPermission>',
description:
- `Suffix` `(string: "")` - Match if the header with the given name has 'A set of criteria that can match on HTTP request headers. If more than one is configured all must match for the overall match to apply.',
this suffix. children: [
{
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` name: 'Name',
may be configured. type: 'string: <required>',
description: 'Name of the header to match',
- `Regex` `(string: "")` - Match if the header with the given name matches },
this pattern. {
name: 'Present',
The syntax is [described below](#regular-expression-syntax). type: 'bool: false',
description: {
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` hcl:
may be configured. 'Match if the header with the given name is present with any value.<br><br> At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` may be configured.',
yaml:
- `Invert` `(bool: false)` - Inverts the logic of the match. 'Match if the header with the given name is present with any value.<br><br> At most only one of `exact`, `prefix`, `suffix`, `regex`, or `present` may be configured.',
},
},
{
name: 'Exact',
type: 'string: ""',
description: {
hcl:
'Match if the header with the given name is this value.<br><br> At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` may be configured.',
yaml:
'Match if the header with the given name is this value.<br><br> At most only one of `exact`, `prefix`, `suffix`, `regex`, or `present` may be configured.',
},
},
{
name: 'Prefix',
type: 'string: ""',
description: {
hcl:
'Match if the header with the given name has this prefix.<br><br> At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` may be configured.',
yaml:
'Match if the header with the given name has this prefix.<br><br> At most only one of `exact`, `prefix`, `suffix`, `regex`, or `present` may be configured.',
},
},
{
name: 'Suffix',
type: 'string: ""',
description: {
hcl:
'Match if the header with the given name has this suffix.<br><br> At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` may be configured.',
yaml:
'Match if the header with the given name has this suffix.<br><br> At most only one of `exact`, `prefix`, `suffix`, `regex`, or `present` may be configured.',
},
},
{
name: 'Regex',
type: 'string: ""',
description: {
hcl:
'Match if the header with the given name matches this pattern.<br><br>The syntax is [described below](#regular-expression-syntax).<br><br> At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` may be configured.',
yaml:
'Match if the header with the given name matches this pattern.<br><br>The syntax is [described below](#regular-expression-syntax).<br><br> At most only one of `exact`, `prefix`, `suffix`, `regex`, or `present` may be configured.',
},
},
{
name: 'Invert',
type: 'bool: false',
description: 'Inverts the logic of the match',
},
],
},
]}
/>
## ACLs ## ACLs

543
website/content/docs/agent/config-entries/service-resolver.mdx
View File

@ -9,9 +9,10 @@ description: >-
# Service Resolver # Service Resolver
-> **1.6.0+:** This config entry is available in Consul versions 1.6.0 and newer. -> **v1.8.4+:** On Kubernetes, the `ServiceResolver` custom resource is supported in Consul versions 1.8.4+.<br />
**v1.6.0+:** On other platforms, this config entry is supported in Consul versions 1.6.0+.
The `service-resolver` config entry kind controls which service instances The `service-resolver` config entry kind (`ServiceResolver` on Kubernetes) controls which service instances
should satisfy Connect upstream discovery requests for a given service name. should satisfy Connect upstream discovery requests for a given service name.
If no resolver config is defined the chain assumes 100% of traffic goes to the If no resolver config is defined the chain assumes 100% of traffic goes to the
@ -25,6 +26,11 @@ and discovery terminates.
## Sample Config Entries ## Sample Config Entries
### Filter on service version
<Tabs>
<Tab heading="HCL">
Create service subsets based on a version metadata and override the defaults: Create service subsets based on a version metadata and override the defaults:
```hcl ```hcl
@ -41,6 +47,33 @@ Subsets = {
} }
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Create service subsets based on a version metadata and override the defaults:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
metadata:
name: web
spec:
defaultSubset: 'v1'
subsets:
'v1':
filter: 'Service.Meta.version == v1'
'v2':
filter: 'Service.Meta.version == v2'
```
</Tab>
</Tabs>
### Other datacenters
<Tabs>
<Tab heading="HCL">
Expose a set of services in another datacenter as a virtual service: Expose a set of services in another datacenter as a virtual service:
```hcl ```hcl
@ -52,6 +85,30 @@ Redirect {
} }
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Expose a set of services in another datacenter as a virtual service:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
metadata:
name: web-dc2
spec:
redirect:
service: web
datacenter: dc2
```
</Tab>
</Tabs>
### Datacenter failover
<Tabs>
<Tab heading="HCL">
Enable failover for all subsets: Enable failover for all subsets:
```hcl ```hcl
@ -65,13 +122,31 @@ Failover = {
} }
``` ```
Representation of the defaults when a resolver is not configured: </Tab>
<Tab heading="Kubernetes YAML">
```hcl Enable failover for all subsets:
Kind = "service-resolver"
Name = "web" ```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
metadata:
name: web
spec:
connectTimeout: 15s
failover:
'*':
datacenters: ['dc3', 'dc4']
``` ```
</Tab>
</Tabs>
### Consistent load balancing
<Tabs>
<Tab heading="HCL">
Apply consistent load balancing for requests based on `x-user-id` header: Apply consistent load balancing for requests based on `x-user-id` header:
```hcl ```hcl
@ -89,137 +164,335 @@ LoadBalancer = {
} }
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Apply consistent load balancing for requests based on `x-user-id` header:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
metadata:
name: web
spec:
loadBalancer:
policy: maglev
hashPolicies:
- field: header
fieldValue: x-user-id
```
</Tab>
</Tabs>
## Available Fields ## Available Fields
- `Kind` - Must be set to `service-resolver` <ConfigEntryReference
keys={[
- `Name` `(string: <required>)` - Set to the name of the service being configured. {
name: 'apiVersion',
- `Namespace` `(string: "default")` <EnterpriseAlert inline /> - Specifies the namespace the config entry will apply to. description: 'Must be set to `consul.hashicorp.com/v1alpha1`',
hcl: false,
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4. },
{
- `ConnectTimeout` `(duration: 0s)` - The timeout for establishing new network name: 'Kind',
connections to this service. description: {
hcl: 'Must be set to `service-resolver`',
- `DefaultSubset` `(string: "")` - The subset to use when no explicit subset is yaml: 'Must be set to `ServiceResolver`',
requested. If empty the unnamed subset is used. },
},
- `Subsets` `(map[string]ServiceResolverSubset)` - A map of subset name to {
subset definition for all usable named subsets of this service. The map key name: 'Name',
is the name of the subset and all names must be valid DNS subdomain elements. description: 'Set to the name of the service being configured.',
type: 'string: <required>',
This may be empty, in which case only the unnamed default subset will be yaml: false,
usable. },
{
- `Filter` `(string: "")` - The name: 'Namespace',
[filter expression](/api/features/filtering) to be used for selecting type: `string: "default"`,
instances of the requested service. If empty all healthy instances are enterprise: true,
returned. This expression can filter on the same selectors as the description: 'Specifies the namespace the config entry will apply to.',
[Health API endpoint](/api/health#filtering-2). yaml: false,
},
- `OnlyPassing` `(bool: false)` - Specifies the behavior of the resolver's {
health check interpretation. If this is set to false, instances with checks name: 'Meta',
in the passing as well as the warning states will be considered healthy. If type: 'map<string|string>: nil',
this is set to true, only instances with checks in the passing state will description:
be considered healthy. 'Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.',
yaml: false,
- `Redirect` `(ServiceResolverRedirect: <optional>)` - When configured, all },
attempts to resolve the service this resolver defines will be substituted for {
the supplied redirect EXCEPT when the redirect has already been applied. name: 'metadata',
children: [
When substituting the supplied redirect into the all other fields besides {
`Kind`, `Name`, and `Redirect` will be ignored. name: 'name',
description: 'Set to the name of the service being configured.',
- `Service` `(string: "")` - A service to resolve instead of the current },
service. ],
hcl: false,
- `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. name: 'ConnectTimeout',
type: 'duration: 0s',
If this is specified at least one of Service, Datacenter, or Namespace description:
should be configured. 'The timeout for establishing new network connections to this service.',
},
- `Namespace` `(string: "")` - The namespace to resolve the service from {
instead of the current one. name: 'DefaultSubset',
type: 'string: ""',
- `Datacenter` `(string: "")` - The datacenter to resolve the service from description:
instead of the current one. 'The subset to use when no explicit subset is requested. If empty the unnamed subset is used.',
},
- `Failover` `(map[string]ServiceResolverFailover`) - Controls when and how to {
reroute traffic to an alternate pool of service instances. name: 'Subsets',
type: 'map[string]ServiceResolverSubset',
The map is keyed by the service subset it applies to and the special description:
string `"*"` is a wildcard that applies to any subset not otherwise 'A map of subset name to subset definition for all usable named subsets of this service. The map key is the name of the subset and all names must be valid DNS subdomain elements.<br><br>This may be empty, in which case only the unnamed default subset will be usable.',
specified here. children: [
{
`Service`, `ServiceSubset`, `Namespace`, and `Datacenters` cannot all be name: 'Filter',
empty at once. type: 'string: ""',
description: `The [filter expression](/api/features/filtering) to be used for selecting
- `Service` `(string: "")` - The service to resolve instead of the default as instances of the requested service. If empty all healthy instances are
the failover group of instances during failover. returned. This expression can filter on the same selectors as the
[Health API endpoint](/api/health#filtering-2).`,
- `ServiceSubset` `(string: "")` - The named subset of the requested service },
to resolve as the failover group of instances. If empty the default subset {
for the requested service is used. name: 'OnlyPassing',
type: 'bool: false',
- `Namespace` `(string: "")` - The namespace to resolve the requested service description: `Specifies the behavior of the resolver's
from to form the failover group of instances. If empty the current health check interpretation. If this is set to false, instances with checks
namespace is used. in the passing as well as the warning states will be considered healthy. If
this is set to true, only instances with checks in the passing state will
- `Datacenters` `(array<string>)` - A fixed list of datacenters to try during be considered healthy.`,
failover. },
],
- `LoadBalancer` `(LoadBalancer`) - Determines the load balancing policy and },
configuration for services issuing requests to this upstream. {
This option is available in Consul versions 1.9.0 and newer. name: 'Redirect',
type: 'ServiceResolverRedirect: <optional>',
- `Policy` `(string: "")` - The load balancing policy used to select a host. description: {
One of: `random`, `round_robin`, `least_request`, `ring_hash`, `maglev`. hcl: `When configured, all
attempts to resolve the service this resolver defines will be substituted for
- `RingHashConfig` `(RingHashConfig)` - Configuration for the `ring_hash` the supplied redirect EXCEPT when the redirect has already been applied.
policy type. <br><br>
When substituting the supplied redirect into the all other fields besides
- `MinimumRingRize` `(int: 1024)` - Determines the minimum number of entries \`Kind\`, \`Name\`, and \`Redirect\` will be ignored.`,
in the hash ring. yaml: `When configured, all
attempts to resolve the service this resolver defines will be substituted for
- `MaximumRingRize` `(int: 8192)` - Determines the maximum number of entries the supplied redirect EXCEPT when the redirect has already been applied.
in the hash ring. <br><br>
When substituting the supplied redirect into the all other fields besides
- `LeastRequestConfig` `(LeastRequestConfig)` - Configuration for the `least_request` \`redirect\` will be ignored.`,
policy type. },
children: [
- `ChoiceCount` `(int: 2)` - Determines the number of random healthy hosts {
from which to select the one with the least requests. name: 'Service',
type: 'string: ""',
- `HashPolicies` `(array<HashPolicies>)` - a list of hash policies to use for description: 'A service to resolve instead of the current service.',
hashing load balancing algorithms. Hash policies are evaluated individually },
and combined such that identical lists result in the same hash. {
If no hash policies are present, or none are successfully evaluated, name: 'ServiceSubset',
then a random backend host will be selected. type: 'string: ""',
description: {
- `Field` `(string: "")` - The attribute type to hash on. hcl: `A named subset of the given service to
Must be one of `header`,`cookie`, or `query_parameter`. resolve instead of one defined as that service's \`DefaultSubset\`. If empty, the
Cannot be specified along with `SourceAddress`. default subset is used.
- `FieldValue` `(string: "")` - The value to hash. <br><br>
ie. header name, cookie name, URL query parameter name. If this is specified at least one of \`Service\`, \`Datacenter\`, or \`Namespace\`
Cannot be specified along with `SourceAddress`. should be configured.`,
- `CookieConfig` `(CookieConfig)` - Additional configuration for the "cookie" hash policy type. yaml: `A named subset of the given service to
This is specified to have Envoy generate a cookie for a client on its first request. resolve instead of one defined as that service's \`defaultSubset\`. If empty, the
default subset is used.
- `Session` `(bool: false)` - Generates a session cookie with no expiration. <br><br>
If this is specified at least one of \`service\`, \`datacenter\`, or \`namespace\`
- `TTL` `(duration: 0s)` - TTL for generated cookies. Cannot be specified for session cookies. should be configured.`,
- `Path` `(string: "")` - The path to set for the cookie. },
},
- `SourceIP` `(bool: false)` - Determines whether the hash should be of the source IP {
address rather than of a field and field value. name: 'Namespace',
Cannot be specified along with `Field` or `FieldValue`. enterprise: true,
- `Terminal` `(bool: false)` - Will short circuit the computation of the hash type: 'string: ""',
when multiple hash policies are present. If a hash is computed when a description:
Terminal policy is evaluated, then that hash will be used and subsequent 'The namespace to resolve the service from instead of the current one.',
hash policies will be ignored. },
{
name: 'Datacenter',
type: 'string: ""',
description:
'The datacenter to resolve the service from instead of the current one.',
},
],
},
{
name: 'Failover',
type: 'map[string]ServiceResolverFailover',
description: {
hcl: `Controls when and how to
reroute traffic to an alternate pool of service instances.
<br><br>
The map is keyed by the service subset it applies to and the special
string \`"*"\` is a wildcard that applies to any subset not otherwise
specified here.
<br><br>
\`Service\`, \`ServiceSubset\`, \`Namespace\`, and \`Datacenters\` cannot all be
empty at once.`,
yaml: `Controls when and how to
reroute traffic to an alternate pool of service instances.
<br><br>
The map is keyed by the service subset it applies to and the special
string \`"*"\` is a wildcard that applies to any subset not otherwise
specified here.
<br><br>
\`service\`, \`serviceSubset\`, \`namespace\`, and \`datacenters\` cannot all be
empty at once.`,
},
children: [
{
name: 'Service',
type: 'string: ""',
description:
'The service to resolve instead of the default as the failover group of instances during failover.',
},
{
name: 'ServiceSubset',
type: 'string: ""',
description:
'The named subset of the requested service to resolve as the failover group of instances. If empty the default subset for the requested service is used.',
},
{
name: 'Namespace',
enterprise: true,
type: 'string: ""',
description:
'The namespace to resolve the requested service from to form the failover group of instances. If empty the current namespace is used.',
},
{
name: 'Datacenters',
type: 'array<string>',
description: 'A fixed list of datacenters to try during failover.',
},
],
},
{
name: 'LoadBalancer',
type: 'LoadBalancer',
description:
'Determines the load balancing policy and configuration for services issuing requests to this upstream. This option is available in Consul versions 1.9.0 and newer.',
children: [
{
name: 'Policy',
type: 'string: ""',
description:
'The load balancing policy used to select a host. One of: `random`, `round_robin`, `least_request`, `ring_hash`, `maglev`.',
},
{
name: 'RingHashConfig',
type: 'RingHashConfig',
description: 'Configuration for the `ring_hash` policy type.',
children: [
{
name: 'MinimumRingRize',
type: 'int: 1024',
description:
'Determines the minimum number of entries in the hash ring.',
},
{
name: 'MaximumRingRize',
type: 'int: 8192',
description:
'Determines the maximum number of entries in the hash ring.',
},
],
},
{
name: 'LeastRequestConfig',
type: 'LeastRequestConfig',
description: 'Configuration for the `least_request` policy type.',
children: [
{
name: 'ChoiceCount',
type: 'int: 2',
description:
'Determines the number of random healthy hosts from which to select the one with the least requests.',
},
],
},
{
name: 'HashPolicies',
type: 'array<HashPolicies>',
description: `List of hash policies to use for
hashing load balancing algorithms. Hash policies are evaluated individually
and combined such that identical lists result in the same hash.
If no hash policies are present, or none are successfully evaluated,
then a random backend host will be selected.`,
children: [
{
name: 'Field',
type: 'string: ""',
description: {
hcl:
'The attribute type to hash on. Must be one of `header`, `cookie`, or `query_parameter`. Cannot be specified along with `SourceAddress`.',
yaml:
'The attribute type to hash on. Must be one of `header`, `cookie`, or `query_parameter`. Cannot be specified along with `sourceAddress`.',
},
},
{
name: 'FieldValue',
type: 'string: ""',
description: {
hcl:
'The value to hash. ie. header name, cookie name, URL query parameter name. Cannot be specified along with `SourceAddress`.',
yaml:
'The value to hash. ie. header name, cookie name, URL query parameter name. Cannot be specified along with `sourceAddress`.',
},
},
{
name: 'CookieConfig',
type: 'CookieConfig',
description:
'Additional configuration for the "cookie" hash policy type. This is specified to have Envoy generate a cookie for a client on its first request.',
children: [
{
name: 'Session',
type: 'bool: false',
description: 'Generates a session cookie with no expiration.',
},
{
name: 'TTL',
type: 'duration: 0s',
description:
'TTL for generated cookies. Cannot be specified for session cookies.',
},
{
name: 'Path',
type: 'string: ""',
description: 'The path to set for the cookie.',
},
],
},
{
name: 'SourceIP',
type: 'bool: false',
description: {
hcl:
'Determines whether the hash should be of the source IP address rather than of a field and field value. Cannot be specified along with `Field` or `FieldValue`.',
yaml:
'Determines whether the hash should be of the source IP address rather than of a field and field value. Cannot be specified along with `field` or `fieldValue`.',
},
},
{
name: 'Terminal',
type: 'bool: false',
description:
'Will short circuit the computation of the hash when multiple hash policies are present. If a hash is computed when a Terminal policy is evaluated, then that hash will be used and subsequent hash policies will be ignored.',
},
],
},
],
},
]}
/>
## Service Subsets ## Service Subsets

522
website/content/docs/agent/config-entries/service-router.mdx
View File

@ -9,9 +9,10 @@ description: >-
# Service Router # Service Router
-> **1.6.0+:** This config entry is available in Consul versions 1.6.0 and newer. -> **v1.8.4+:** On Kubernetes, the `ServiceRouter` custom resource is supported in Consul versions 1.8.4+.<br />
**v1.6.0+:** On other platforms, this config entry is supported in Consul versions 1.6.0+.
The `service-router` config entry kind controls Connect traffic routing and The `service-router` config entry kind (`ServiceRouter` on Kubernetes) controls Connect traffic routing and
manipulation at networking layer 7 (e.g. HTTP). manipulation at networking layer 7 (e.g. HTTP).
If a router is not explicitly configured or is configured with no routes then If a router is not explicitly configured or is configured with no routes then
@ -38,6 +39,11 @@ service of the same name.
## Sample Config Entries ## Sample Config Entries
### Path prefix matching
<Tabs>
<Tab heading="HCL">
Route HTTP requests with a path starting with `/admin` to a different service: Route HTTP requests with a path starting with `/admin` to a different service:
```hcl ```hcl
@ -59,6 +65,34 @@ Routes = [
] ]
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Route HTTP requests with a path starting with `/admin` to a different service:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceRouter
metadata:
name: web
spec:
routes:
- match:
http:
pathPrefix: /admin
destination:
service: admin
# NOTE: a default catch-all will send unmatched traffic to "web"
```
</Tab>
</Tabs>
### Header/query parameter matching
<Tabs>
<Tab heading="HCL">
Route HTTP requests with a special url parameter or header to a canary subset: Route HTTP requests with a special url parameter or header to a canary subset:
```hcl ```hcl
@ -101,6 +135,45 @@ Routes = [
] ]
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Route HTTP requests with a special url parameter or header to a canary subset:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceRouter
metadata:
name: web
spec:
routes:
- match:
http:
header:
- name: x-debug
exact: '1'
destination:
service: web
serviceSubset: canary
- match:
http:
queryParam:
- name: x-debug
exact: '1'
destination:
service: web
serviceSubset: canary
# NOTE: a default catch-all will send unmatched traffic to "web"
```
</Tab>
</Tabs>
### gRPC routing
<Tabs>
<Tab heading="HCL">
Re-route a gRPC method to another service. Since gRPC method calls [are Re-route a gRPC method to another service. Since gRPC method calls [are
HTTP/2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can use an HTTP path match rule to re-route traffic: HTTP/2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can use an HTTP path match rule to re-route traffic:
@ -123,144 +196,325 @@ Routes = [
] ]
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Re-route a gRPC method to another service. Since gRPC method calls [are
HTTP/2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md), we can use an HTTP path match rule to re-route traffic:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceRouter
metadata:
name: billing
spec:
routes:
- match:
http:
pathExact: /mycompany.BillingService/GenerateInvoice
destination:
service: invoice-generator
# NOTE: a default catch-all will send unmatched traffic to "billing"
```
</Tab>
</Tabs>
## Available Fields ## Available Fields
- `Kind` - Must be set to `service-router` <ConfigEntryReference
keys={[
- `Name` `(string: <required>)` - Set to the name of the service being configured. {
name: 'apiVersion',
- `Namespace` `(string: "default")` <EnterpriseAlert inline /> - Specifies the namespace the config entry will apply to. description: 'Must be set to `consul.hashicorp.com/v1alpha1`',
hcl: false,
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4. },
{
- `Routes` `(array<ServiceRoute>)` - The list of routes to consider when name: 'Kind',
processing L7 requests. The first route to match in the list is terminal and description: {
stops further evaluation. Traffic that fails to match any of the provided hcl: 'Must be set to `service-router`',
routes will be routed to the default service. yaml: 'Must be set to `ServiceRouter`',
},
- `Match` `(ServiceRouteMatch: <optional>)` - A set of criteria that can },
match incoming L7 requests. If empty or omitted it acts as a catch-all. {
name: 'Name',
- `HTTP` `(ServiceRouteHTTPMatch: <optional>)` - A set of description: 'Set to the name of the service being configured.',
[HTTP-specific match criteria](#serviceroutehttpmatch). type: 'string: <required>',
yaml: false,
- `Destination` `(ServiceRouteDestination: <optional>)` - Controls [how to },
proxy](#serviceroutedestination) the matching request(s) to a {
service. name: 'Namespace',
type: `string: "default"`,
enterprise: true,
description: 'Specifies the namespace the config entry will apply to.',
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.',
},
],
hcl: false,
},
{
name: 'Routes',
type: 'array<ServiceRoute>',
description: `The list of routes to consider when
processing L7 requests. The first route to match in the list is terminal and
stops further evaluation. Traffic that fails to match any of the provided
routes will be routed to the default service.`,
children: [
{
name: 'Match',
type: 'ServiceRouteMatch: <optional>',
description: `A set of criteria that can
match incoming L7 requests. If empty or omitted it acts as a catch-all.`,
children: [
{
name: 'HTTP',
type: 'ServiceRouteHTTPMatch: <optional>',
description: `A set of [HTTP-specific match criteria](#serviceroutehttpmatch).`,
},
],
},
{
name: 'Destination',
type: 'ServiceRouteDestination: <optional>',
description: `Controls [how to proxy](#serviceroutedestination) the matching request(s) to a service.`,
},
],
},
]}
/>
### `ServiceRouteHTTPMatch` ### `ServiceRouteHTTPMatch`
- `PathExact` `(string: "")` - Exact path to match on the HTTP request path. <ConfigEntryReference
topLevel={false}
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured. keys={[
{
- `PathPrefix` `(string: "")` - Path prefix to match on the HTTP request path. name: 'PathExact',
type: 'string: ""',
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured. description: {
hcl:
- `PathRegex` `(string: "")` - Regular expression to match on the HTTP 'Exact path to match on the HTTP request path.<br><br> At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.',
request path. yaml:
'Exact path to match on the HTTP request path.<br><br> At most only one of `pathExact`, `pathPrefix`, or `pathRegex` may be configured.',
The syntax is [described below](#regular-expression-syntax). },
},
At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured. {
name: 'PathPrefix',
- `Methods` `(array<string>)` - A list of HTTP methods for which this match type: 'string: ""',
applies. If unspecified all HTTP methods are matched. description: {
If provided the names must be a valid [method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). hcl:
'Path prefix to match on the HTTP request path.<br><br> At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.',
- `Header` `(array<ServiceRouteHTTPMatchHeader>)` - A set of criteria that can yaml:
match on HTTP request headers. If more than one is configured all must match 'Path prefix to match on the HTTP request path.<br><br> At most only one of `pathExact`, `pathPrefix`, or `pathRegex` may be configured.',
for the overall match to apply. },
},
- `Name` `(string: <required>)` - Name of the header to match. {
name: 'PathRegex',
- `Present` `(bool: false)` - Match if the header with the given name is type: 'string: ""',
present with any value. description: {
hcl:
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` 'Regular expression to match on the HTTP request path.<br><br>The syntax is [described below](#regular-expression-syntax).<br><br> At most only one of `PathExact`, `PathPrefix`, or `PathRegex` may be configured.',
may be configured. yaml:
'Regular expression to match on the HTTP request path.<br><br>The syntax is [described below](#regular-expression-syntax).<br><br> At most only one of `pathExact`, `pathPrefix`, or `pathRegex` may be configured.',
- `Exact` `(string: "")` - Match if the header with the given name is this },
value. },
{
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` name: 'Methods',
may be configured. type: 'array<string>',
description:
- `Prefix` `(string: "")` - Match if the header with the given name has 'A list of HTTP methods for which this match applies. If unspecified all HTTP methods are matched. If provided the names must be a valid [method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods).',
this prefix. },
{
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` name: 'Header',
may be configured. type: 'array<ServiceRouteHTTPMatchHeader>)',
description:
- `Suffix` `(string: "")` - Match if the header with the given name has 'A set of criteria that can match on HTTP request headers. If more than one is configured all must match for the overall match to apply.',
this suffix. children: [
{
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` name: 'Name',
may be configured. type: 'string: <required>',
description: 'Name of the header to match.',
- `Regex` `(string: "")` - Match if the header with the given name matches },
this pattern. {
name: 'Present',
The syntax is [described below](#regular-expression-syntax). type: 'bool: false',
description: {
At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` hcl:
may be configured. 'Match if the header with the given name is present with any value.<br><br> At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` may be configured.',
yaml:
- `Invert` `(bool: false)` - Inverts the logic of the match. 'Match if the header with the given name is present with any value.<br><br> At most only one of `exact`, `prefix`, `suffix`, `regex`, or `present` may be configured.',
},
- `QueryParam` `(array<ServiceRouteHTTPMatchQueryParam>)` - A set of criteria },
that can match on HTTP query parameters. If more than one is configured all {
must match for the overall match to apply. name: 'Exact',
type: 'string: ""',
- `Name` `(string: <required>)` - The name of the query parameter to match on. description: {
hcl:
- `Present` `(bool: false)` - Match if the query parameter with the given 'Match if the header with the given name is this value.<br><br> At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` may be configured.',
name is present with any value. yaml:
'Match if the header with the given name is this value.<br><br> At most only one of `exact`, `prefix`, `suffix`, `regex`, or `present` may be configured.',
At most only one of `Exact`, `Regex`, or `Present` may be configured. },
},
- `Exact` `(string: "")` - Match if the query parameter with the given name {
is this value. name: 'Prefix',
type: 'string: ""',
At most only one of `Exact`, `Regex`, or `Present` may be configured. description: {
hcl:
- `Regex` `(string: "")` - Match if the query parameter with the given name 'Match if the header with the given name has this prefix.<br><br> At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` may be configured.',
matches this pattern. yaml:
'Match if the header with the given name has this prefix.<br><br> At most only one of `exact`, `prefix`, `suffix`, `regex`, or `present` may be configured.',
The syntax is [described below](#regular-expression-syntax). },
},
At most only one of `Exact`, `Regex`, or `Present` may be configured. {
name: 'Suffix',
type: 'string: ""',
description: {
hcl:
'Match if the header with the given name has this suffix.<br><br> At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` may be configured.',
yaml:
'Match if the header with the given name has this suffix.<br><br> At most only one of `exact`, `prefix`, `suffix`, `regex`, or `present` may be configured.',
},
},
{
name: 'Regex',
type: 'string: ""',
description: {
hcl:
'Match if the header with the given name matches this pattern.<br><br>The syntax is [described below](#regular-expression-syntax).<br><br> At most only one of `Exact`, `Prefix`, `Suffix`, `Regex`, or `Present` may be configured.',
yaml:
'Match if the header with the given name matches this pattern.<br><br>The syntax is [described below](#regular-expression-syntax).<br><br> At most only one of `exact`, `prefix`, `suffix`, `regex`, or `present` may be configured.',
},
},
{
name: 'Invert',
type: 'bool: false',
description: 'Inverts the logic of the match',
},
],
},
{
name: 'QueryParam',
type: 'array<ServiceRouteHTTPMatchQueryParam>)',
description:
'A set of criteria that can match on HTTP query parameters. If more than one is configured all must match for the overall match to apply.',
children: [
{
name: 'Name',
type: 'string: <required>',
description: 'The name of the query parameter to match on.',
},
{
name: 'Present',
type: 'bool: false',
description: {
hcl:
'Match if the query parameter with the given name is present with any value.<br><br>At most only one of `Exact`, `Regex`, or `Present` may be configured.',
yaml:
'Match if the query parameter with the given name is present with any value.<br><br>At most only one of `exact`, `regex`, or `present` may be configured.',
},
},
{
name: 'Exact',
type: 'string: ""',
description: {
hcl:
'Match if the query parameter with the given name is this value.<br><br>At most only one of `Exact`, `Regex`, or `Present` may be configured.',
yaml:
'Match if the query parameter with the given name is this value.<br><br>At most only one of `exact`, `regex`, or `present` may be configured.',
},
},
{
name: 'Regex',
type: 'string: ""',
description: {
hcl:
'Match if the query parameter with the given name matches this pattern.<br><br>The syntax is [described below](#regular-expression-syntax).<br><br>At most only one of `Exact`, `Regex`, or `Present` may be configured.',
yaml:
'Match if the query parameter with the given name matches this pattern.<br><br>The syntax is [described below](#regular-expression-syntax).<br><br>At most only one of `exact`, `regex`, or `present` may be configured.',
},
},
],
},
]}
/>
### `ServiceRouteDestination` ### `ServiceRouteDestination`
- `Service` `(string: "")` - The service to resolve instead of the default <ConfigEntryReference
service. If empty then the default service name is used. topLevel={false}
keys={[
- `ServiceSubset` `(string: "")` - A named subset of the given service to {
resolve instead of the one defined as that service's `DefaultSubset`. If empty, name: 'Service',
the default subset is used. type: 'string: ""',
description:
- `Namespace` `(string: "")` - The namespace to resolve the service from 'The service to resolve instead of the default service. If empty then the default service name is used.',
instead of the current namespace. If empty the current namespace is assumed. },
{
- `PrefixRewrite` `(string: "")` - Defines how to rewrite the HTTP request path name: 'ServiceSubset',
before proxying it to its final destination. type: 'string: ""',
description: {
This requires that either `Match.HTTP.PathPrefix` or hcl:
`Match.HTTP.PathExact` be configured on this route. "A named subset of the given service to resolve instead of the one defined as that service's `DefaultSubset`. If empty, the default subset is used.",
yaml:
- `RequestTimeout` `(duration: 0s)` - The total amount of time permitted for "A named subset of the given service to resolve instead of the one defined as that service's `defaultSubset`. If empty, the default subset is used.",
the entire downstream request (and retries) to be processed. },
},
- `NumRetries` `(int: 0)` - The number of times to retry the request when a {
retryable result occurs. name: 'Namespace',
type: 'string: ""',
- `RetryOnConnectFailure` `(bool: false)` - Allows for connection failure description:
errors to trigger a retry. 'The Consul namespace to resolve the service from instead of the current namespace. If empty the current namespace is assumed.',
enterprise: true,
- `RetryOnStatusCodes` `(array<int>)` - A list of HTTP response status codes },
that are eligible for retry. {
name: 'PrefixRewrite',
type: 'string: ""',
description: {
hcl:
'Defines how to rewrite the HTTP request path before proxying it to its final destination.<br><br> This requires that either `Match.HTTP.PathPrefix` or `Match.HTTP.PathExact` be configured on this route.',
yaml:
'Defines how to rewrite the HTTP request path before proxying it to its final destination.<br><br> This requires that either `match.http.pathPrefix` or `match.http.pathExact` be configured on this route.',
},
},
{
name: 'RequestTimeout',
type: 'duration: 0',
description:
'The total amount of time permitted for the entire downstream request (and retries) to be processed.',
},
{
name: 'NumRetries',
type: 'int: 0',
description:
'The number of times to retry the request when a retryable result occurs.',
},
{
name: 'RetryOnConnectFailure',
type: 'bool: false',
description: 'Allows for connection failure errors to trigger a retry.',
},
{
name: 'RetryOnStatusCodes',
type: 'array<int>',
description:
'A list of HTTP response status codes that are eligible for retry.',
},
]}
/>
## ACLs ## ACLs
@ -279,8 +533,8 @@ name in these fields:
The actual syntax of the regular expression fields described here is entirely The actual syntax of the regular expression fields described here is entirely
proxy-specific. proxy-specific.
When using [Envoy](/docs/connect/proxies/envoy) as a proxy, the syntax for When using [Envoy](/docs/connect/proxies/envoy) as a proxy (the only supported proxy in Kubernetes),
these fields is version specific: the syntax for these fields is version specific:
| Envoy Version | Syntax | | Envoy Version | Syntax |
| --------------- | ------------------------------------------------------------------- | | --------------- | ------------------------------------------------------------------- |

164
website/content/docs/agent/config-entries/service-splitter.mdx
View File

@ -11,9 +11,10 @@ description: >-
# Service Splitter # Service Splitter
-> **1.6.0+:** This config entry is available in Consul versions 1.6.0 and newer. -> **v1.8.4+:** On Kubernetes, the `ServiceSplitter` custom resource is supported in Consul versions 1.8.4+.<br />
**v1.6.0+:** On other platforms, this config entry is supported in Consul versions 1.6.0+.
The `service-splitter` config entry kind controls how to split incoming Connect 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 requests across different subsets of a single service (like during staged
canary rollouts), or perhaps across different services (like during a v2 canary rollouts), or perhaps across different services (like during a v2
rewrite or other type of codebase migration). rewrite or other type of codebase migration).
@ -41,6 +42,11 @@ resolution stage.
## Sample Config Entries ## Sample Config Entries
### Two subsets of same service
<Tabs>
<Tab heading="HCL">
Split traffic between two subsets of the same service: Split traffic between two subsets of the same service:
```hcl ```hcl
@ -58,6 +64,32 @@ Splits = [
] ]
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Split traffic between two subsets of the same service:
```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
<Tabs>
<Tab heading="HCL">
Split traffic between two services: Split traffic between two services:
```hcl ```hcl
@ -75,33 +107,111 @@ Splits = [
] ]
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Split traffic between two services:
```yaml
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: 10
service: web-rewrite
```
</Tab>
</Tabs>
## Available Fields ## Available Fields
- `Kind` - Must be set to `service-splitter` <ConfigEntryReference
keys={[
- `Name` `(string: <required>)` - Set to the name of the service being configured. {
name: 'apiVersion',
- `Namespace` `(string: "default")` <EnterpriseAlert inline /> - Specifies the namespace the config entry will apply to. description: 'Must be set to `consul.hashicorp.com/v1alpha1`',
hcl: false,
- `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 name: 'Kind',
set of service instances during a traffic split. The sum of weights across description: {
all splits must add up to 100. hcl: 'Must be set to `service-splitter`',
yaml: 'Must be set to `ServiceSplitter`',
- `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% {
name: 'Name',
- `Service` `(string: "")` - The service to resolve instead of the default. description: 'Set to the name of the service being configured.',
type: 'string: <required>',
- `ServiceSubset` `(string: "")` - A named subset of the given service to yaml: false,
resolve instead of one defined as that service's `DefaultSubset`. If empty },
the default subset is used. {
name: 'Namespace',
- `Namespace` `(string: "")` - The namespace to resolve the service from type: `string: "default"`,
instead of the current namespace. If empty the current namespace is enterprise: true,
assumed. description: 'Specifies the namespace the config entry will apply to.',
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.',
},
],
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 eight 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 assumed.',
},
],
},
]}
/>
## ACLs ## ACLs

303
website/content/docs/agent/config-entries/terminating-gateway.mdx
View File

@ -9,9 +9,10 @@ description: >-
# Terminating Gateway # Terminating Gateway
-> **1.8.0+:** This config entry is available in Consul versions 1.8.0 and newer. -> **v1.8.4+:** On Kubernetes, the `ServiceSplitter` custom resource is supported in Consul versions 1.8.4+.<br />
**v1.8.0+:** On other platforms, this config entry is supported in Consul versions 1.8.0+.
The `terminating-gateway` config entry kind you to configure terminating gateways The `terminating-gateway` config entry kind (`TerminatingGateway` on Kubernetes) allows you to configure terminating gateways
to proxy traffic from services in the Consul service mesh to services registered with Consul that do not have a to proxy traffic from services in the Consul service mesh to services registered with Consul that do not have a
[Connect service sidecar proxy](/docs/connect/proxies). The configuration is associated with the name of a gateway service [Connect service sidecar proxy](/docs/connect/proxies). The configuration is associated with the name of a gateway service
and will apply to all instances of the gateway with that name. and will apply to all instances of the gateway with that name.
@ -78,6 +79,37 @@ Services = [
] ]
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Link gateway named "us-west-gateway" with the billing service:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: TerminatingGateway
metadata:
name: us-west-gateway
spec:
services:
- name: billing
```
</Tab>
<Tab heading="Kubernetes YAML (Consul Enterprise)">
Link gateway named "us-west-gateway" in the default namespace with the billing service in the finance namespace:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: TerminatingGateway
metadata:
name: us-west-gateway
spec:
services:
- name: billing
namespace: finance
```
</Tab> </Tab>
<Tab heading="JSON"> <Tab heading="JSON">
@ -154,6 +186,40 @@ Services = [
] ]
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Link gateway named "us-west-gateway" with the billing service and specify a CA file for one-way TLS authentication:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: TerminatingGateway
metadata:
name: us-west-gateway
spec:
services:
- name: billing
caFile: /etc/certs/ca-chain.cert.pem
```
</Tab>
<Tab heading="Kubernetes YAML (Consul Enterprise)">
Link gateway named "us-west-gateway" in the default namespace with the billing service in the finance namespace,
and specify a CA file for one-way TLS authentication:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: TerminatingGateway
metadata:
name: us-west-gateway
spec:
services:
- name: billing
namespace: finance
caFile: /etc/certs/ca-chain.cert.pem
```
</Tab> </Tab>
<Tab heading="JSON"> <Tab heading="JSON">
@ -237,6 +303,44 @@ Services = [
] ]
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Link gateway named "us-west-gateway" with the payments service and specify a CA file, key file, and cert file for mutual TLS authentication:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: TerminatingGateway
metadata:
name: us-west-gateway
spec:
services:
- name: billing
caFile: /etc/certs/ca-chain.cert.pem
keyFile: /etc/certs/gateway.key.pem
certFile: /etc/certs/gateway.cert.pem
```
</Tab>
<Tab heading="Kubernetes YAML (Consul Enterprise)">
Link gateway named "us-west-gateway" in the default namespace with the payments service in the finance namespace.
Also specify a CA file, key file, and cert file for mutual TLS authentication:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: TerminatingGateway
metadata:
name: us-west-gateway
spec:
services:
- name: billing
namespace: finance
caFile: /etc/certs/ca-chain.cert.pem
keyFile: /etc/certs/gateway.key.pem
certFile: /etc/certs/gateway.cert.pem
```
</Tab> </Tab>
<Tab heading="JSON"> <Tab heading="JSON">
@ -336,6 +440,52 @@ Services = [
] ]
``` ```
</Tab>
<Tab heading="Kubernetes YAML">
Link gateway named "us-west-gateway" with all services in the datacenter, and configure default certificates for mutual TLS.
Also override the SNI and CA file used for connections to the billing service:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: TerminatingGateway
metadata:
name: us-west-gateway
spec:
services:
- name: '*'
caFile: /etc/common-certs/ca-chain.cert.pem
keyFile: /etc/common-certs/gateway.key.pem
certFile: /etc/common-certs/gateway.cert.pem
- name: billing
caFile: /etc/billing-ca/ca-chain.cert.pem
sni: billing.service.com
```
</Tab>
<Tab heading="Kubernetes YAML (Consul Enterprise)">
Link gateway named "us-west-gateway" in the default namespace with all services in the finance namespace,
and configure default certificates for mutual TLS. Also override the SNI and CA file used for connections to the billing service:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: TerminatingGateway
metadata:
name: us-west-gateway
spec:
services:
- name: '*'
namespace: finance
caFile: /etc/common-certs/ca-chain.cert.pem
keyFile: /etc/common-certs/gateway.key.pem
certFile: /etc/common-certs/gateway.cert.pem
- name: billing
namespace: finance
caFile: /etc/billing-ca/ca-chain.cert.pem
sni: billing.service.com
```
</Tab> </Tab>
<Tab heading="JSON"> <Tab heading="JSON">
@ -398,44 +548,117 @@ and configure default certificates for mutual TLS. Also override the SNI and CA
## Available Fields ## Available Fields
- `Kind` - Must be set to `terminating-gateway` <ConfigEntryReference
keys={[
- `Name` `(string: <required>)` - Set to the name of the gateway being configured. {
name: 'apiVersion',
- `Namespace` `(string: "default")` - <EnterpriseAlert inline /> Specifies the namespace description: 'Must be set to `consul.hashicorp.com/v1alpha1`',
the config entry will apply to. This must be the namespace the gateway is registered in. hcl: false,
If omitted, the namespace will be inherited from [the request](/api/config#ns) },
or will default to the `default` namespace. {
name: 'Kind',
- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4. description: {
hcl: 'Must be set to `terminating-gateway`',
- `Services` `(array<LinkedService>: <optional>)` - A list of services to link yaml: 'Must be set to `TerminatingGateway`',
with the gateway. The gateway will proxy traffic to these services. These linked services },
must be registered with Consul for the gateway to discover their addresses. They must also },
be registered in the same Consul datacenter as the terminating gateway. {
name: 'Name',
- `Name` `(string: "")` - The name of the service to link with the gateway. description: 'Set to the name of the gateway being configured.',
If the wildcard specifier, `*`, is provided, then ALL services within the namespace type: 'string: <required>',
will be linked with the gateway. yaml: false,
},
- `Namespace` `(string: "")` - <EnterpriseAlert inline /> The namespace of the service. {
If omitted, the namespace will be inherited from the config entry. name: 'Namespace',
type: `string: "default"`,
- `CAFile` `(string: "")` - A file path to a PEM-encoded certificate authority. enterprise: true,
The file must be present on the proxy's filesystem. description:
The certificate authority is used to verify the authenticity of the service linked with the gateway. 'Specifies the namespace the config entry will apply to. This must be the namespace the gateway is registered in.' +
It can be provided along with a CertFile and KeyFile for mutual TLS authentication, or on its own ' If omitted, the namespace will be inherited from [the request](/api/config#ns)' +
for one-way TLS authentication. If none is provided the gateway **will not** encrypt the traffic to the destination. ' or will default to the `default` namespace.',
yaml: false,
- `CertFile` `(string: "")` - A file path to a PEM-encoded certificate. },
The file must be present on the proxy's filesystem. {
The certificate is provided servers to verify the gateway's authenticity. It must be provided if a KeyFile was specified. name: 'Meta',
type: 'map<string|string>: nil',
- `KeyFile` `(string: "")` - A file path to a PEM-encoded private key. description:
The file must be present on the proxy's filesystem. 'Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.',
The key is used with the certificate to verify the gateway's authenticity. It must be provided along if a CertFile was specified. yaml: false,
},
- `SNI` `(string: "")` - An optional hostname or domain name to specify during the TLS handshake. {
name: 'metadata',
children: [
{
name: 'name',
description: 'Set to the name of the gateway being configured.',
},
],
hcl: false,
},
{
name: 'Services',
type: 'array<LinkedService>: <optional>',
description: `A list of services to link
with the gateway. The gateway will proxy traffic to these services. These linked services
must be registered with Consul for the gateway to discover their addresses. They must also
be registered in the same Consul datacenter as the terminating gateway.`,
children: [
{
name: 'Name',
type: 'string: ""',
description:
'The name of the service to link with the gateway. If the wildcard specifier, `*`, is provided, then ALL services within the namespace will be linked with the gateway.',
},
{
name: 'Namespace',
enterprise: true,
type: 'string: ""',
description:
'The namespace of the service. If omitted, the namespace will be inherited from the config entry.',
},
{
name: 'CAFile',
type: 'string: ""',
description: `A file path to a PEM-encoded certificate authority.
The file must be present on the proxy's filesystem.
The certificate authority is used to verify the authenticity of the service linked with the gateway.
It can be provided along with a CertFile and KeyFile for mutual TLS authentication, or on its own
for one-way TLS authentication. If none is provided the gateway <b>will not</b> encrypt the traffic to the destination.`,
},
{
name: 'CertFile',
type: 'string: ""',
description: {
hcl: `A file path to a PEM-encoded certificate.
The file must be present on the proxy's filesystem.
The certificate is provided servers to verify the gateway's authenticity. It must be provided if a \`KeyFile\` was specified.`,
yaml: `A file path to a PEM-encoded certificate.
The file must be present on the proxy's filesystem.
The certificate is provided servers to verify the gateway's authenticity. It must be provided if a \`keyFile\` was specified.`,
},
},
{
name: 'KeyFile',
type: 'string: ""',
description: {
hcl: `A file path to a PEM-encoded private key.
The file must be present on the proxy's filesystem.
The key is used with the certificate to verify the gateway's authenticity. It must be provided along if a \`CertFile\` was specified.`,
yaml: `A file path to a PEM-encoded private key.
The file must be present on the proxy's filesystem.
The key is used with the certificate to verify the gateway's authenticity. It must be provided along if a \`certFile\` was specified.`,
},
},
{
name: 'SNI',
type: 'string: ""',
description:
'An optional hostname or domain name to specify during the TLS handshake.',
},
],
},
]}
/>
## ACLs ## ACLs

336
website/content/docs/k8s/crds/index.mdx
View File

@ -10,7 +10,7 @@ description: >-
# Custom Resource Definitions # Custom Resource Definitions
-> This feature requires consul-helm >= 0.26.0, consul-k8s >= 0.20.0 and consul >= 1.8.4. -> This feature requires consul-helm >= 0.28.0, consul-k8s >= 0.22.0 and consul >= 1.8.4.
We support managing Consul [configuration entries](/docs/agent/config-entries) We support managing Consul [configuration entries](/docs/agent/config-entries)
via Kubernetes Custom Resources. Configuration entries are used to provide via Kubernetes Custom Resources. Configuration entries are used to provide
@ -18,29 +18,26 @@ cluster-wide defaults for the service mesh.
We currently support the follow configuration entry kinds: We currently support the follow configuration entry kinds:
- [`proxy-defaults`](/docs/agent/config-entries/proxy-defaults) - [`ProxyDefaults`](/docs/agent/config-entries/proxy-defaults)
- [`service-defaults`](/docs/agent/config-entries/service-defaults) - [`ServiceDefaults`](/docs/agent/config-entries/service-defaults)
- [`service-splitter`](/docs/agent/config-entries/service-splitter) - [`ServiceSplitter`](/docs/agent/config-entries/service-splitter)
- [`service-router`](/docs/agent/config-entries/service-router) - [`ServiceRouter`](/docs/agent/config-entries/service-router)
- [`service-resolver`](/docs/agent/config-entries/service-resolver) - [`ServiceResolver`](/docs/agent/config-entries/service-resolver)
- [`service-intentions`](/docs/agent/config-entries/service-intentions) (requires Consul >= 1.9.0) - [`ServiceIntentions`](/docs/agent/config-entries/service-intentions) (requires Consul >= 1.9.0)
- [`IngressGateway`](/docs/agent/config-entries/ingress-gateway)
The following kinds are **not** currently supported: - [`TerminatingGateway`](/docs/agent/config-entries/terminating-gateway)
- [`ingress-gateway`](/docs/agent/config-entries/ingress-gateway)
- [`terminating-gateway`](/docs/agent/config-entries/terminating-gateway)
## Installation ## Installation
Ensure you have version `0.26.0` of the helm chart: Ensure you have at least version `0.28.0` of the helm chart:
```shell-session ```shell-session
$ helm search repo hashicorp/consul $ helm search repo hashicorp/consul
NAME CHART VERSION APP VERSION DESCRIPTION NAME CHART VERSION APP VERSION DESCRIPTION
hashicorp/consul 0.26.0 1.8.5 Official HashiCorp Consul Chart hashicorp/consul 0.28.0 1.9.1 Official HashiCorp Consul Chart
``` ```
If you don't have `0.26.0`, you will need to update your helm repository cache: If you don't have `0.28.0`, you will need to update your helm repository cache:
```shell-session ```shell-session
$ helm repo update $ helm repo update
@ -55,8 +52,6 @@ and enable the controller that acts on them:
```yaml ```yaml
global: global:
name: consul name: consul
image: 'consul:1.9.0' # consul >= 1.8.4 must be used
imageK8S: 'hashicorp/consul-k8s:0.20.0'
controller: controller:
enabled: true enabled: true
@ -68,8 +63,6 @@ connectInject:
Note that: Note that:
1. `controller.enabled: true` installs the CRDs and enables the controller. 1. `controller.enabled: true` installs the CRDs and enables the controller.
1. `global.image` must be a Consul version `>= 1.8.4`, e.g. `consul:1.8.4` or `consul:1.9.0`.
1. `global.imageK8S` must be `>= 0.20.0`
1. Configuration entries are used to configure Consul service mesh so it's also 1. Configuration entries are used to configure Consul service mesh so it's also
expected that `connectInject` will be enabled. expected that `connectInject` will be enabled.
@ -102,7 +95,7 @@ EOF
servicedefaults.consul.hashicorp.com/foo created servicedefaults.consul.hashicorp.com/foo created
``` ```
See [Specifications](#specifications) for detailed schema documentation. See [Configuration Entries](/docs/agent/config-entries) for detailed schema documentation.
### Get ### Get
@ -180,306 +173,3 @@ to be deleted since that would put Consul into a broken state.
In order to delete the `ServiceDefaults` config, you would need to first delete In order to delete the `ServiceDefaults` config, you would need to first delete
the `ServiceSplitter`. the `ServiceSplitter`.
## Specifications
### ProxyDefaults
A [proxy-defaults](/docs/agent/config-entries/proxy-defaults)
entry configures global defaults across all proxies.
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ProxyDefaults
metadata:
name: global
spec:
config:
envoy_tracing_json: '{"http":{"config":{"collector_cluster":"jaeger_9411","collector_endpoint":"/api/v2/spans"},"name":"envoy.zipkin"}}'
expose:
checks: true
paths:
- listenerPort: 80
localPathPort: 42
path: /test/path
protocol: http
- listenerPort: 8080
localPathPort: 4201
path: /root/test/path
protocol: http2
meshGateway:
mode: local
```
Notes:
1. There can only be one `ProxyDefaults` resource and its name **must** be `global`.
1. Keys under `spec.config` will need to use `snake_case`, not `camelCase`, because
this config is passed directly to Envoy which uses `snake_case`, e.g.
```yaml
spec:
config:
envoy_statsd_url: 'udp://127.0.0.1:8125'
```
1. See [proxy-defaults](/docs/agent/config-entries/proxy-defaults) for full
documentation on this config entry.
### ServiceDefaults
A [service-defaults](/docs/agent/config-entries/service-defaults)
entry configures a specific service.
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
name: your-service-name
spec:
protocol: https
meshGateway:
mode: local
expose:
checks: true
paths:
- listenerPort: 80
path: /path
localPathPort: 9000
protocol: http
- listenerPort: 8080
path: /another-path
localPathPort: 9091
protocol: http2
externalSNI: external-sni
```
Notes:
1. The name of the service that this `ServiceDefaults` configures is set by
`metadata.name`.
1. See [service-defaults](/docs/agent/config-entries/service-defaults) for full
documentation on this config entry.
### ServiceIntentions
A [service-intentions](/docs/agent/config-entries/service-intentions)
entry configures traffic authorization for a destination service.
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceIntentions
metadata:
name: my-intention
spec:
destination:
name: your-service-name
sources:
- name: svc1
namespace: test
action: allow
permissions: []
description: allow access from svc1
- name: '*'
namespace: not-test
action: deny
permissions: []
description: disallow access from namespace not-test
- name: svc-2
namespace: bar
action: ''
permissions:
- action: allow
http:
pathExact: /foo
pathPrefix: /bar
pathRegex: /baz
header:
- name: header
present: true
exact: exact
prefix: prefix
suffix: suffix
regex: regex
invert: true
methods:
- GET
- PUT
description: an L7 config
```
Notes:
1. This resource is only supported in Consul 1.9.0.
1. **Unlike the other configuration entries**, the value of `metadata.name` does not
define which service the intention applies to.
Instead, the name of the service this intention
is configuring is set in `spec.destination.name`.
The `metadata.name` field can be set to any value,
however, we recommend setting it to the name of the destination service the
intention is configuring.
1. Wildcard intentions can be created by setting `spec.destination.name` to `*` and/or
`spec.sources[].name` to `*`. For example to create a `deny` intention that applies
to all services:
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceIntentions
metadata:
name: deny-all
spec:
destination:
name: *
sources:
- name: *
action: deny
```
1. See [service-intentions](/docs/agent/config-entries/service-intentions) for full
documentation on this config entry.
### ServiceResolver
A [service-resolver](/docs/agent/config-entries/service-resolver)
entry configures which service instances should satisfy Connect upstream discovery requests for a given service name.
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceResolver
metadata:
name: your-service-name
spec:
defaultSubset: default_subset
subsets:
subset1:
filter: filter1
onlyPassing: true
subset2:
filter: filter2
redirect:
service: redirect
serviceSubset: redirect_subset
namespace: redirect_namespace
datacenter: redirect_datacenter
failover:
failover1:
service: failover1
serviceSubset: failover_subset1
namespaces: failover_namespace1
datacenters:
- failover1_dc1
- failover1_dc2
failover2:
service: failover2
serviceSubset: failover_subset2
namespaces: failover_namespace2
datacenters:
- failover2_dc1
- failover2_dc2
connectTimeout: 1000000000
loadBalancer:
policy: policy
ringHashConfig:
minimumRingSize: 1
maximumRingSize: 2
leastRequestConfig:
choiceCount: 1
hashPolicies:
- field: field
fieldValue: value
cookieConfig:
session: true
ttl: 1
path: path
sourceIP: true
terminal: true
```
Notes:
1. The name of the service that this `ServiceResolver` configures is set by
`metadata.name`.
1. See [service-resolver](/docs/agent/config-entries/service-resolver) for full
documentation on this config entry.
### ServiceRouter
A [service-router](/docs/agent/config-entries/service-router)
entry configures traffic routing and manipulation at networking layer 7 (e.g. HTTP).
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceRouter
metadata:
name: your-service-name
spec:
routes:
- match:
http:
pathExact: pathExact
pathPrefix: pathPrefix
pathRegex: pathRegex
header:
- name: name
present: true
exact: exact
prefix: prefix
suffix: suffix
regex: regex
invert: true
queryParam:
- name: name
present: true
exact: exact
regex: regex
methods:
- method1
- method2
destination:
service: service
serviceSubset: serviceSubset
namespace: namespace
prefixRewrite: prefixRewrite
requestTimeout: 1000000000
numRetries: 1
retryOnConnectFailure: true
retryOnStatusCodes:
- 500
- 400
```
Notes:
1. The name of the service that this `ServiceRouter` configures is set by
`metadata.name`.
1. See [service-router](/docs/agent/config-entries/service-router) for full
documentation on this config entry.
### ServiceSplitter
A [service-splitter](/docs/agent/config-entries/service-splitter)
entry configures splitting incoming requests across different subsets of a single service.
```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceSplitter
metadata:
name: your-service-name
spec:
splits:
- weight: 25.5
service: foo
serviceSubset: v1
namespace: baz
- weight: 74.5
service: foo
serviceSubset: v2
namespace: baz
```
Notes:
1. The name of the service that this `ServiceSplitter` configures is set by
`metadata.name`.
1. See [service-splitter](/docs/agent/config-entries/service-splitter) for full
documentation on this config entry.

4
website/pages/docs/[[...page]].jsx
View File

@ -5,8 +5,10 @@ import {
generateStaticPaths, generateStaticPaths,
generateStaticProps, generateStaticProps,
} from '@hashicorp/react-docs-page/server' } from '@hashicorp/react-docs-page/server'
import ConfigEntryReference from 'components/config-entry-reference'
const subpath = 'docs' const subpath = 'docs'
const additionalComponents = {ConfigEntryReference}
export default function DocsLayout(props) { export default function DocsLayout(props) {
return ( return (
@ -15,6 +17,7 @@ export default function DocsLayout(props) {
subpath={subpath} subpath={subpath}
order={order} order={order}
staticProps={props} staticProps={props}
additionalComponents={additionalComponents}
/> />
) )
} }
@ -28,5 +31,6 @@ export async function getStaticProps({ params }) {
subpath, subpath,
productName, productName,
params, params,
additionalComponents
}) })
} }