Mesh Configuration Entry

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.

Kind = "mesh"
TLS {
  Incoming {
    TLSMinVersion = "TLSv1_2"
  }
}

apiVersion: consul.hashicorp.com/v1alpha1
kind: Mesh
metadata:
  name: mesh
spec:
  tls:
    incoming:
      tlsMinVersion: TLSv1_2

{
  "Kind": "mesh",
  "TLS": {
    "Incoming": {
      "TLSMinVersion": "TLSv1_2"
    }
  }
}

The mesh configuration entry can only be created in the default namespace and will apply to proxies across all namespaces.

Kind      = "mesh"
TLS {
  Incoming {
    TLSMinVersion = "TLSv1_2"
  }
}

apiVersion: consul.hashicorp.com/v1alpha1
kind: Mesh
metadata:
  name: mesh
  namespace: default
spec:
  tls:
    incoming:
      tlsMinVersion: TLSv1_2

{
  "Kind": "mesh",
  "Namespace": "default",
  "Partition": "default",
  "TLS": {
    "Incoming": {
      "TLSMinVersion": "TLSv1_2"
    }
  }
}

Note that the Kubernetes example does not include a partition field. Configuration entries are applied on Kubernetes using custom resource definitions (CRD), which can only be scoped to their own partition.

Mesh Destinations Only

Only allow transparent proxies to dial addresses in the mesh.

Kind = "mesh"
TransparentProxy {
  MeshDestinationsOnly = true
}

apiVersion: consul.hashicorp.com/v1alpha1
kind: Mesh
metadata:
  name: mesh
spec:
  transparentProxy:
    meshDestinationsOnly: true

{
  "Kind": "mesh",
  "TransparentProxy": {
    "MeshDestinationsOnly": true
  }
}

The mesh configuration entry can only be created in the default namespace and will apply to proxies across all namespaces.

Kind      = "mesh"
TransparentProxy {
  MeshDestinationsOnly = true
}

apiVersion: consul.hashicorp.com/v1alpha1
kind: Mesh
metadata:
  name: mesh
  namespace: default
spec:
  transparentProxy:
    meshDestinationsOnly: true

{
  "Kind": "mesh",
  "Namespace": "default",
  "Partition": "default",
  "TransparentProxy": {
    "MeshDestinationsOnly": true
  }
}

Note that the Kubernetes example does not include a partition field. Configuration entries are applied on Kubernetes using custom resource definitions (CRD), 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.

Kind = "mesh"
Peering {
  PeerThroughMeshGateways = true
}

apiVersion: consul.hashicorp.com/v1alpha1
kind: Mesh
metadata:
  name: mesh
spec:
  peering:
    peerThroughMeshGateways: true

{
  "Kind": "mesh",
  "Peering": {
    "PeerThroughMeshGateways": true
  }
}

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.

Kind = "mesh"
Peering {
  PeerThroughMeshGateways = true
}

apiVersion: consul.hashicorp.com/v1alpha1
kind: Mesh
metadata:
  name: mesh
  namespace: default
spec:
  peering:
    peerThroughMeshGateways: true

{
  "Kind": "mesh",
  "Peering": {
    "PeerThroughMeshGateways": true
  }
}

Note that the Kubernetes example does not include a partition field. Configuration entries are applied on Kubernetes using custom resource definitions (CRD), which can only be scoped to their own partition.

Available Fields

• Kind - Must be set to mesh

• Namespace (string: "default")Enterprise - Must be set to default. The configuration will apply to all namespaces.

• Partition (string: "default")Enterprise - Specifies the name of the admin partition in which the configuration entry applies. Refer to the Admin Partitions documentation for additional information.

• Meta (map<string|string>: nil) - Specifies arbitrary KV metadata pairs. Added in Consul 1.8.4.

• TransparentProxy (TransparentProxyConfig: <optional>) - Controls configuration specific to proxies in transparent mode. Added in v1.10.0.

  • MeshDestinationsOnly (bool: false) - 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 mesh-native services. If disabled, requests will be proxied as-is to the original destination IP address. Consul will not encrypt the connection.

