Backport of docs: Reference doc updates for permissive mTLS settings …

…into release/1.16.x (#17652) * backport of commit 1602c99 * backport of commit 132c6ee * backport of commit 5e64b93 * backport of commit 83a7b3f --------- Co-authored-by: Paul Glass <[email protected]>
hashicorp · Jun 12, 2023 · cb1e18c · cb1e18c
1 parent 96213b6
commit cb1e18c
Show file tree

Hide file tree

Showing 7 changed files with 83 additions and 16 deletions.
diff --git a/website/content/api-docs/config.mdx b/website/content/api-docs/config.mdx
@@ -215,6 +215,7 @@ The corresponding CLI command is [`consul config list`](/consul/commands/config/
 ### Path Parameters
 
 - `kind` `(string: <required>)` - Specifies the kind of the entry to list.
+- `filter` `(string: "")` - Specifies an expression to use for filtering the results.
 
 ### Query Parameters
 

diff --git a/website/content/commands/config/list.mdx b/website/content/commands/config/list.mdx
@@ -44,6 +44,7 @@ Usage: `consul config list [options]`
 #### Command Options
 
 - `-kind` - Specifies the kind of the config entry to list.
+- `-filter` - Specifies an expression to use for filtering the results.
 
 #### Enterprise Options
 
@@ -57,7 +58,16 @@ Usage: `consul config list [options]`
 
 ## Examples
 
+To list all service-defaults config entries:
+
     $ consul config list -kind service-defaults
     billing
     db
     web
+
+The following lists service-defaults with a filter expression:
+
+    $ consul config list -kind service-defaults -filter 'MutualTLSMode == "permissive"'
+    db
+    web
+
diff --git a/website/content/docs/connect/config-entries/mesh.mdx b/website/content/docs/connect/config-entries/mesh.mdx
@@ -338,6 +338,12 @@ Note that the Kubernetes example does not include a `partition` field. Configura
         },
       ],
     },
+    {
+      name: 'AllowEnablingPermissiveMutualTLS',
+      type: 'bool: false',
+      description:
+        'Controls whether `MutualTLSMode=permissive` can be set in the `proxy-defaults` and `service-defaults` configuration entries. '
+    },
     {
       name: 'TLS',
       type: 'TLSConfig: <optional>',

diff --git a/website/content/docs/connect/config-entries/proxy-defaults.mdx b/website/content/docs/connect/config-entries/proxy-defaults.mdx
@@ -53,6 +53,7 @@ TransparentProxy {
   OutboundListenerPort = <port the proxy should listen on for outbound traffic>
   DialedDirectly       = <true if proxy instances should be dialed directly>
 }
+MutualTLSMode = "<mutual TLS mode for all proxies>"
 MeshGateway {
   Mode = "<name of mesh gateway configuration for all proxies>"
 }
@@ -92,6 +93,7 @@ spec:
   transparentProxy:
     outboundListenerPort: <port the proxy should listen on for outbound traffic>
     dialedDirectly: <true if proxy instances should be dialed directly>
+  mutualTLSMode: <mutual TLS mode for all proxies>
   meshGateway:
     mode: <name of mesh gateway configuration for all proxies>
   expose:
@@ -120,6 +122,7 @@ spec:
   "Config": {
     "<arbitrary string key>": <arbitrary value>
   },
+  "MutualTLSMode": "<mutual TLS mode for all proxies>",
   "Mode": "<name of proxy mode>",
   "TransparentProxy": {
     "OutboundListenerPort": <port the proxy should listen on for outbound traffic>,
@@ -175,6 +178,7 @@ TransparentProxy {
   OutboundListenerPort = <port the proxy should listen on for outbound traffic>
   DialedDirectly       = <true if proxy instances should be dialed directly>
 }
+MutualTLSMode = "<mutual TLS mode for all proxies>"
 MeshGateway {
   Mode = "<name of mesh gateway configuration for all proxies>"
 }
@@ -215,6 +219,7 @@ spec:
   transparentProxy:
     outboundListenerPort: <port the proxy should listen on for outbound traffic>
     dialedDirectly: <true if proxy instances should be dialed directly>
+  mutualTLSMode: <mutual TLS mode for all proxies>
   meshGateway:
     mode: <name of mesh gateway configuration for all proxies>
   expose:
@@ -249,6 +254,7 @@ spec:
     "OutboundListenerPort": <port the proxy should listen on for outbound traffic>,
     "DialedDirectly": <true if proxy instances should be dialed directly>
   },
+  "MutualTLSMode": "<mutual TLS mode for all proxies>",
   "MeshGateway": {
     "Mode": = "<name of mesh gateway configuration for all proxies>"
   },
@@ -405,6 +411,17 @@ spec:
         },
       ],
     },
