k3s secrets-encrypt

K3s supports enabling secrets encryption at rest. For more information, see Secrets Encryption.

Secrets Encryption Tool

K3s contains a CLI 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.

Encryption Key Rotation

Version Gate

Available as of the September 2024 releases: v1.30.5+k3s1, v1.31.1+k3s1

Single-Server

To rotate secrets encryption keys on a single-server cluster:

1. Start the K3s server with the flag --secrets-encryption

2. Rotate secrets encryption keys

   k3s secrets-encrypt rotate-keys

3. Wait for reencryption to finish. Watch the server logs, or wait for:

   $ k3s secrets-encrypt status
   Encryption Status: Enabled
   Current Rotation Stage: reencrypt_finished

High-Availability

For brevity, the servers will be referred to as S1, S2, S3.

To rotate secrets encryption keys on HA setups:

1. Start up all three K3s servers with the --secrets-encryption flag.

2. Rotate secrets encryption keys on S1

   k3s secrets-encrypt rotate-keys

3. Wait for reencryption to finish. Watch the server logs, or wait for:

   $ k3s secrets-encrypt status
   Encryption Status: Enabled
   Current Rotation Stage: reencrypt_finished

   info

   K3s will reencrypt ~5 secrets per second. Clusters with large # of secrets can take several minutes to reencrypt. You can track progress in the server logs.

4. Restart K3s on S1 with same arguments. If running K3s as a service:

   # If using systemd
   systemctl restart k3s
   # If using openrc
   rc-service k3s restart

5. Once S1 is up, restart K3s on S2 and S3

Enable Secrets Encryption on an Existing Cluster

Version Gate

Available as of the March 2026 releases: v1.33.10+k3s1, v1.34.6+k3s1, v1.35.3+k3s1

Use this procedure when the cluster was started without --secrets-encryption and you want to enable secrets encryption at a later time.

Single-Server

1. Verify encryption is currently disabled

   $ k3s secrets-encrypt status 
   Encryption Status: Disabled, no configuration file found

2. Enable secrets encryption on the server

   k3s secrets-encrypt enable

3. Modify the server args/config and add --secrets-encryption. Restart the server.

4. Verify the status shows encryption disabled but at the start stage

   $ k3s secrets-encrypt status
   Encryption Status: Disabled
   Current Rotation Stage: start
   Server Encryption Hashes: All hashes match

5. Rotate keys to enable encryption for new secrets

   k3s secrets-encrypt rotate-keys

6. Restart the server with the same arguments

7. Verify encryption is enabled

   $ k3s secrets-encrypt status
   Encryption Status: Enabled
   Current Rotation Stage: reencrypt_finished
   Server Encryption Hashes: All hashes match

High-Availability

For brevity, the servers will be referred to as S1, S2, S3.

1. Verify encryption is currently disabled

   k3s secrets-encrypt status
   Encryption Status: Disabled, no configuration file found

2. Enable secrets encryption on S1

   k3s secrets-encrypt enable

3. Restart all servers with --secrets-encryption

4. Verify the status shows encryption disabled but at the start stage, and that all server hashes match

   k3s secrets-encrypt status
   Encryption Status: Disabled
   Current Rotation Stage: start
   Server Encryption Hashes: All hashes match

5. Rotate keys on S1 to enable encryption for new secrets

   k3s secrets-encrypt rotate-keys

6. Restart all servers with the same arguments

7. Verify encryption is enabled

   k3s secrets-encrypt status
   Encryption Status: Enabled
   Current Rotation Stage: reencrypt_finished
   Server Encryption Hashes: All hashes match

Legacy Encryption Key Rotation

New Procedure

If using K3s versions v1.30+, we recommend using the Encryption Key Rotation instead.

Single-Server

To rotate secrets encryption keys on a single-server cluster:

1. Start the K3s server with the flag --secrets-encryption

2. Prepare

   k3s secrets-encrypt prepare

3. Kill and restart the K3s server with same arguments. If running K3s as a service:

   # If using systemd
   systemctl restart k3s
   # If using openrc
   rc-service k3s restart

4. Rotate

   k3s secrets-encrypt rotate

5. Kill and restart the K3s server with same arguments

6. Reencrypt

   info

   K3s will reencrypt ~5 secrets per second.
   Clusters with large # of secrets can take several minutes to reencrypt.

   k3s secrets-encrypt reencrypt

High-Availability

The steps are the same for both embedded DB and external DB clusters. or brevity, the servers will be referred to as S1, S2, S3.

To rotate secrets encryption keys on HA setups:

1. Start up all three K3s servers with the --secrets-encryption flag. F

   Notes

   • While not required, it is recommended that you pick one server node from which to run the secrets-encrypt commands.

2. Prepare on S1

   k3s secrets-encrypt prepare

3. Kill and restart S1 with same arguments. If running K3s as a service:

   # If using systemd
   systemctl restart k3s
   # If using openrc
   rc-service k3s restart

4. Once S1 is up, kill and restart the S2 and S3

5. Rotate on S1

   k3s secrets-encrypt rotate

6. Kill and restart S1 with same arguments

7. Once S1 is up, kill and restart the S2 and S3

8. Reencrypt on S1

   info

   K3s will reencrypt ~5 secrets per second.
   Clusters with large # of secrets can take several minutes to reencrypt.

   k3s secrets-encrypt reencrypt

9. Kill and restart S1 with same arguments

10. Once S1 is up, kill and restart the S2 and S3

Secrets Encryption Disable/Re-enable

Single-Server

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. If running K3s as a service:

   # If using systemd
   systemctl restart k3s
   # If using openrc
   rc-service k3s restart

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

note

While not required, it is recommended that you pick one server node from which to run the secrets-encrypt commands.

For brevity, the servers 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. If running K3s as a service:

   # If using systemd
   systemctl restart k3s
   # If using openrc
   rc-service k3s restart

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: Keys using this tool support AES-CBC and secretbox types. See more info here.
  • Name: Name of the encryption key.