Kubernetesのetcdのバックアップとリストア手順｜スナップショットの取得から復元・定期実行まで

Kubernetes のクラスターの状態（Deployment、Service、Secret など、API で作ったリソースのすべて）は etcd に保存されています。etcd のバックアップは etcdctl snapshot save でスナップショットを取り、リストアは etcdutl snapshot restore で新しいデータディレクトリに展開して、etcd をそこから起動し直すのが基本です。この記事では、kubeadm で構築したクラスターを例に、取得・検証・復元・定期実行の手順と、スナップショットに含まれないものを説明します。

前提：etcd に直接触れられる環境か

etcd を直接バックアップできるのは、コントロールプレーンを自分で管理しているクラスターだけです。

• kubeadm などで自前構築したクラスター: この記事の手順が使えます。
• EKS、GKE、AKS などのマネージドサービス: etcd はクラウド事業者が管理しており、利用者は触れられません。リソースのバックアップには Velero のようなツールを使い、API 経由でマニフェストと永続ボリュームを保存します。
• k3s: 組み込み etcd を使う構成では k3s etcd-snapshot save という専用のコマンドがあり、定期スナップショットの設定もできます。SQLite を使う既定構成では、データベースファイルのバックアップになります。手順が異なるため、k3s のドキュメントを参照してください。

また、作業の前に etcd のバージョンを確認しておきます。リストアには、バックアップを取った etcd と同じバージョンのツールを使うのが安全です。

kubectl -n kube-system get pod -l component=etcd \
  -o jsonpath='{.items[0].spec.containers[0].image}'

etcdctl と etcdutl の使い分け

etcd には2つのコマンドラインツールがあります。

• etcdctl: 動いている etcd にネットワーク経由で接続して操作します。スナップショットの取得（snapshot save）はこちらです。
• etcdutl: etcd のデータファイルを直接扱います。スナップショットの検証や復元はこちらで行います。

etcd 3.5 以降、etcdctl snapshot restore と etcdctl snapshot status は非推奨になり、etcdutl を使うよう案内されています。古い手順書で etcdctl を使っている箇所は、etcdutl に読み替えてください（2026年10月現在）。

ツールはホストに入っていないことが多いので、etcd の GitHub リリースから、クラスターの etcd と同じバージョンのものを取得してコントロールプレーンのノードに置きます。

手順1：スナップショットを取る

kubeadm のクラスターでは、etcd は TLS のクライアント証明書がないと接続できません。証明書は /etc/kubernetes/pki/etcd/ にあります。

sudo ETCDCTL_API=3 etcdctl \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  snapshot save /var/backups/etcd/snapshot-$(date +%Y%m%d-%H%M).db

ETCDCTL_API=3 は、etcd 3.4 以降では既定値なので省略できますが、付けておくと古い環境でも同じ動きになります。証明書のパスは etcd の静的 Pod のマニフェスト（/etc/kubernetes/manifests/etcd.yaml）の --cert-file などの引数で確認できます。

context deadline exceeded で失敗する場合は、エンドポイントの URL（https か、ポートが2379か）と、証明書の3つのパスを見直します。

手順2：スナップショットを検証する

取ったスナップショットが壊れていないかを確かめます。

sudo etcdutl snapshot status /var/backups/etcd/snapshot-20261018-0300.db -w table

ハッシュ、リビジョン、キーの総数、サイズが表示されます。キーの総数が極端に少ない、サイズが前回より大幅に小さい、といった場合は、取得先や証明書の指定を確認します。

スナップショットの扱いに注意する

etcd のスナップショットには Secret の中身が含まれます。保存時暗号化（EncryptionConfiguration）を設定していないクラスターでは、パスワードや API トークンが読める状態で入っています。

• バックアップの保存先は、閲覧できる人を限定します。
• 外部に転送する場合は、暗号化してから送ります。
• 保存時暗号化を設定している場合、復元には暗号化に使った鍵が必要です。EncryptionConfiguration のファイルも、スナップショットとは別の安全な場所に保管してください。鍵が無いと、復元しても Secret を読めません。

kubeadm のクラスターでは、/etc/kubernetes/pki/ の証明書類もあわせてバックアップしておくと、ノードを作り直すときに役立ちます。

手順3：リストアする

リストアは、クラスターの状態をスナップショットの時点まで巻き戻す操作です。スナップショット以降に作ったリソースや変更はすべて失われます。本番で行う前に、検証用のクラスターで一度手順を通しておいてください。

ここでは、コントロールプレーン1台の kubeadm クラスターを例にします。

3-1. API サーバーと etcd を止める

kubeadm では、/etc/kubernetes/manifests/ に置かれた静的 Pod のマニフェストを kubelet が起動しています。マニフェストを別の場所に移すと、その Pod が止まります。