+    {
+      name: 'MutualTLSMode',
+      type: 'string: ""',
+      description: `Controls the default mutual TLS mode for all proxies. This setting is only
+                    supported for services with transparent proxy enabled. One of \`""\`, \`strict\`, or \`permissive\`.
+                    When unset or \`""\`, the mode defaults to \`strict\`. When set to \`strict\`, the sidecar proxy
+                    requires mutual TLS for incoming traffic. When set to \`permissive\`, the sidecar proxy accepts
+                    mutual TLS traffic on the sidecar proxy service port and accepts any traffic on the destination
+                    service port. We recommend only using \`permissive\` mode if necessary while onboarding services to
+                    the service mesh. `,
+    },
     {
       name: 'MeshGateway',
       type: 'MeshGatewayConfig: <optional>',

diff --git a/website/content/docs/connect/config-entries/service-defaults.mdx b/website/content/docs/connect/config-entries/service-defaults.mdx
@@ -10,7 +10,7 @@ This topic describes how to configure service defaults configuration entries. Th
 
 ## Configuration model
 
-The following outline shows how to format the service splitter configuration entry. Click on a property name to view details about the configuration.
+The following outline shows how to format the service defaults configuration entry. Click on a property name to view details about the configuration.
 
 <Tabs>
 <Tab heading="HCL and JSON" group="hcl">
@@ -58,6 +58,7 @@ The following outline shows how to format the service splitter configuration ent
 - [`TransparentProxy`](#transparentproxy): map | no default
   - [`OutboundListenerPort`](#transparentproxy): integer | `15001`
   - [`DialedDirectly`](#transparentproxy  ): boolean | `false`
+- [`MutualTLSMode`](#mutualtlsmode): string | `""`
 - [`EnvoyExtensions`](#envoyextensions): list | no default
   - [`Name`](#envoyextensions): string | `""`
   - [`Required`](#envoyextensions): string | `""`
@@ -126,6 +127,7 @@ The following outline shows how to format the service splitter configuration ent
   - [`transparentProxy`](#transparentproxy): map | no default
     - [`outboundListenerPort`](#transparentproxy): integer | `15001`
     - [`dialedDirectly`](#transparentproxy): boolean | `false`
+  - [`mutualTLSMode`](#mutualtlsmode): string | `""`
   - [`envoyExtensions`](#envoyextensions): list | no default
     - [`name`](#envoyextensions): string | `""`
     - [`required`](#envoyextensions): string | `""`
@@ -152,7 +154,7 @@ The following outline shows how to format the service splitter configuration ent
 
 ## Complete configuration
 
-When every field is defined, a service splitter configuration entry has the following form: 
+When every field is defined, a service-defaults configuration entry has the following form:
 
 <Tabs>
 <Tab heading="HCL" group="hcl">
@@ -213,6 +215,7 @@ TransparentProxy = {
   OutboundListenerPort = 15002
   DialedDirectly       = true
 }
+MutualTLSMode = "strict"
 Destination = {
   Addresses = [
     "First IP address",
@@ -288,6 +291,7 @@ spec:
   transparentProxy:
     outboundListenerPort: 15001
     dialedDirectly: false
+  mutualTLSMode: strict
   destination:
     addresses:
     - <First hostname or IP address>
@@ -370,6 +374,7 @@ spec:
       "outboundListenerPort": 15001,
       "dialedDirectly": false
     },
+    "mutualTLSMode": "strict",
     "destination": {
       "addresses": [
         "<First hostname or IP address>",
@@ -697,6 +702,19 @@ You can configure the following parameters in the `TransparentProxy` block:
 | `OutboundListenerPort` | Specifies the port that the proxy listens on for outbound traffic. This must be the same port number where outbound application traffic is redirected. | integer | `15001` |
 | `DialedDirectly` | Enables transparent proxies to dial the proxy instance's IP address directly when set to `true`. Transparent proxies commonly dial upstreams at the `"virtual"` tagged address, which load balances across instances. Dialing individual instances can be helpful for stateful services, such as a database cluster with a leader. | boolean | `false` |
 
+### `MutualTLSMode`
+
+Controls whether mutual TLS is required for incoming connections to this service. This setting is
+only supported for services with transparent proxy enabled. We recommend only using `permissive`
+mode if necessary while onboarding services to the service mesh.
+
+You can specify the following string values for the `MutualTLSMode` field:
+
+- `""`: When this field is empty, the value is inherited from the `proxy-defaults` config entry.
+- `strict`: The sidecar proxy requires mutual TLS for incoming traffic.
+- `permissive`: The sidecar proxy accepts mutual TLS traffic on the sidecar proxy service port,
+  and accepts any traffic on the destination service's port.
+
 ### `EnvoyExtensions`
 
 List of extensions to modify Envoy proxy configuration. Refer to [Envoy Extensions](/consul/docs/connect/proxies/envoy-extensions) for additional information.  
@@ -1089,6 +1107,21 @@ You can configure the following parameters in the `TransparentProxy` block:
 | `outboundListenerPort` | Specifies the port that the proxy listens on for outbound traffic. This must be the same port number where outbound application traffic is redirected. | integer | `15001` |
 | `dialedDirectly` | Enables transparent proxies to dial the proxy instance's IP address directly when set to `true`. Transparent proxies commonly dial upstreams at the `"virtual"` tagged address, which load balances across instances. Dialing individual instances can be helpful for stateful services, such as a database cluster with a leader. | boolean | `false` |
 
+### `spec.mutualTLSMode`
+
+Controls whether mutual TLS is required for incoming connections to this service. This setting is
+only supported for services with transparent proxy enabled. We recommend only using `permissive`
+mode if necessary while onboarding services to the service mesh.
+
+#### Values
+
+You can specify the following string values for the `MutualTLSMode` field:
+
+- `""`: When this field is empty, the value is inherited from the `proxy-defaults` config entry.
+- `strict`: The sidecar proxy requires mutual TLS for incoming traffic.
+- `permissive`: The sidecar proxy accepts mutual TLS traffic on the sidecar proxy service port,
+  and accepts any traffic on the destination service's port.
+
 ### `spec.envoyExtensions`
 
 List of extensions to modify Envoy proxy configuration. Refer to [Envoy Extensions](/consul/docs/connect/proxies/envoy-extensions) for additional information.

diff --git a/website/content/docs/release-notes/consul/v1_13_x.mdx b/website/content/docs/release-notes/consul/v1_13_x.mdx
@@ -15,7 +15,7 @@ description: >-
 
 - **Enables TLS on the Envoy Prometheus endpoint**: The Envoy prometheus endpoint can be enabled when `envoy_prometheus_bind_addr` is set and then secured over TLS using new CLI flags for the `consul connect envoy` command. These commands are: `-prometheus-ca-file`, `-prometheus-ca-path`, `-prometheus-cert-file` and `-prometheus-key-file`. The CA, cert, and key can be provided to Envoy by a Kubernetes mounted volume so that Envoy can watch the files and dynamically reload the certs when the volume is updated.
 
-- **UDP Health Checks**: Adds the ability to register service discovery health checks that periodically send UDP datagrams to the specified IP/hostname and port. Refer to [UDP checks](/consul/docs//services/usage/checks#udp-checks).
+- **UDP Health Checks**: Adds the ability to register service discovery health checks that periodically send UDP datagrams to the specified IP/hostname and port. Refer to [UDP checks](/consul/docs/services/usage/checks#udp-checks).
 
 ## What's Changed
 
@@ -46,4 +46,4 @@ The changelogs for this major release version and any maintenance versions are l
 - [1.13.3](https://github.com/hashicorp/consul/releases/tag/v1.13.3)
 - [1.13.4](https://github.com/hashicorp/consul/releases/tag/v1.13.4)
 - [1.13.5](https://github.com/hashicorp/consul/releases/tag/v1.13.5)
-- [1.13.6](https://github.com/hashicorp/consul/releases/tag/v1.13.6)
+- [1.13.6](https://github.com/hashicorp/consul/releases/tag/v1.13.6)
diff --git a/website/content/docs/services/discovery/dns-configuration.mdx b/website/content/docs/services/discovery/dns-configuration.mdx
@@ -1,7 +1,7 @@
 ---
 layout: docs
-page_title: Configure Consul DNS behavior 
-description: -> 
+page_title: Configure Consul DNS behavior
+description: ->
     Learn how to modify the default DNS behavior so that services and nodes can easily discover other services and nodes in your network.
 ---
 
@@ -12,37 +12,37 @@ This topic describes the default behavior of the Consul DNS functionality and ho
 ## Introduction
 The Consul DNS is the primary interface for querying records when Consul service mesh is disabled and your network runs in a non-Kubernetes environment. The DNS enables you to look up services and nodes registered with Consul using terminal commands instead of making HTTP API requests to Consul. Refer to the [Discover Consul Nodes and Services Overview](/consul/docs/services/discovery/dns-overview) for additional information.
 
-## Configure DNS behaviors 
+## Configure DNS behaviors
 By default, the Consul DNS listens for queries at `127.0.0.1:8600` and uses the `consul` domain. Specify the following parameters in the agent configuration to determine DNS behavior when querying services:
 
 - [`client_addr`](/consul/docs/agent/config/config-files#client_addr)
 - [`ports.dns`](/consul/docs/agent/config/config-files#dns_port)
 - [`recursors`](/consul/docs/agent/config/config-files#recursors)
-- [`domain`](/consul/docs/agent/config/config-files#domain) 
+- [`domain`](/consul/docs/agent/config/config-files#domain)
 - [`alt_domain`](/consul/docs/agent/config/config-files#alt_domain)
-- [`dns_config`](/consul/docs/agent/config/config-files#dns_config) 
+- [`dns_config`](/consul/docs/agent/config/config-files#dns_config)
 
 ### Configure WAN address translation
 By default, Consul DNS queries return a node's local address, even when being queried from a remote datacenter. You can configure the DNS to reach a node from outside its datacenter by specifying the address in the following configuration fields in the Consul agent:
 
-- [advertise-wan](/consul/docs/agent/config/cli-flags#_advertise-wan) 
-- [translate_wan_addrs](/consul//docs/agent/config/config-files#translate_wan_addrs) 
+- [advertise-wan](/consul/docs/agent/config/cli-flags#_advertise-wan)
+- [translate_wan_addrs](/consul/docs/agent/config/config-files#translate_wan_addrs)
 
 ### Use a custom DNS resolver library
 You can specify a list of addresses in the agent's [`recursors`](/consul/docs/agent/config/config-files#recursors) field to provide upstream DNS servers that recursively resolve queries that are outside the service domain for Consul.
- 
-Nodes that query records outside the `consul.` domain resolve to an upstream DNS. You can specify IP addresses or use `go-sockaddr` templates. Consul resolves IP addresses in the specified order and ignores duplicates. 
+
+Nodes that query records outside the `consul.` domain resolve to an upstream DNS. You can specify IP addresses or use `go-sockaddr` templates. Consul resolves IP addresses in the specified order and ignores duplicates.
 
 ### Enable non-Consul queries
-You enable non-Consul queries to be resolved by setting Consul as the DNS server for a node and providing a [`recursors`](/consul/docs/agent/config/config-files#recursors) configuration. 
+You enable non-Consul queries to be resolved by setting Consul as the DNS server for a node and providing a [`recursors`](/consul/docs/agent/config/config-files#recursors) configuration.
 
 ### Forward queries to an agent
 You can forward all queries sent to the `consul.` domain from the existing DNS server to a Consul agent. Refer to [Forward DNS for Consul Service Discovery](/consul/tutorials/networking/dns-forwarding) for instructions.
 
 ### Query an alternate domain
 By default, Consul responds to DNS queries in the `consul` domain, but you can set a specific domain for responding to DNS queries by configuring the [`domain`](/consul/docs/agent/config/config-files#domain) parameter.
 
-You can also specify an additional domain in the [`alt_domain`](/consul/docs/agent/config/config-files#alt_domain) agent configuration option, which configures Consul to respond to queries in a secondary domain. Configuring an alternate domain may be useful during a DNS migration or to distinguish between internal and external queries, for example. 
+You can also specify an additional domain in the [`alt_domain`](/consul/docs/agent/config/config-files#alt_domain) agent configuration option, which configures Consul to respond to queries in a secondary domain. Configuring an alternate domain may be useful during a DNS migration or to distinguish between internal and external queries, for example.
 
 Consul's DNS response uses the same domain as the query.
 
@@ -62,7 +62,7 @@ machine.node.dc1.test-domain. 0 IN  A 127.0.0.1
 machine.node.dc1.test-domain. 0 IN  TXT "consul-network-segment="
 ```
 #### PTR queries
-Responses to pointer record (PTR) queries, such as `<ip>.in-addr.arpa.`, always use the [primary domain](/consul/docs/agent/config/config-files#domain) and not the alternative domain. 
+Responses to pointer record (PTR) queries, such as `<ip>.in-addr.arpa.`, always use the [primary domain](/consul/docs/agent/config/config-files#domain) and not the alternative domain.
 
 ### Caching
 By default, DNS results served by Consul are not cached. Refer to the [DNS Caching tutorial](/consul/tutorials/networking/dns-caching) for instructions on how to enable caching.