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
Merged

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

Changes from 3 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
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 @@
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.

Check warning on line 16 in app/_src/production/secure-deployment/certificates.md

View workflow job for this annotation

GitHub Actions / Lint docs 

[vale] reported by reviewdog 🐶
[Google.Contractions] Use 'isn't' instead of 'is not'.

Raw Output:
{"message": "[Google.Contractions] Use 'isn't' instead of 'is not'.", "location": {"path": "app/_src/production/secure-deployment/certificates.md", "range": {"start": {"line": 16, "column": 14}}}, "severity": "INFO"}

Check warning on line 16 in app/_src/production/secure-deployment/certificates.md

View workflow job for this annotation

GitHub Actions / Lint docs 

[vale] reported by reviewdog 🐶
[Google.Passive] In general, use active voice instead of passive voice ('be confused').

Raw Output:
{"message": "[Google.Passive] In general, use active voice instead of passive voice ('be confused').", "location": {"path": "app/_src/production/secure-deployment/certificates.md", "range": {"start": {"line": 16, "column": 24}}}, "severity": "INFO"}
{% endtip %}

## Data plane proxy to control plane communication
Expand All @@ -25,7 +25,7 @@
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.

Check warning on line 28 in app/_src/production/secure-deployment/certificates.md

View workflow job for this annotation

GitHub Actions / Lint docs 

[vale] reported by reviewdog 🐶
[Google.Passive] In general, use active voice instead of passive voice ('was used').

Raw Output:
{"message": "[Google.Passive] In general, use active voice instead of passive voice ('was used').", "location": {"path": "app/_src/production/secure-deployment/certificates.md", "range": {"start": {"line": 28, "column": 144}}}, "severity": "INFO"}

Check warning on line 28 in app/_src/production/secure-deployment/certificates.md

View workflow job for this annotation

GitHub Actions / Lint docs 

[vale] reported by reviewdog 🐶
[Google.Passive] In general, use active voice instead of passive voice ('is secured').

Raw Output:
{"message": "[Google.Passive] In general, use active voice instead of passive voice ('is secured').", "location": {"path": "app/_src/production/secure-deployment/certificates.md", "range": {"start": {"line": 28, "column": 217}}}, "severity": "INFO"}
Note, this CA is not the same CA for service-to-service communication.

**To override autogenerated certificates**
Expand All @@ -41,7 +41,7 @@
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 @@
--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-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:

Check warning on line 90 in app/_src/production/secure-deployment/certificates.md

View workflow job for this annotation

GitHub Actions / Lint docs 

[vale] reported by reviewdog 🐶
[Google.Parens] Use parentheses judiciously.

Raw Output:
{"message": "[Google.Parens] Use parentheses judiciously.", "location": {"path": "app/_src/production/secure-deployment/certificates.md", "range": {"start": {"line": 90, "column": 100}}}, "severity": "INFO"}

Check warning on line 90 in app/_src/production/secure-deployment/certificates.md

View workflow job for this annotation

GitHub Actions / Lint docs 

[vale] reported by reviewdog 🐶
[Google.Acronyms] Spell out 'PEM', if it's unfamiliar to the audience.

Raw Output:
{"message": "[Google.Acronyms] Spell out 'PEM', if it's unfamiliar to the audience.", "location": {"path": "app/_src/production/secure-deployment/certificates.md", "range": {"start": {"line": 90, "column": 101}}}, "severity": "INFO"}
```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 @@

**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`

Check warning on line 165 in app/_src/production/secure-deployment/certificates.md

View workflow job for this annotation

GitHub Actions / Lint docs 

[vale] reported by reviewdog 🐶
[Google.Acronyms] Spell out 'PKI', if it's unfamiliar to the audience.

Raw Output:
{"message": "[Google.Acronyms] Spell out 'PKI', if it's unfamiliar to the audience.", "location": {"path": "app/_src/production/secure-deployment/certificates.md", "range": {"start": {"line": 165, "column": 51}}}, "severity": "INFO"}

Check warning on line 165 in app/_src/production/secure-deployment/certificates.md

View workflow job for this annotation

GitHub Actions / Lint docs 

[vale] reported by reviewdog 🐶
[Google.Acronyms] Spell out 'PEM', if it's unfamiliar to the audience.

Raw Output:
{"message": "[Google.Acronyms] Spell out 'PEM', if it's unfamiliar to the audience.", "location": {"path": "app/_src/production/secure-deployment/certificates.md", "range": {"start": {"line": 165, "column": 86}}}, "severity": "INFO"}

Check warning on line 165 in app/_src/production/secure-deployment/certificates.md

View workflow job for this annotation

GitHub Actions / Lint docs 

[vale] reported by reviewdog 🐶
[Google.Passive] In general, use active voice instead of passive voice ('was used').

Raw Output:
{"message": "[Google.Passive] In general, use active voice instead of passive voice ('was used').", "location": {"path": "app/_src/production/secure-deployment/certificates.md", "range": {"start": {"line": 165, "column": 158}}}, "severity": "INFO"}

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 @@
{% 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:

Check warning on line 209 in app/_src/production/secure-deployment/certificates.md

View workflow job for this annotation

GitHub Actions / Lint docs 

[vale] reported by reviewdog 🐶
[Google.Acronyms] Spell out 'PEM', if it's unfamiliar to the audience.

Raw Output:
{"message": "[Google.Acronyms] Spell out 'PEM', if it's unfamiliar to the audience.", "location": {"path": "app/_src/production/secure-deployment/certificates.md", "range": {"start": {"line": 209, "column": 83}}}, "severity": "INFO"}
```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` command-line tool:
cloudjumpercat marked this conversation as resolved.
Show resolved Hide resolved
```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 @@
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 @@
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 @@
--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
Loading