mirror of https://github.com/hashicorp/consul
468 lines
14 KiB
Markdown
468 lines
14 KiB
Markdown
---
|
|
layout: docs
|
|
page_title: Mesh - Configuration Entry Reference
|
|
description: >-
|
|
The mesh configuration entry kind defines global default settings like TLS version requirements for proxies inside the service mesh. Use the reference guide to learn about `""mesh""` config entry parameters and how to control communication with services outside of the mesh.
|
|
---
|
|
|
|
# Mesh Configuration Entry
|
|
|
|
-> **v1.10.0+:** This configuration entry is supported in Consul versions 1.10.0+.
|
|
|
|
The `mesh` configuration entry allows you to define a global default configuration that applies to all service mesh proxies.
|
|
Settings in this config entry apply across all namespaces and federated datacenters.
|
|
|
|
## Sample Configuration Entries
|
|
|
|
### Mesh-wide TLS Min Version
|
|
|
|
Enforce that service mesh mTLS traffic uses TLS v1.2 or newer.
|
|
|
|
<Tabs>
|
|
<Tab heading="Consul OSS">
|
|
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "mesh"
|
|
TLS {
|
|
Incoming {
|
|
TLSMinVersion = "TLSv1_2"
|
|
}
|
|
}
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: Mesh
|
|
metadata:
|
|
name: mesh
|
|
spec:
|
|
tls:
|
|
incoming:
|
|
tlsMinVersion: TLSv1_2
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "mesh",
|
|
"TLS": {
|
|
"Incoming": {
|
|
"TLSMinVersion": "TLSv1_2"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
</Tab>
|
|
<Tab heading="Consul Enterprise">
|
|
|
|
The `mesh` configuration entry can only be created in the `default` namespace and will apply to proxies across **all** namespaces.
|
|
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "mesh"
|
|
|
|
TLS {
|
|
Incoming {
|
|
TLSMinVersion = "TLSv1_2"
|
|
}
|
|
}
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: Mesh
|
|
metadata:
|
|
name: mesh
|
|
namespace: default
|
|
spec:
|
|
tls:
|
|
incoming:
|
|
tlsMinVersion: TLSv1_2
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "mesh",
|
|
"Namespace": "default",
|
|
"Partition": "default",
|
|
"TLS": {
|
|
"Incoming": {
|
|
"TLSMinVersion": "TLSv1_2"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
Note that the Kubernetes example does not include a `partition` field. Configuration entries are applied on Kubernetes using [custom resource definitions (CRD)](/consul/docs/k8s/crds), which can only be scoped to their own partition.
|
|
|
|
### Mesh Destinations Only
|
|
|
|
Only allow transparent proxies to dial addresses in the mesh.
|
|
|
|
<Tabs>
|
|
<Tab heading="Consul OSS">
|
|
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "mesh"
|
|
TransparentProxy {
|
|
MeshDestinationsOnly = true
|
|
}
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: Mesh
|
|
metadata:
|
|
name: mesh
|
|
spec:
|
|
transparentProxy:
|
|
meshDestinationsOnly: true
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "mesh",
|
|
"TransparentProxy": {
|
|
"MeshDestinationsOnly": true
|
|
}
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
</Tab>
|
|
<Tab heading="Consul Enterprise">
|
|
|
|
The `mesh` configuration entry can only be created in the `default` namespace and will apply to proxies across **all** namespaces.
|
|
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "mesh"
|
|
|
|
TransparentProxy {
|
|
MeshDestinationsOnly = true
|
|
}
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: Mesh
|
|
metadata:
|
|
name: mesh
|
|
namespace: default
|
|
spec:
|
|
transparentProxy:
|
|
meshDestinationsOnly: true
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "mesh",
|
|
"Namespace": "default",
|
|
"Partition": "default",
|
|
"TransparentProxy": {
|
|
"MeshDestinationsOnly": true
|
|
}
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
Note that the Kubernetes example does not include a `partition` field. Configuration entries are applied on Kubernetes using [custom resource definitions (CRD)](/consul/docs/k8s/crds), which can only be scoped to their own partition.
|
|
|
|
### Peer Through Mesh Gateways
|
|
|
|
Set the `PeerThroughMeshGateways` parameter to `true` to route peering control plane traffic through mesh gateways.
|
|
|
|
<Tabs>
|
|
<Tab heading="Consul OSS">
|
|
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "mesh"
|
|
Peering {
|
|
PeerThroughMeshGateways = true
|
|
}
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: Mesh
|
|
metadata:
|
|
name: mesh
|
|
spec:
|
|
peering:
|
|
peerThroughMeshGateways: true
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "mesh",
|
|
"Peering": {
|
|
"PeerThroughMeshGateways": true
|
|
}
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
</Tab>
|
|
<Tab heading="Consul Enterprise">
|
|
|
|
You can only set the `PeerThroughMeshGateways` attribute on `mesh` configuration entries in the `default` partition.
|
|
The `default` partition owns the traffic routed through the mesh gateway control plane to Consul servers.
|
|
|
|
<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
|
|
|
|
```hcl
|
|
Kind = "mesh"
|
|
|
|
Peering {
|
|
PeerThroughMeshGateways = true
|
|
}
|
|
```
|
|
|
|
```yaml
|
|
apiVersion: consul.hashicorp.com/v1alpha1
|
|
kind: Mesh
|
|
metadata:
|
|
name: mesh
|
|
namespace: default
|
|
spec:
|
|
peering:
|
|
peerThroughMeshGateways: true
|
|
```
|
|
|
|
```json
|
|
{
|
|
"Kind": "mesh",
|
|
"Peering": {
|
|
"PeerThroughMeshGateways": true
|
|
}
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
Note that the Kubernetes example does not include a `partition` field. Configuration entries are applied on Kubernetes using [custom resource definitions (CRD)](/consul/docs/k8s/crds), which can only be scoped to their own partition.
|
|
|
|
|
|
## Available Fields
|
|
|
|
<ConfigEntryReference
|
|
keys={[
|
|
{
|
|
name: 'apiVersion',
|
|
description: 'Must be set to `consul.hashicorp.com/v1alpha1`',
|
|
hcl: false,
|
|
},
|
|
{
|
|
name: 'Kind',
|
|
description: {
|
|
hcl: 'Must be set to `mesh`',
|
|
yaml: 'Must be set to `Mesh`',
|
|
},
|
|
},
|
|
{
|
|
name: 'Namespace',
|
|
type: `string: "default"`,
|
|
enterprise: true,
|
|
description:
|
|
'Must be set to `default`. The configuration will apply to all namespaces.',
|
|
yaml: false,
|
|
},
|
|
{
|
|
name: 'Partition',
|
|
type: `string: "default"`,
|
|
enterprise: true,
|
|
description:
|
|
'Specifies the name of the admin partition in which the configuration entry applies. Refer to the [Admin Partitions documentation](/consul/docs/enterprise/admin-partitions) for additional information.',
|
|
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: 'Must be set to `mesh`',
|
|
},
|
|
{
|
|
name: 'namespace',
|
|
enterprise: true,
|
|
description:
|
|
'Must be set to `default`. If running Consul Open Source, the namespace is ignored (see [Kubernetes Namespaces in Consul OSS](/consul/docs/k8s/crds#consul-oss)). If running Consul Enterprise see [Kubernetes Namespaces in Consul Enterprise](/consul/docs/k8s/crds#consul-enterprise) for additional information.',
|
|
},
|
|
],
|
|
hcl: false,
|
|
},
|
|
{
|
|
name: 'TransparentProxy',
|
|
type: 'TransparentProxyConfig: <optional>',
|
|
description:
|
|
'Controls configuration specific to proxies in `transparent` [mode](/consul/docs/connect/config-entries/service-defaults#mode). Added in v1.10.0.',
|
|
children: [
|
|
{
|
|
name: 'MeshDestinationsOnly',
|
|
type: 'bool: false',
|
|
description: `Determines whether sidecar proxies operating in transparent mode can
|
|
proxy traffic to IP addresses not registered in Consul's mesh. If enabled, traffic will only be proxied
|
|
to upstream proxies or Connect-native services. If disabled, requests will be proxied as-is to the
|
|
original destination IP address. Consul will not encrypt the connection.`,
|
|
},
|
|
],
|
|
},
|
|
{
|
|
name: 'TLS',
|
|
type: 'TLSConfig: <optional>',
|
|
description: 'TLS configuration for the service mesh.',
|
|
children: [
|
|
{
|
|
name: 'Incoming',
|
|
type: 'TLSDirectionConfig: <optional>',
|
|
description: `TLS configuration for inbound mTLS connections targeting
|
|
the public listener on \`connect-proxy\` and \`terminating-gateway\`
|
|
proxy kinds.`,
|
|
children: [
|
|
{
|
|
name: 'TLSMinVersion',
|
|
type: 'string: ""',
|
|
description:
|
|
"Set the default minimum TLS version supported. One of `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`. If unspecified, Envoy v1.22.0 and newer [will default to TLS 1.2 as a min version](https://github.com/envoyproxy/envoy/pull/19330), while older releases of Envoy default to TLS 1.0.",
|
|
},
|
|
{
|
|
name: 'TLSMaxVersion',
|
|
type: 'string: ""',
|
|
description: {
|
|
hcl:
|
|
"Set the default maximum TLS version supported. Must be greater than or equal to `TLSMinVersion`. One of `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`. If unspecified, Envoy will default to TLS 1.3 as a max version for incoming connections.",
|
|
yaml:
|
|
"Set the default maximum TLS version supported. Must be greater than or equal to `tls_min_version`. One of `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`. If unspecified, Envoy will default to TLS 1.3 as a max version for incoming connections.",
|
|
},
|
|
},
|
|
{
|
|
name: 'CipherSuites',
|
|
type: 'array<string>: <optional>',
|
|
description: `Set the default list of TLS cipher suites
|
|
to support when negotiating connections using
|
|
TLS 1.2 or earlier. If unspecified, Envoy will use a
|
|
[default server cipher list](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites).
|
|
The list of supported cipher suites can seen in
|
|
[\`consul/types/tls.go\`](https://github.com/hashicorp/consul/blob/v1.11.2/types/tls.go#L154-L169)
|
|
and is dependent on underlying support in Envoy. Future
|
|
releases of Envoy may remove currently-supported but
|
|
insecure cipher suites, and future releases of Consul
|
|
may add new supported cipher suites if any are added to
|
|
Envoy.`,
|
|
},
|
|
],
|
|
},
|
|
{
|
|
name: 'Outgoing',
|
|
type: 'TLSDirectionConfig: <optional>',
|
|
description: `TLS configuration for outbound mTLS connections dialing upstreams
|
|
from \`connect-proxy\` and \`ingress-gateway\`
|
|
proxy kinds.`,
|
|
children: [
|
|
{
|
|
name: 'TLSMinVersion',
|
|
type: 'string: ""',
|
|
description:
|
|
"Set the default minimum TLS version supported. One of `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`. If unspecified, Envoy v1.22.0 and newer [will default to TLS 1.2 as a min version](https://github.com/envoyproxy/envoy/pull/19330), while older releases of Envoy default to TLS 1.0.",
|
|
},
|
|
{
|
|
name: 'TLSMaxVersion',
|
|
type: 'string: ""',
|
|
description: {
|
|
hcl:
|
|
"Set the default maximum TLS version supported. Must be greater than or equal to `TLSMinVersion`. One of `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`. If unspecified, Envoy will default to TLS 1.2 as a max version for outgoing connections, but future Envoy releases [may change this to TLS 1.3](https://github.com/envoyproxy/envoy/issues/9300).",
|
|
yaml:
|
|
"Set the default maximum TLS version supported. Must be greater than or equal to `tls_min_version`. One of `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, or `TLSv1_3`. If unspecified, Envoy will default to TLS 1.2 as a max version for outgoing connections, but future Envoy releases [may change this to TLS 1.3](https://github.com/envoyproxy/envoy/issues/9300).",
|
|
},
|
|
},
|
|
{
|
|
name: 'CipherSuites',
|
|
type: 'array<string>: <optional>',
|
|
description: `Set the default list of TLS cipher suites
|
|
to support when negotiating connections using
|
|
TLS 1.2 or earlier. If unspecified, Envoy will use a
|
|
[default server cipher list](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites).
|
|
The list of supported cipher suites can seen in
|
|
[\`consul/types/tls.go\`](https://github.com/hashicorp/consul/blob/v1.11.2/types/tls.go#L154-L169)
|
|
and is dependent on underlying support in Envoy. Future
|
|
releases of Envoy may remove currently-supported but
|
|
insecure cipher suites, and future releases of Consul
|
|
may add new supported cipher suites if any are added to
|
|
Envoy.`,
|
|
},
|
|
],
|
|
},
|
|
],
|
|
},
|
|
{
|
|
name: 'HTTP',
|
|
type: 'HTTPConfig: <optional>',
|
|
description: 'HTTP configuration for the service mesh.',
|
|
children: [
|
|
{
|
|
name: 'SanitizeXForwardedClientCert',
|
|
type: 'bool: <optional>',
|
|
description: `If configured to \`true\`, the \`forward_client_cert_details\` option will be set to \`SANITIZE\`
|
|
for all Envoy proxies. As a result, Consul will not include the \`x-forwarded-client-cert\` header in the next hop.
|
|
If set to \`false\` (default), the XFCC header is propagated to upstream applications.`,
|
|
},
|
|
],
|
|
},
|
|
{
|
|
name: 'Peering',
|
|
type: 'PeeringMeshConfig: <optional>',
|
|
description:
|
|
'Controls configuration specific to [peering connections](/consul/docs/connect/cluster-peering).',
|
|
children: [
|
|
{
|
|
name: 'PeerThroughMeshGateways',
|
|
type: 'bool: <optional>',
|
|
description: `Determines if peering control-plane traffic should be routed through mesh gateways.
|
|
When enabled, dialing cluster attempt to contact peers through their mesh gateway.
|
|
Clusters that accept calls advertise the address of their mesh gateways, rather than the address of their Consul servers.`,
|
|
},
|
|
],
|
|
},
|
|
]}
|
|
/>
|
|
|
|
## ACLs
|
|
|
|
Configuration entries may be protected by [ACLs](/consul/docs/security/acl).
|
|
|
|
Reading a `mesh` config entry requires no specific privileges.
|
|
|
|
Creating, updating, or deleting a `mesh` config entry requires
|
|
`operator:write`.
|