sudo mkdir -p /root/manifests-backup
sudo mv /etc/kubernetes/manifests/kube-apiserver.yaml /root/manifests-backup/
sudo mv /etc/kubernetes/manifests/etcd.yaml /root/manifests-backup/

数十秒待ってから、コンテナが止まったことを確認します（containerd の場合は sudo crictl ps）。

3-2. 新しいデータディレクトリに復元する

既存の /var/lib/etcd は上書きせず、別のディレクトリに復元します。失敗したときに元に戻せるようにするためです。

sudo etcdutl snapshot restore /var/backups/etcd/snapshot-20261018-0300.db \
  --data-dir /var/lib/etcd-restored

3-3. etcd の参照先を変えて起動する

退避した etcd.yaml を編集し、hostPath のうち /var/lib/etcd を指している箇所を /var/lib/etcd-restored に書き換えます。

  volumes:
  - hostPath:
      path: /var/lib/etcd-restored
      type: DirectoryOrCreate
    name: etcd-data

マニフェストを元の場所に戻すと、kubelet が etcd と API サーバーを起動し直します。etcd を先に戻し、起動を確認してから API サーバーを戻すと、問題の切り分けがしやすくなります。

sudo mv /root/manifests-backup/etcd.yaml /etc/kubernetes/manifests/
sudo mv /root/manifests-backup/kube-apiserver.yaml /etc/kubernetes/manifests/

3-4. 復元後の確認

kubectl get nodes
kubectl get pods -A

Kubernetes の公式ドキュメントでは、復元後に kube-scheduler、kube-controller-manager、kubelet などのコンポーネントを再起動することが推奨されています。古い状態を覚えたままのコンポーネントが、復元した状態と食い違う動きをするのを防ぐためです。

コントロールプレーンが複数台ある構成では、すべてのメンバーで同じスナップショットから復元し、--name、--initial-cluster、--initial-advertise-peer-urls などでメンバー構成を指定し直す必要があります。手順が長くなるため、etcd の災害復旧のドキュメントに沿って進めてください。

定期バックアップを自動化する

手動で取るだけでは、いざというときに最新のスナップショットがありません。cron や systemd タイマーで定期的に取得します。次のスクリプトは、スナップショットを取り、検証し、7日より古いものを削除する例です。

#!/usr/bin/env bash
set -euo pipefail

BACKUP_DIR=/var/backups/etcd
FILE="${BACKUP_DIR}/snapshot-$(date +%Y%m%d-%H%M).db"

mkdir -p "${BACKUP_DIR}"

ETCDCTL_API=3 etcdctl \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  snapshot save "${FILE}"

etcdutl snapshot status "${FILE}" -w table

chmod 600 "${FILE}"

# 7日より古いスナップショットを削除する
find "${BACKUP_DIR}" -name 'snapshot-*.db' -mtime +7 -delete

運用では次の点も決めておきます。

• 保存先をノードの外にする。 コントロールプレーンのディスクが壊れれば、そこにあるバックアップも失われます。暗号化したうえで、オブジェクトストレージや別のサーバーに転送します。
• 失敗に気づけるようにする。 スクリプトが失敗したときに通知が飛ぶ仕組み（監視ツールや終了コードの監視）を用意します。
• 復元の練習をする。 定期的に検証用の環境でリストアを試し、手順と所要時間を確認しておきます。

etcd のスナップショットに含まれないもの

etcd に入っているのは Kubernetes の API オブジェクトだけです。次のものは含まれないため、別にバックアップが必要です。

• 永続ボリューム（PersistentVolume）の中身。 データベースのデータや、WordPress のアップロードファイルなどです。ストレージのスナップショットや Velero などで保存します。
• コンテナイメージ。 レジストリ側で保持します。
• ノードの OS の設定や、etcd の外にある設定ファイル。

逆に、クラスターを作り直す場合でもマニフェストを Git で管理していれば、多くのリソースは再適用で戻せます。etcd のバックアップは、Git にない状態（手動で作ったリソース、Secret、各リソースの状態）を守る最後の手段と考えると、両者の役割を整理しやすくなります。

まとめ

• etcd のバックアップは etcdctl snapshot save、検証と復元は etcdutl を使います。ツールは etcd と同じバージョンにそろえます。
• マネージド Kubernetes では etcd に触れられないため、Velero などで API 経由のバックアップを取ります。
• スナップショットには Secret が含まれます。保存先を限定し、暗号化の鍵は別に保管します。
• リストアは既存のデータディレクトリを残したまま新しいディレクトリに展開し、マニフェストの参照先を書き換えて起動し直します。
• 永続ボリュームの中身は etcd に含まれません。定期実行、ノード外への保存、復元の練習までを運用に組み込みます。

• Kubernetes クラスターのアップグレード手順
• バックアップの3-2-1ルールの考え方