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(certs): Add note about supported cert types to docs #1484

Merged
merged 4 commits into from
Oct 25, 2023
+42 −32
Merged

docs(certs): Add note about supported cert types to docs #1484

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
967c85e
Add note about error when you use unsupported certs or corrupted data
cloudjumpercat Oct 12, 2023
4f7c251
Add supported cert type and fix some formatting
cloudjumpercat Oct 16, 2023
1ecdfb5
Fix Vale warnings
cloudjumpercat Oct 20, 2023
e34139d
Add CLI to Vale ignore file
cloudjumpercat Oct 23, 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 .github/styles/Vocab/Base/accept.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ Bitnami
blockquotes?
boolean
CloudFormation
CLI
CNI|cni
Cognito
configs?
Expand Down
73 changes: 41 additions & 32 deletions app/_src/production/secure-deployment/certificates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ This page explains how secure access is provided across a {{site.mesh_product_na
directory is `$HOME/.kuma`. You can change the working directory by setting the `KUMA_GENERAL_WORK_DIR` environment variable.

{% tip %}
This section is not to be confused with the [mTLS policy](/docs/{{ page.version }}/policies/mutual-tls/) that we can apply to a {% if_version lte:2.1.x %}[Mesh](/docs/{{ page.version }}/policies/mesh/){% endif_version %}{% if_version gte:2.2.x %}[Mesh](/docs/{{ page.version }}/production/mesh/){% endif_version %} to secure service-to-service traffic.
This section is not to be confused with the [mTLS policy](/docs/{{ page.version }}/policies/mutual-tls/) that you can apply to a {% if_version lte:2.1.x %}[Mesh](/docs/{{ page.version }}/policies/mesh/){% endif_version %}{% if_version gte:2.2.x %}[Mesh](/docs/{{ page.version }}/production/mesh/){% endif_version %} to secure service-to-service traffic.
{% endtip %}

## Data plane proxy to control plane communication
Expand All @@ -25,7 +25,7 @@ A data plane proxy connects to the control plane for its configuration, includin
Because the data plane proxy and the control plane exchange sensitive information, the communication needs to be encrypted by TLS.
By default, the control plane's server that is consumed by the data plane proxy is secured by TLS with autogenerated certificates.

It is recommended that the data plane proxy verifies the identity of the control plane. To do so, data plane proxies need to obtain the CA that was used to generate the certificate by which the control plane's server is secured.
It's recommended that the data plane proxy verifies the identity of the control plane. To do so, data plane proxies need to obtain the CA that was used to generate the certificate by which the control plane's server is secured.
Note, this CA is not the same CA for service-to-service communication.

**To override autogenerated certificates**
Expand All @@ -41,7 +41,7 @@ and [control plane to control plane](#control-plane-to-control-plane-multizone)
Generate a TLS pair with a PKI of your choice and store it in PEM-encoded format in `/tmp/tls.crt`, `/tmp/tls.key`.
Store the CA that was used to sign this pair in `/tmp/ca.crt`.

We can also use `kumactl` to generate self-signed certs:
You can also use `kumactl` to generate self-signed certs:
```sh
kumactl generate tls-certificate \
--type=server \
Expand All @@ -50,7 +50,7 @@ kumactl generate tls-certificate \
--key-file=/tmp/tls.key
```

Since "tls.crt" is a self-signed cert, it is also a CA:
Since "tls.crt" is a self-signed cert, it's also a CA:
```sh
cp /tmp/tls.crt /tmp/ca.crt
```
Expand Down Expand Up @@ -87,6 +87,11 @@ KUMA_GENERAL_TLS_CERT_FILE=/tmp/tls.crt \
kuma-cp run
```

If you receive an error like the following, make sure you are using a supported certificate type (PEM) and that the certificate doesn't contain incomplete or corrupted data:
```sh
Warning FailedCreate 3m39s (x18 over 14m) replicaset-controller Error creating: Internal error occurred: failed calling webhook "namespace-kuma-injector.kuma.io": could not get REST client: unable to load root certificates: unable to parse bytes as PEM block
```

Configure the data plane proxy with CA:

```sh
Expand Down Expand Up @@ -157,23 +162,21 @@ The API Server HTTPS server is secured by default by autogenerated certificates.

**To override autogenerated certificates.**

1) Prepare certificates

Generate TLS pair with a PKI of your choice and store it in PEM-encoded format in `/tmp/tls.crt`, `/tmp/tls.key`. Store the CA that was used to sign this pair in `/tmp/ca.crt`

We can also use `kumactl` to generate self-signed certs:
```sh
kumactl generate tls-certificate \
--type=server \
--hostname=<KUMA_CP_DNS_NAME> \
--cert-file=/tmp/tls.crt \
--key-file=/tmp/tls.key
```

Since "tls.crt" is a self-signed cert, it is also a CA:
```sh
cp /tmp/tls.crt /tmp/ca.crt
```
1) Prepare certificates. Generate TLS pair with a PKI of your choice and store it in PEM-encoded format in `/tmp/tls.crt`, `/tmp/tls.key`. Store the CA that was used to sign this pair in `/tmp/ca.crt`

You can also use `kumactl` to generate self-signed certs:
```sh
kumactl generate tls-certificate \
--type=server \
--hostname=<KUMA_CP_DNS_NAME> \
--cert-file=/tmp/tls.crt \
--key-file=/tmp/tls.key
```

Since "tls.crt" is a self-signed cert, it's also a CA:
```sh
cp /tmp/tls.crt /tmp/ca.crt
```

2) Configure the control plane with generated certificates
{% tabs configure-control-plane useUrlFragment=false %}
Expand Down Expand Up @@ -203,15 +206,21 @@ KUMA_API_SERVER_HTTPS_TLS_CERT_FILE=/tmp/tls.crt \
{% endtab %}
{% endtabs %}

