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

docs(kuma-cp) permissive mTLS mode #510

Merged
merged 3 commits into from
Aug 25, 2021
Merged

docs(kuma-cp) permissive mTLS mode #510

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a85e268
docs(kuma-cp) permissive mTLS mode
lobkovilya Aug 23, 2021
7b720ff
Update docs/docs/1.2.3/policies/mutual-tls.md
lobkovilya Aug 25, 2021
4e4f416
docs(kuma-cp) warning
lobkovilya Aug 25, 2021
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
45 changes: 45 additions & 0 deletions docs/docs/1.2.3/policies/mutual-tls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,6 +187,51 @@ A few considerations:
* The `dpCert` configuration determines how often Kuma should automatically rotate the certificates assigned to every data plane proxy.
* The Secrets must exist before referencing them in a `provided` backend.

## Permissive mTLS

Kuma provides a convenient way to migrate existing workloads to the mTLS mesh with zero downtime. In order to do so
`PERMISSIVE` mode has to be enabled.
Comment on lines +192 to +193
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
Kuma provides a convenient way to migrate existing workloads to the mTLS mesh with zero downtime. In order to do so
`PERMISSIVE` mode has to be enabled.
In version 1.3.0 and later, Kuma provides `PERMISSIVE` mTLS mode to let you migrate existing workloads with zero downtime:

This ... seems like something we should maybe also encourage users not to leave on? Or at the very least warn about insecure incoming connections? Or ... something?

I'm also not sure about the order of things. Might be better to put the explanation at lines 228-230 before the examples also?

Copy link
Contributor

Choose a reason for hiding this comment

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

Good point. I'm missing the information on when can I switch from permissive to strict mTLS. Metrics are in progress?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Added a warning:

image

The message and format is not final, I know @Bradamant3 doesn't like a lot of frames :)


:::: tabs :options="{ useUrlFragment: false }"

::: tab "Kubernetes"
```yaml
apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
name: default
spec:
mtls:
enabledBackend: ca-1
backends:
- name: ca-1
type: builtin
mode: PERMISSIVE # supported values: STRICT, PERMISSIVE
```
:::

::: tab "Universal"
```yaml
type: Mesh
name: default
mtls:
enabledBackend: ca-1
backends:
- name: ca-1
type: builtin
mode: PERMISSIVE # supported values: STRICT, PERMISSIVE
```
:::

::::

Permissive mTLS mode encrypts outbound connections the same way as strict mTLS mode, but inbound connections on the server-side
accept both TLS and plaintext. This lets you migrate servers to an mTLS mesh before their clients. It also supports the case where the client and server already implement TLS.

::: warning
Using PERMISSIVE mode is not secure, as soon as all services will be moved to the mesh, make sure to set STRICT mode.
:::

Copy link
Contributor

Choose a reason for hiding this comment

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

Not a blocker but I'm missing here a guide on how can I migrate an app with existing TLS. I bet we will see this question on Kuma slack.

Maybe it should be a part of a bigger guide that let say we have 3 apps, 1 <-> 2 <-> 3. There is custom TLS between 2 <-> 3 and we present how to gradually introduce them to a mesh with mTLS without any downtime.
Just an idea, it can go to the backlog, but we may take this into account when we rewrite docs.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I think we can do it as a tutorial rather than theoretical steps?

### CA requirements

When using an arbitrary certificate and key for a `provided` backend, we must make sure that we comply with the following requirements:
Expand Down