Etcd 데이터 백업 및 복원방법

소 개

1. etcd는 정족수에 따라 (n-1)/2의 노드수 만큼 일시적인 장애를 허용하지만, H/W의 장애나 네트워크의 영구적인 문제 등 단기간내에 복구가 이루어 지지 않으면 ETCD 자체에 문제가 발생할 수도 있습니다, 이럴때 주기적으로 백업(snapshot)을 받아놓았다면, 해당 백업(snapshot)을 가지고 복구를 수행 후 kubernetes를 운영할 수 있습니다.
2. etcd 백업(snapshot)은 다중 노드에서 수행해도 되나, 복구는 동일한 백업(snapshot)을 가지고 복구를 해야 합니다, 특히 다중 노드에서 개별 노드에 백업(snapshot)된 데이터를 복구할 경우 오히려 kubernetes의 데이터의 문제로 장애가 발생 할 수 있으니, 복구는 동일한 snaphot을 가지고 복구를 수행하셔야 합니다.
3. 백업(snapshot)수행시 무결성 검증을 위한 해쉬값이 포함되는데, 백업(snapshot)된 데이터의 수정을 하는 경우 해쉬데이터가 깨질수 있습니다. 불가피한 경우로 해쉬데이터를 무시하고 복구를 수행이 필요한 경우 --skip-hash-check 옵션을 추가하여 복구를 수행하면 복구가 가능합니다.
4. 이번에는 Kubernetes에서 중요한 역할을 하는 API Server와 클러스터 상태 정보를 저장하는 etcd의 백업과 복구 방법을 정리하겠습니다.

안내

etcd 3.6이후부터는 etcdctl 명령어는 deprecated 된다고 합니다. (etcdutil -> etcdutl)

작업절차

1. etcd스크립트 생성

   $> cat /usr/local/bin/etcdctl.sh
   #!/bin/bash
   # Ansible managed
   # example invocation: etcdctl.sh get --keys-only --from-key ""
   
   etcdctl \
     --cacert /etc/ssl/etcd/ssl/ca.pem \
     --cert /etc/ssl/etcd/ssl/admin-master1.pem \
     --key /etc/ssl/etcd/ssl/admin-master1-key.pem "$@"
   

2. /tmp/backup 파일로 etcd snapshot 수행

   $> ./etcdctl.sh snapshot save /tmp/backup
   {"level":"info","ts":"2024-09-23T23:43:44.67136+0900","caller":"snapshot/v3_snapshot.go:65","msg":"created temporary db file","path":"/tmp/backup.part"}
   {"level":"info","ts":"2024-09-23T23:43:44.672148+0900","logger":"client","caller":"v3@v3.5.10/maintenance.go:212","msg":"opened snapshot stream; downloading"}
   {"level":"info","ts":"2024-09-23T23:43:44.672741+0900","caller":"snapshot/v3_snapshot.go:73","msg":"fetching snapshot","endpoint":"127.0.0.1:2379"}
   {"level":"info","ts":"2024-09-23T23:43:44.71756+0900","logger":"client","caller":"v3@v3.5.10/maintenance.go:220","msg":"completed snapshot read; closing"}
   {"level":"info","ts":"2024-09-23T23:43:44.730295+0900","caller":"snapshot/v3_snapshot.go:88","msg":"fetched snapshot","endpoint":"127.0.0.1:2379","size":"6.2 MB","took":"now"}
   {"level":"info","ts":"2024-09-23T23:43:44.730359+0900","caller":"snapshot/v3_snapshot.go:97","msg":"saved","path":"/tmp/backup"}
   

3. 백업(snapshot)된 데이터 확인

   $> ./etcdctl.sh snapshot status /tmp/backup  -w table
   +----------+----------+------------+------------+
   |   HASH   | REVISION | TOTAL KEYS | TOTAL SIZE |
   +----------+----------+------------+------------+
   | 844eca85 |  1914345 |       1100 |     6.2 MB |
   +----------+----------+------------+------------+
   

