#etcd Encryption

Install and operate etcd Encryption Manager in to automate etcd data encryption key rotation within your clusters.

It ensures that sensitive data stored in etcd, such as secrets and configmaps, is encrypted using a secure algorithm, enhancing your cluster's security.

#Key Strategies

The plugin supports two key strategies. Pick the one that matches your cluster role.

In deterministic mode, the runtime Active / Standby role is detected automatically; it is not a manual install parameter.

#Installation

The plugin supports two installation paths depending on the target cluster:

• Workload / DCS clusters — use the default random key strategy.
• Global clusters — must use the deterministic key strategy (see Global Clusters (Deterministic Mode) below).

See Cluster Plugin for the general plugin installation workflow.

#Workload / DCS Clusters (random strategy)

• Supported cluster types: On-Premises, DCS.
• No additional installation parameters are required — install via the standard Cluster Plugin workflow.

#Global Clusters (Deterministic Mode)

#Prerequisites

• The cluster must be a global cluster. When global.cluster.name is global, the chart enforces etcdEncryption.keyStrategy=deterministic; the plugin UI also defaults the field to deterministic for clusters labeled is-global=true.

#Plugin Parameters

The plugin form exposes the following parameters for deterministic installation. Defaults reflect the current plugin-config.yaml shipped with the chart.

The rootSecretRef.namespace is fixed to kube-system and is not exposed in the form.

#key_strategy

For global clusters this must be deterministic.

#replication_group_id

Recommendations:

• For DR clusters built with the etcd Synchronizer, both sides of the same DR group must share the same replication_group_id.
• To avoid leaking real business, environment, or cluster identity, do not reuse the cluster name even when the UI prefills it. Plan a separate opaque identifier ahead of installation.
• A UUID-style identifier may be a good fit, for example 6f1b9e2c-7c3a-4a9c-8b72-2fd0f8f3c1ab.

To generate a UUID-style value from the command line:

openssl rand -hex 16 | sed -E 's/^(.{8})(.{4})(.{4})(.{4})(.{12})$/\1-\2-\3-\4-\5/'

#root_secret_name

The plugin form exposes only the Secret name; the namespace is always kube-system at render time.

#Preparing the Root Secret

The deterministic root Secret must exist in kube-system before installing the plugin. Prepare it in two steps:

1. Generate 32 bytes of cryptographically strong random material into ./root-key.bin. The bytes must come from a high-entropy source — typically the operating system CSPRNG. openssl rand is a safe default; equivalent OS-CSPRNG-backed commands such as head -c 32 /dev/urandom > ./root-key.bin also work. Do not use shell $RANDOM, language-level rand(), or any time-seeded generator.

   openssl rand -out ./root-key.bin 32

2. Create the Secret in kube-system from that file:

   kubectl -n kube-system create secret generic etcd-derivation-root \
     --from-file=root-key=./root-key.bin

If you use a different Secret name, replace etcd-derivation-root above with the value you will enter as root_secret_name.

#Advanced (chart values, not exposed in the plugin form)

#How it Works

Upon installation, an etcd-encryption-manager controller is deployed in the kube-system namespace, which:

• Periodically rotates etcd data encryption keys.
• Retains the 8 most recent keys for rollback compatibility.
• Updates encryption configurations on all control nodes.
• Triggers kube-apiserver to hot reload new keys.
• Automatically migrates resources to re-encrypt data with new keys.

Cluster stability is maintained throughout these operations.

When the plugin is installed in deterministic mode on a global DR pair, the controller additionally:

• Detects whether it is acting as Active or Standby at runtime — this is not a manual configuration.
• On the Active side, generates the SeedBundle and lets the etcd Synchronizer replicate it to the Standby.
• On the Standby side, derives the same per-revision keys from the shared SeedBundle and the root Secret, so a failover produces identical encryption keys without manual key copy.

#Default Configuration

#Operations Guide

#Configuration Files

#Checking Status

Run the following command to check the current rotation status:

kubectl get EtcdEncryptionConfig default -o yaml

Example output:

apiVersion: cluster.alauda.io/v1alpha1
kind: EtcdEncryptionConfig
metadata:
  name: default
spec:
  resources:
    - secrets
    - configmaps
  rotationInterval: 168h0m0s
  type: aesgcm
status:
  deployStatus:
    192.168.100.1:
      revision: 3
      state: Success
    192.168.100.2:
      revision: 3
      state: Success
    192.168.100.3:
      revision: 3
      state: Success
  migration:
    completeTimestamp: "2025-05-27T05:47:01Z"
    resources:
      - secrets
      - configmaps
    revision: 3
    state: Success
  revision: 3