• AllowEnablingPermissiveMutualTLS (bool: false) - Controls whether MutualTLSMode=permissive can be set in the proxy-defaults and service-defaults configuration entries.

• TLS (TLSConfig: <optional>) - TLS configuration for the service mesh.

  • Incoming (TLSDirectionConfig: <optional>) - TLS configuration for inbound mTLS connections targeting the public listener on connect-proxy and terminating-gateway proxy kinds.

    • TLSMinVersion (string: "") - 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, while older releases of Envoy default to TLS 1.0.

    • TLSMaxVersion (string: "") - 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.

    • CipherSuites (array<string>: <optional>) - 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. The list of supported cipher suites can seen in consul/types/tls.go 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.

  • Outgoing (TLSDirectionConfig: <optional>) - TLS configuration for outbound mTLS connections dialing upstreams from connect-proxy and ingress-gateway proxy kinds.

    • TLSMinVersion (string: "") - 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, while older releases of Envoy default to TLS 1.0.

    • TLSMaxVersion (string: "") - 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.

    • CipherSuites (array<string>: <optional>) - 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. The list of supported cipher suites can seen in consul/types/tls.go 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.

• HTTP (HTTPConfig: <optional>) - HTTP configuration for the service mesh.

  • SanitizeXForwardedClientCert (bool: <optional>) - 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.

• Peering (PeeringMeshConfig: <optional>) - Controls configuration specific to peering connections.

  • PeerThroughMeshGateways (bool: <optional>) - 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.

• apiVersion - Must be set to consul.hashicorp.com/v1alpha1

• kind - Must be set to Mesh

• metadata

  • name - Must be set to mesh

  • namespace Enterprise - Must be set to default. If running Consul Open Source, the namespace is ignored (see Kubernetes Namespaces in Consul OSS). If running Consul Enterprise see Kubernetes Namespaces in Consul Enterprise for additional information.

• spec

  • transparentProxy (TransparentProxyConfig: <optional>) - Controls configuration specific to proxies in transparent mode. Added in v1.10.0.

    • meshDestinationsOnly (bool: false) - 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 mesh-native services. If disabled, requests will be proxied as-is to the original destination IP address. Consul will not encrypt the connection.

  • allowEnablingPermissiveMutualTLS (bool: false) - Controls whether MutualTLSMode=permissive can be set in the proxy-defaults and service-defaults configuration entries.

  • tls (TLSConfig: <optional>) - TLS configuration for the service mesh.

    • incoming (TLSDirectionConfig: <optional>) - TLS configuration for inbound mTLS connections targeting the public listener on connect-proxy and terminating-gateway proxy kinds.

      • tlsMinVersion (string: "") - 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, while older releases of Envoy default to TLS 1.0.

      • tlsMaxVersion (string: "") - 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.

      • cipherSuites (array<string>: <optional>) - 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. The list of supported cipher suites can seen in consul/types/tls.go 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.

    • outgoing (TLSDirectionConfig: <optional>) - TLS configuration for outbound mTLS connections dialing upstreams from connect-proxy and ingress-gateway proxy kinds.

      • tlsMinVersion (string: "") - 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, while older releases of Envoy default to TLS 1.0.

      • tlsMaxVersion (string: "") - 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.

      • cipherSuites (array<string>: <optional>) - 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. The list of supported cipher suites can seen in consul/types/tls.go 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.

  • http (HTTPConfig: <optional>) - HTTP configuration for the service mesh.

    • sanitizeXForwardedClientCert (bool: <optional>) - 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.

  • peering (PeeringMeshConfig: <optional>) - Controls configuration specific to peering connections.

    • peerThroughMeshGateways (bool: <optional>) - 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.

Reading a mesh config entry requires no specific privileges.

Creating, updating, or deleting a mesh config entry requires operator:write.