4. 백업된 데이터 복구 방법

   $> ./etcdctl.sh snapshot restore /tmp/backup
   2024-09-23T23:48:49+09:00       info    snapshot/v3_snapshot.go:260     restoring snapshot      {"path": "/tmp/backup", "wal-dir": "default.etcd/member/wal", "data-dir": "default.etcd", "snap-dir": "default.etcd/member/snap"}
   2024-09-23T23:48:49+09:00       info    membership/store.go:141 Trimming membership information from the backend...
   2024-09-23T23:48:49+09:00       info    membership/cluster.go:421       added member    {"cluster-id": "cdf818194e3a8c32", "local-member-id": "0", "added-peer-id": "8e9e05c52164694d", "added-peer-peer-urls": ["http://localhost:2380"]}
   2024-09-23T23:48:49+09:00       info    snapshot/v3_snapshot.go:287     restored snapshot       {"path": "/tmp/backup", "wal-dir": "default.etcd/member/wal", "data-dir": "default.etcd", "snap-dir": "default.etcd/member/snap"}
   

5. timer기반의 정기 백업 절차 구성
   • 백업스크립트 구성

     $> vi /root/etcd_backup.sh
     
     #!/bin/bash
     
     PATH=/usr/local/bin:$PATH
     
     BACK_DATE=$(date +%Y-%m-%d)
     ORI_DATE=$(date +%Y-%m-%d -d '7days')
     BACK_DIR=/tmp/backup
     
     #백업 디렉토리 없으면 생성
     if [[ ! -d $BACK_DIR ]]
     then
      mkdir -p $BACK_DIR
     fi
     
     #백업 수행
     /usr/local/bin/etcdctl.sh snapshot save $BACK_DIR/etcd-$BACK_DATE
     
     #백업파일 확인 후 미생성시 에러
     if [[ ! -f $BACK_DIR/etcd-$BACK_DATE ]]
       then
       echo "Backup failed"
       exit 1
     fi
     
     #오래된 데이터 삭제
     rm -f $BACK_DIR/etcd-$ORI_DATE
     

     $> chmod +x /root/etcd_backup.sh
     $> ls -l  /root/etcd_backup.sh
     -rwxr-xr-x 1 root root 483  9월 23 23:55 /root/etcd_backup.sh
     

   • timer 구성 (매일 04시에 백업수행)
     

     $> cat /etc/systemd/system/etcd_backup.timer
     [Unit]
     Description=ETCD Backup
     
     [Timer]
     OnCalendar=*-*-* 04:00:00
     
     [Install]
     WantedBy=multi-user.target
     

   • timer에 연결된 서비스 구성
     

     $> cat /etc/systemd/system/etcd_backup.service
     [Unit]
     Description=ETCD Backup script
     
     [Service]
     Type=oneshot
     ExecStart= /root/etcd_backup.sh
     

   • backup timer 활성화
     

     $>  systemctl daemon-reload
     $> systemctl enable etcd_backup.timer --now
     Created symlink /etc/systemd/system/multi-user.target.wants/etcd_backup.timer → /etc/systemd/system/etcd_backup.timer.
     

   • timer 확인
     

     $> systemctl status etcd_backup.timer
     ● etcd_backup.timer - ETCD Backup
          Loaded: loaded (/etc/systemd/system/etcd_backup.timer; enabled; vendor preset: disabled)
          Active: active (waiting) since Mon 2024-06-23 23:58:42 KST; 1s ago
           Until: Mon 2024-06-23 23:58:42 KST; 1s ago
         Trigger: Tue 2024-06-24 04:00:00 KST; 6h left
        Triggers: ● etcd_backup.service
     

Reference

• https://kubernetes.io/docs/tasks/administer-cluster/configure-upgrade-etcd/#etcd-verify-snapshot-1
• https://etcd.io/docs/v3.5/op-guide/maintenance/
  
  
  

작성일: 2026년 6월 18일 ,  마지막 업데이트: 2026년 8월 20일