Backup an etcd Cluster

This guide demonstrates how to create backups for etcd clusters managed by KubeBlocks using the datafile backup method.

Backup Method

KubeBlocks etcd uses datafile for full backups:

Prerequisites

Before proceeding, verify your environment meets these requirements:

• A functional Kubernetes cluster (v1.21+ recommended)
• kubectl v1.21+ installed and configured with cluster access
• Helm installed (installation guide)
• KubeBlocks installed (installation guide)
• etcd Add-on installed and an etcd cluster running (see Quickstart)

• A BackupRepo configured and in Ready state. See Create a BackupRepo for setup instructions.

Verify Backup Configuration

Check BackupRepo

kubectl get backuprepo

NAME         STATUS   STORAGEPROVIDER   ACCESSMETHOD   DEFAULT   AGE
minio-repo   Ready    minio             Tool           true      6h

Check BackupPolicy

KubeBlocks automatically generates a BackupPolicy for each etcd cluster:

kubectl get backuppolicy -n demo -l app.kubernetes.io/instance=etcd-cluster

NAME                              BACKUP-REPO   STATUS      AGE
etcd-cluster-etcd-backup-policy                Available   10m

etcd supports one backup method: datafile.

Create an On-Demand Backup

apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: Backup
metadata:
  name: etcd-cluster-backup
  namespace: demo
spec:
  # Backup method: datafile
  backupMethod: datafile
  backupPolicyName: etcd-cluster-etcd-backup-policy
  # `Retain`: backup data is kept when the Backup CR is deleted
  # `Delete`: backup data is removed when the Backup CR is deleted
  deletionPolicy: Delete

Apply it:

kubectl apply -f https://raw.githubusercontent.com/apecloud/kubeblocks-addons/refs/heads/main/examples/etcd/backup.yaml

Monitor Backup Progress

kubectl get backup etcd-cluster-backup -n demo -w

NAME                   POLICY                             METHOD     REPO         STATUS      TOTAL-SIZE   DURATION   DELETION-POLICY   CREATION-TIME
etcd-cluster-backup    etcd-cluster-etcd-backup-policy    datafile   minio-repo   Running     0            0s         Delete            2026-04-03T17:20:00Z
etcd-cluster-backup    etcd-cluster-etcd-backup-policy    datafile   minio-repo   Completed   853          10s        Delete            2026-04-03T17:20:00Z

A Completed status means the backup succeeded.

Configure Scheduled Backups

Enable automatic scheduled backups by updating the BackupSchedule:

kubectl patch backupschedule etcd-cluster-etcd-backup-schedule -n demo \
  --type merge \
  -p '{"spec":{"schedules":[{"backupMethod":"datafile","cronExpression":"0 2 * * *","enabled":true,"retentionPeriod":"7d"}]}}'

This schedules a daily backup at 2:00 AM with a 7-day retention period.

Verify:

kubectl get backupschedule etcd-cluster-etcd-backup-schedule -n demo -oyaml \
  | grep -A5 "schedules:"

  schedules:
  - backupMethod: datafile
    cronExpression: 0 2 * * *
    enabled: true
    retentionPeriod: 7d

Troubleshooting

If a backup fails or stays in Running state:

1. Check the Backup resource for errors:

   kubectl describe backup etcd-cluster-backup -n demo
   

2. Check the backup job:

   kubectl get job -n demo -l app.kubernetes.io/instance=etcd-cluster,app.kubernetes.io/managed-by=kubeblocks-dataprotection
   

3. Check job pod logs:

   kubectl logs -n demo -l app.kubernetes.io/instance=etcd-cluster,app.kubernetes.io/managed-by=kubeblocks-dataprotection
   

Cleanup

kubectl delete backup etcd-cluster-backup -n demo
kubectl delete cluster etcd-cluster -n demo
kubectl delete ns demo