Control Plane Backup
This guide explains how to back up the core data of your Kubernetes cluster — etcd snapshots and PKI certificates — as a single bundle to object storage.
What is a Control Plane Backup? — A control plane backup provides cluster-level disaster recovery (DR) that Velero does not cover. etcd is the "brain" of the cluster, holding all resource information, while PKI certificates (/etc/kubernetes/pki) protect cluster communication. Both must be backed up together to fully recover a cluster.
Data Stored in a Control Plane Backup
- etcd snapshot: Includes the definitions of all K8s resources such as Pods, Deployments, Services, ConfigMaps, and Secrets.
- PKI certificates (
/etc/kubernetes/pki): Includes the full certificate bundle used for cluster communication — CA certificates, API server certificates, etcd certificates, and more.
A control plane backup stores K8s resource definitions and certificates. Actual application data stored in PersistentVolumes must be protected separately using Velero backups.
If etcd at-rest encryption (EncryptionConfiguration) is enabled, the Secrets inside the snapshot are stored as ciphertext. The decryption key (/etc/kubernetes/enc/encryption-config.yaml) is not part of this backup bundle, so you must back up the key separately in a secure location. If the key is lost, the Secrets cannot be recovered even after restoring the snapshot.
⚠️ Do not keep the key in the same storage or same bundle as the etcd snapshot. If the data and the key leak together — or are lost together — encryption becomes meaningless.
Backup Creation Procedure
Control plane backups are created with the backup wizard: connection method selection → SSH credentials → etcd tool check → backup settings.
Step 1: Navigate to Backup Management
- Click [Backup Management] in the left menu.
- In the Backup List tab, switch the K8s backup Segmented control to Control Plane. (Choose between Velero / Control Plane.)
- Click the Create Backup button.
Can't see your cluster? — Verify that the Kubernetes cluster is properly registered on the [Runtime Environment] page.
Step 2: Select Connection Method
Choose whether to connect to the master node directly via SSH or through a VPN. If you cannot reach the master directly from your network, you can connect through an active VPN session.
Step 3: Enter Master Node SSH Credentials
The backup is performed by connecting directly to the master node via SSH. Multi-hop SSH through a gateway is supported.
- SSH connection details: host/port/username/password for the master node (and any gateway hop)
- sudo password: sudo password required to run
etcdctl snapshot save
SSH credential storage — The SSH connection credentials you enter (password/private key) are stored encrypted (AES-256-GCM) on the KIOPS server and are automatically reused for later operations against the same master node (such as restore). No plaintext is kept in the browser. (For security, some values like the sudo password may be requested again at operation time.)
Step 4: Check and Install etcd Backup Tools
When you reach the backup settings step, the master node is automatically checked for etcdctl/etcdutl.
- If the tools are missing, an "etcd backup tools are not installed" notice appears with an Install Backup Tools button.
- Clicking it detects the cluster's etcd version and installs the matching tools. The Create Backup button stays disabled until installation finishes.
Why the tool check is needed — Control plane backup/restore relies on etcdctl/etcdutl on the master node. Even in environments without these tools (e.g., external clusters), they are prepared automatically at this step without any manual installation.
Step 5: Configure and Run the Backup
- Choose a backup name (default auto-generated as
cp-YYYYMMDDHHmmss) and a backup storage. - Click the Create Backup button.
- The backend automatically performs the following steps:
- Connect to the master node via SSH
- Run
etcdctl snapshot save - Compress the
/etc/kubernetes/pkidirectory to tar.gz - Upload to object storage (path:
controlplane/<backup-name>/) - Clean up temporary files
- The backup is complete when the status in the control plane backup list changes to completed.
Control Plane Backup List Columns
| Column | Description |
|---|---|
| Backup name | Identifier for the created backup |
| Size | File size of the backup bundle |
| Created at | Creation timestamp |
| Actions | Provides Restore and Delete icons |
Differences from Velero Backup
| Item | Control Plane Backup | Velero Backup |
|---|---|---|
| Protected scope | Cluster structure (etcd + PKI) | Application workloads + PV data |
| Access method | Direct SSH to master node | Velero Agent (inside cluster) |
| Restore scope | Full cluster reconstruction | Namespace/resource-level selective restore |
| Recommended use | Cluster-level DR | Per-service backup and migration |
Recommended operational strategy — In production, run Control Plane Backup + Velero Backup together. The control plane backup provides the foundation for cluster recovery, while Velero protects application data.
Restore Flow Preview
Clicking the Restore icon in the control plane backup list opens the restore wizard. Like backup creation, it proceeds through connection method selection → SSH credentials → confirmation.
- Select connection method: Choose direct SSH or via VPN.
- Re-enter master node SSH credentials: SSH connection details (multi-hop supported) are required again at restore time.
- Enter sudo password: Enter the sudo password required to stop/restore etcd and apply the PKI.
- Enter confirmation text: You must type the backup name exactly for the restore button to become enabled.
See the Recovery guide for detailed restore steps.
Troubleshooting
Backup Failure: "etcdctl snapshot save failed"
Why does this happen? A problem occurred while connecting to the etcd cluster or saving the snapshot.
How to resolve
- Check SSH credentials: Verify that the master node SSH connection details are correct.
- Check sudo privileges: Confirm that the account has sudo privileges.
- Check etcd status: Verify that all etcd members are healthy.
- Check disk space: Confirm that sufficient temporary storage is available on the master node.
Backup Failure: Object Storage Upload Error
How to resolve
- Verify storage registration: In [Backup Management] > Storage Management tab, confirm that object storage is properly registered.
- Re-validate credentials: Check that the Access Key, Secret Key, and bucket name are correct.
- Check network connectivity: Verify that the KIOPS server can reach the object storage endpoint.
Preventing backup corruption — Create control plane backups regularly to maintain multiple recovery points. Always create a manual backup before performing significant cluster changes.