mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-05-16 18:13:17 +00:00
Merge pull request #3735 from dereknola/k3s_encrypt
Add page about new K3s `secrets-encrypt` tool.
This commit is contained in:
Jen Travinski
GitHub
@@ -13,7 +13,6 @@ This section contains advanced information describing the different ways you can
|
||||
- [Using Docker as the container runtime](#using-docker-as-the-container-runtime)
|
||||
- [Using etcdctl](#using-etcdctl)
|
||||
- [Configuring containerd](#configuring-containerd)
|
||||
- [Secrets Encryption Config (Experimental)](#secrets-encryption-config-experimental)
|
||||
- [Running K3s with Rootless mode (Experimental)](#running-k3s-with-rootless-mode-experimental)
|
||||
- [Node labels and taints](#node-labels-and-taints)
|
||||
- [Starting the server with the installation script](#starting-the-server-with-the-installation-script)
|
||||
@@ -145,44 +144,6 @@ For advanced customization for this file you can create another file called `con
|
||||
|
||||
The `config.toml.tmpl` will be treated as a Go template file, and the `config.Node` structure is being passed to the template. [This template](https://github.com/rancher/k3s/blob/master/pkg/agent/templates/templates.go#L16-L32) example on how to use the structure to customize the configuration file.
|
||||
|
||||
# Secrets Encryption Config (Experimental)
|
||||
As of v1.17.4+k3s1, K3s added the experimental feature of enabling secrets encryption at rest by passing the flag `--secrets-encryption` on a server, this flag will do the following automatically:
|
||||
|
||||
- Generate an AES-CBC key
|
||||
- Generate an encryption config file with the generated key
|
||||
|
||||
```
|
||||
{
|
||||
"kind": "EncryptionConfiguration",
|
||||
"apiVersion": "apiserver.config.k8s.io/v1",
|
||||
"resources": [
|
||||
{
|
||||
"resources": [
|
||||
"secrets"
|
||||
],
|
||||
"providers": [
|
||||
{
|
||||
"aescbc": {
|
||||
"keys": [
|
||||
{
|
||||
"name": "aescbckey",
|
||||
"secret": "xxxxxxxxxxxxxxxxxxx"
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"identity": {}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- Pass the config to the KubeAPI as encryption-provider-config
|
||||
|
||||
Once enabled any created secret will be encrypted with this key. Note that if you disable encryption then any encrypted secrets will not be readable until you enable encryption again.
|
||||
|
||||
# Running K3s with Rootless mode (Experimental)
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ If you wish to use an external datastore such as PostgreSQL, MySQL, or etcd you
|
||||
|
||||
CLI Flag | Environment Variable | Description
|
||||
------------|-------------|------------------
|
||||
<span style="white-space: nowrap">`--datastore-endpoint`</span> | `K3S_DATASTORE_ENDPOINT` | Specify a PostgresSQL, MySQL, or etcd connection string. This is a string used to describe the connection to the datastore. The structure of this string is specific to each backend and is detailed below.
|
||||
<span style="white-space: nowrap">`--datastore-endpoint`</span> | `K3S_DATASTORE_ENDPOINT` | Specify a PostgreSQL, MySQL, or etcd connection string. This is a string used to describe the connection to the datastore. The structure of this string is specific to each backend and is detailed below.
|
||||
<span style="white-space: nowrap">`--datastore-cafile`</span> | `K3S_DATASTORE_CAFILE` | TLS Certificate Authority (CA) file used to help secure communication with the datastore. If your datastore serves requests over TLS using a certificate signed by a custom certificate authority, you can specify that CA using this parameter so that the K3s client can properly verify the certificate. |
|
||||
| <span style="white-space: nowrap">`--datastore-certfile`</span> | `K3S_DATASTORE_CERTFILE` | TLS certificate file used for client certificate based authentication to your datastore. To use this feature, your datastore must be configured to support client certificate based authentication. If you specify this parameter, you must also specify the `datastore-keyfile` parameter. |
|
||||
| <span style="white-space: nowrap">`--datastore-keyfile`</span> | `K3S_DATASTORE_KEYFILE` | TLS key file used for client certificate based authentication to your datastore. See the previous `datastore-certfile` parameter for more details. |
|
||||
@@ -81,7 +81,7 @@ The above assumes a typical three node etcd cluster. The parameter can accept on
|
||||
{{% /tab %}}
|
||||
{{% /tabs %}}
|
||||
|
||||
<br/>Based on the above, the following example command could be used to launch a server instance that connects to a PostgresSQL database named k3s:
|
||||
<br/>Based on the above, the following example command could be used to launch a server instance that connects to a PostgreSQL database named k3s:
|
||||
```
|
||||
K3S_DATASTORE_ENDPOINT='postgres://username:password@hostname:5432/k3s' k3s server
|
||||
```
|
||||
|
||||
@@ -0,0 +1,237 @@
|
||||
---
|
||||
title: Secrets Encryption
|
||||
weight: 26
|
||||
---
|
||||
|
||||
# Secrets Encryption Config
|
||||
_Available as of v1.17.4+k3s1_
|
||||
|
||||
K3s supports enabling secrets encryption at rest by passing the flag `--secrets-encryption` on a server; this flag will do the following automatically:
|
||||
|
||||
- Generate an AES-CBC key
|
||||
- Generate an encryption config file with the generated key
|
||||
- Pass the config to the KubeAPI as encryption-provider-config
|
||||
|
||||
Example of the encryption config file:
|
||||
```
|
||||
{
|
||||
"kind": "EncryptionConfiguration",
|
||||
"apiVersion": "apiserver.config.k8s.io/v1",
|
||||
"resources": [
|
||||
{
|
||||
"resources": [
|
||||
"secrets"
|
||||
],
|
||||
"providers": [
|
||||
{
|
||||
"aescbc": {
|
||||
"keys": [
|
||||
{
|
||||
"name": "aescbckey",
|
||||
"secret": "xxxxxxxxxxxxxxxxxxx"
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"identity": {}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Secrets Encryption Tool
|
||||
_Available as of v1.21.8+k3s1_
|
||||
|
||||
K3s contains a utility tool `secrets-encrypt`, which enables automatic control over the following:
|
||||
|
||||
- Disabling/Enabling secrets encryption
|
||||
- Adding new encryption keys
|
||||
- Rotating and deleting encryption keys
|
||||
- Reencrypting secrets
|
||||
|
||||
>**Warning:** Failure to follow proper procedure for rotating encryption keys can leave your cluster permanently corrupted. Proceed with caution.
|
||||
|
||||
### Single-Server Encryption Key Rotation
|
||||
To rotate secrets encryption keys on a single-node cluster:
|
||||
|
||||
- Start the K3s server with the flag `--secrets-encryption`
|
||||
|
||||
>**Note:** Starting K3s without encryption and enabling it at a later time is currently *not* supported.
|
||||
|
||||
1. Prepare
|
||||
|
||||
```
|
||||
k3s secrets-encrypt prepare
|
||||
```
|
||||
|
||||
2. Kill and restart the K3s server with same arguments
|
||||
3. Rotate
|
||||
|
||||
```
|
||||
k3s secrets-encrypt rotate
|
||||
```
|
||||
|
||||
4. Kill and restart the K3s server with same arguments
|
||||
5. Reencrypt
|
||||
|
||||
```
|
||||
k3s secrets-encrypt reencrypt
|
||||
```
|
||||
|
||||
### High-Availability Encryption Key Rotation
|
||||
The steps are the same for both embedded DB and external DB clusters.
|
||||
|
||||
To rotate secrets encryption keys on HA setups:
|
||||
|
||||
>**Note:** While not required, it is recommended that you pick one server node from which to run the `secrets-encrypt` commands.
|
||||
|
||||
- Start up all three K3s servers with the `--secrets-encryption` flag. For brevity, the servers will be referred to as S1, S2, S3.
|
||||
|
||||
1. Prepare on S1
|
||||
|
||||
```
|
||||
k3s secrets-encrypt prepare
|
||||
```
|
||||
|
||||
2. Kill and restart S1 with same arguments
|
||||
3. Once S1 is up, kill and restart the S2 and S3
|
||||
|
||||
4. Rotate on S1
|
||||
|
||||
```
|
||||
k3s secrets-encrypt rotate
|
||||
```
|
||||
|
||||
5. Kill and restart S1 with same arguments
|
||||
6. Once S1 is up, kill and restart the S2 and S3
|
||||
|
||||
7. Reencrypt on S1
|
||||
|
||||
```
|
||||
k3s secrets-encrypt reencrypt
|
||||
```
|
||||
|
||||
8. Kill and restart S1 with same arguments
|
||||
9. Once S1 is up, kill and restart the S2 and S3
|
||||
|
||||
### Single-Server Secrets Encryption Disable/Enable
|
||||
After launching a server with `--secrets-encryption` flag, secrets encryption can be disabled.
|
||||
|
||||
To disable secrets encryption on a single-node cluster:
|
||||
|
||||
1. Disable
|
||||
|
||||
```
|
||||
k3s secrets-encrypt disable
|
||||
```
|
||||
|
||||
2. Kill and restart the K3s server with same arguments
|
||||
|
||||
3. Reencrypt with flags
|
||||
|
||||
```
|
||||
k3s secrets-encrypt reencrypt --force --skip
|
||||
```
|
||||
|
||||
To re-enable secrets encryption on a single node cluster:
|
||||
|
||||
1. Enable
|
||||
|
||||
```
|
||||
k3s secrets-encrypt enable
|
||||
```
|
||||
|
||||
2. Kill and restart the K3s server with same arguments
|
||||
|
||||
3. Reencrypt with flags
|
||||
|
||||
```
|
||||
k3s secrets-encrypt reencrypt --force --skip
|
||||
```
|
||||
|
||||
### High-Availability Secrets Encryption Disable/Enable
|
||||
After launching a HA cluster with `--secrets-encryption` flags, secrets encryption can be disabled.
|
||||
>**Note:** While not required, it is recommended that you pick one server node from which to run the `secrets-encrypt` commands.
|
||||
|
||||
For brevity, the three servers used in this guide will be referred to as S1, S2, S3.
|
||||
|
||||
To disable secrets encryption on a HA cluster:
|
||||
|
||||
1. Disable on S1
|
||||
|
||||
```
|
||||
k3s secrets-encrypt disable
|
||||
```
|
||||
|
||||
2. Kill and restart S1 with same arguments
|
||||
3. Once S1 is up, kill and restart the S2 and S3
|
||||
|
||||
|
||||
4. Reencrypt with flags on S1
|
||||
|
||||
```
|
||||
k3s secrets-encrypt reencrypt --force --skip
|
||||
```
|
||||
|
||||
To re-enable secrets encryption on a HA cluster:
|
||||
|
||||
1. Enable on S1
|
||||
|
||||
```
|
||||
k3s secrets-encrypt enable
|
||||
```
|
||||
|
||||
2. Kill and restart S1 with same arguments
|
||||
3. Once S1 is up, kill and restart the S2 and S3
|
||||
|
||||
4. Reencrypt with flags on S1
|
||||
|
||||
```
|
||||
k3s secrets-encrypt reencrypt --force --skip
|
||||
```
|
||||
|
||||
|
||||
### Secrets Encryption Status
|
||||
The secrets-encrypt tool includes a `status` command that displays information about the current status of secrets encryption on the node.
|
||||
|
||||
An example of the command on a single-server node:
|
||||
```
|
||||
$ k3s secrets-encrypt status
|
||||
Encryption Status: Enabled
|
||||
Current Rotation Stage: start
|
||||
Server Encryption Hashes: All hashes match
|
||||
|
||||
Active Key Type Name
|
||||
------ -------- ----
|
||||
* AES-CBC aescbckey
|
||||
|
||||
```
|
||||
|
||||
Another example on HA cluster, after rotating the keys, but before restarting the servers:
|
||||
```
|
||||
$ k3s secrets-encrypt status
|
||||
Encryption Status: Enabled
|
||||
Current Rotation Stage: rotate
|
||||
Server Encryption Hashes: hash does not match between node-1 and node-2
|
||||
|
||||
Active Key Type Name
|
||||
------ -------- ----
|
||||
* AES-CBC aescbckey-2021-12-10T22:54:38Z
|
||||
AES-CBC aescbckey
|
||||
|
||||
```
|
||||
|
||||
Details on each section are as follows:
|
||||
|
||||
- __Encryption Status__: Displayed whether secrets encryption is disabled or enabled on the node
|
||||
- __Current Rotation Stage__: Indicates the current rotation stage on the node.
|
||||
Stages are: `start`, `prepare`, `rotate`, `reencrypt_request`, `reencrypt_active`, `reencrypt_finished`
|
||||
- __Server Encryption Hashes__: Useful for HA clusters, this indicates whether all servers are on the same stage with their local files. This can be used to identify whether a restart of servers is required before proceeding to the next stage. In the HA example above, node-1 and node-2 have different hashes, indicating that they currently do not have the same encryption configuration. Restarting the servers will sync up their configuration.
|
||||
- __Key Table__: Summarizes information about the secrets encryption keys found on the node.
|
||||
* __Active__: The "*" indicates which, if any, of the keys are currently used for secrets encryption. An active key is used by Kubernetes to encrypt any new secrets.
|
||||
* __Key Type__: All keys using this tool are `AES-CBC` type. See more info [here.](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/#providers)
|
||||
* __Name__: Name of the encryption key.
|
||||
Reference in New Issue
Block a user