Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: Reference doc updates for permissive mTLS settings #17371

Merged
merged 5 commits into from
Jun 12, 2023
Merged

docs: Reference doc updates for permissive mTLS settings #17371

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1602c99
docs: Reference doc updates for permissive mTLS settings
May 15, 2023
132c6ee
Document config entry filtering
May 15, 2023
5e64b93
Apply suggestions from code review
Jun 9, 2023
efa997c
Merge branch 'main' into docs/pglass/NET-3690/pmtls-docs
Jun 9, 2023
83a7b3f
Fix doc errors
Jun 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions website/content/api-docs/config.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
10 changes: 10 additions & 0 deletions website/content/commands/config/list.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

6 changes: 6 additions & 0 deletions website/content/docs/connect/config-entries/mesh.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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` config entries. Added in v1.16.0.'
pglass marked this conversation as resolved.
Show resolved Hide resolved
},
{
name: 'TLS',
type: 'TLSConfig: <optional>',
Expand Down
17 changes: 17 additions & 0 deletions website/content/docs/connect/config-entries/proxy-defaults.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>"
}
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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>,
Expand Down Expand Up @@ -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>"
}
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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>"
},
Expand Down Expand Up @@ -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. Added in v1.16.0.`,
pglass marked this conversation as resolved.
Show resolved Hide resolved
},
{
name: 'MeshGateway',
type: 'MeshGatewayConfig: <optional>',
Expand Down
37 changes: 35 additions & 2 deletions website/content/docs/connect/config-entries/service-defaults.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice catch!


<Tabs>
<Tab heading="HCL and JSON" group="hcl">
Expand Down Expand Up @@ -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 | `""`
Expand Down Expand Up @@ -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 | `""`
Expand All @@ -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">
Expand Down Expand Up @@ -213,6 +215,7 @@ TransparentProxy = {
OutboundListenerPort = 15002
DialedDirectly = true
}
MutualTLSMode = "strict"
Destination = {
Addresses = [
"First IP address",
Expand Down Expand Up @@ -288,6 +291,7 @@ spec:
transparentProxy:
outboundListenerPort: 15001
dialedDirectly: false
mutualTLSMode: strict
destination:
addresses:
- <First hostname or IP address>
Expand Down Expand Up @@ -370,6 +374,7 @@ spec:
"outboundListenerPort": 15001,
"dialedDirectly": false
},
"mutualTLSMode": "strict",
"destination": {
"addresses": [
"<First hostname or IP address>",
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down