3) Configure secure connection using `kumactl` CLI tool:
```sh
kumactl config control-planes add \
--name=<NAME> \
--address=https://<KUMA_CP_DNS_NAME>:5682 \
--ca-cert-file=/tmp/ca.crt \
```
If you receive an error like the following, make sure you are using a supported PEM certificate and that the certificate doesn't contain incomplete or corrupted data:
```sh
Warning FailedCreate 3m39s (x18 over 14m) replicaset-controller Error creating: Internal error occurred: failed calling webhook "namespace-kuma-injector.kuma.io": could not get REST client: unable to load root certificates: unable to parse bytes as PEM block
```


3) Configure secure connection using the `kumactl` CLI:
```sh
kumactl config control-planes add \
--name=<NAME> \
--address=https://<KUMA_CP_DNS_NAME>:5682 \
--ca-cert-file=/tmp/ca.crt \
```

We can also hide the HTTP version of API Server by binding it to localhost `KUMA_API_SERVER_HTTP_INTERFACE: 127.0.0.1` or by disabling it altogether `KUMA_API_SERVER_HTTP_ENABLED: false`
You can also hide the HTTP version of API Server by binding it to localhost `KUMA_API_SERVER_HTTP_INTERFACE: 127.0.0.1` or by disabling it altogether `KUMA_API_SERVER_HTTP_ENABLED: false`

### Authentication

Expand All @@ -226,7 +235,7 @@ A zone control plane connects to a global control plane for policies configurati
Because the global control plane and the zone control plane exchange sensitive information, the communication needs to be encrypted by TLS.
By default, the global control plane's server that is consumed by the zone control plane is secured by TLS with autogenerated certificates.

It is recommended that the zone control plane verifies the identity of the global control plane. To do so, zone control planes need to obtain the CA that was used to generate the certificate by which the control plane's server is secured.
It's recommended that the zone control plane verifies the identity of the global control plane. To do so, zone control planes need to obtain the CA that was used to generate the certificate by which the control plane's server is secured.

**To override autogenerated certificates**

Expand All @@ -235,7 +244,7 @@ It is recommended that the zone control plane verifies the identity of the globa
Generate TLS pair with a PKI of your choice and store it in PEM-encoded format in `/tmp/tls.crt`, `/tmp/tls.key`.
Store the CA that was used to sign this pair in `/tmp/ca.crt`

We can also use `kumactl` to generate self-signed certs:
You can also use `kumactl` to generate self-signed certs:
```sh
kumactl generate tls-certificate \
--type=server \
Expand All @@ -244,7 +253,7 @@ kumactl generate tls-certificate \
--key-file=/tmp/tls.key
```

Since "tls.crt" is a self-signed cert, it is also a CA:
Since "tls.crt" is a self-signed cert, it's also a CA:
```sh
cp /tmp/tls.crt /tmp/ca.crt
```
Expand Down