この文書は自動機械翻訳技術を使用して翻訳されています。 正確な翻訳を提供するように努めておりますが、翻訳された内容の完全性、正確性、信頼性については一切保証いたしません。 相違がある場合は、元の英語版 英語 が優先され、正式なテキストとなります。

k3s etcd-snapshot

このページでは、k3s etcd-snapshot CLIツールを使用してetcdスナップショットを管理し、etcdスナップショットから復元する方法について説明します。

K3s etcdスナップショットはノードのファイルシステムに保存され、災害復旧シナリオのためにS3互換のオブジェクトストアにアップロードすることもできます。スナップショットは、定期的に自動化されることも、手動でオンデマンドで取得されることもあります。k3s etcd-snapshot CLIツールは、スナップショットを作成、削除、管理するために使用できる一連のサブコマンドを提供します。

サブコマンド 説明

delete

指定されたスナップショットを削除する

ls、list、l

スナップショットの一覧

prune

設定された保持数を超えるスナップショットを削除する

save

オンデマンドでetcdスナップショットをトリガーする

etcdスナップショットサブコマンドに関する追加情報は、`k3s etcd-snapshot --help`を実行してください。

スナップショットの作成

  • スケジュール済

  • オンデマンド

スケジュールされたスナップショットはデフォルトで有効で、システム時間の00:00と12:00に実行され、5つのスナップショットが保持されます。スケジュールされたスナップショットは、`etcd-snapshot`で始まり、ノード名とタイムスタンプが続く名前を持っています。

以下のオプションは、スケジュールされたスナップショットの操作を制御します：

フラグ 説明

--etcd-disable-snapshots

スケジュールされたスナップショットを無効にします。

--etcd-snapshot-name

etcdスケジュールされたスナップショットの基本名を設定します。（デフォルト：etcd-snapshot）

--etcd-snapshot-compress

etcdスナップショットを圧縮します。

--etcd-snapshot-dir

dbスナップショットを保存するディレクトリ。（デフォルトの場所：$<data-dir>/db/snapshots）

--etcd-snapshot-retention

保持するスナップショットの数。(デフォルト：5)

--etcd-snapshot-schedule-cron

cron仕様でのスナップショット間隔時間。例えば、5時間ごとに`0 */5 * * *（デフォルト：`0 */12 * * *）。

data-dirの値はデフォルトで`/var/lib/rancher/k3s`に設定されており、`--data-dir`フラグを設定することで独立して変更できます。

スケジュールされたスナップショットは、サーバーの`--etcd-snapshot-dir`値で設定されたパスに保存されます。S3互換のオブジェクトストアに複製したい場合は、S3設定オプションを参照してください。

スナップショットは`k3s etcd-snapshot save`コマンドを実行することで手動で保存できます。これらのオンデマンドスナップショットには保持期間がなく、ユーザーは`k3s etcd-snapshot delete`または`k3s etcd-snapshot prune`コマンドを使用して手動で削除する必要があります。オンデマンドスナップショットの名前は`on-demand`で始まり、ノード名とタイムスタンプが続きます。

以下のオプションは、オンデマンドスナップショットの操作を制御します：

フラグ 説明

--name

etcdオンデマンドスナップショットのベース名を設定します。（デフォルト：on-demand）

--etcd-snapshot-compress

etcdスナップショットを圧縮します。

--etcd-snapshot-dir

dbスナップショットを保存するディレクトリ。（デフォルトの場所：$<data-dir>/db/snapshots）

data-dirの値はデフォルトで`/var/lib/rancher/k3s`に設定されており、`--data-dir`フラグを設定することで独立して変更できます。

--name`フラグは`k3s etcd-snapshot save`コマンドを実行しているときのみ設定できます。他の2つも`k3s server 設定ファイルの一部となることができます。

オンデマンドスナップショットは、サーバーの`--etcd-snapshot-dir`値で設定されたパスに保存されます。S3互換のオブジェクトストアに複製したい場合は、S3設定オプションを参照してください。

スナップショットの削除

スケジュールされたスナップショットは、スナップショットの数が設定された保持カウント（デフォルトは5）を超えると自動的に削除されます。最も古いスナップショットが最初に削除されます。

スケジュールされたスナップショットまたはオンデマンドスナップショットを手動で削除するには、`k3s etcd-snapshot delete`コマンドを使用できます：

k3s etcd-snapshot delete <SNAPSHOT-NAME-1> <SNAPSHOT-NAME-2> ...

prune`サブコマンドは、名前のプレフィックス（デフォルトは`on-demand）に一致し、設定された保持カウントを超えるスナップショットを削除します。保持カウントを設定するためのフラグ`--snapshot-retention`が含まれています。スケジュールされたスナップショットの場合、デフォルトの保持ポリシーを上書きします。オンデマンドスナップショットには保持ポリシーがなく、このフラグが必要です。

"オンデマンド"スナップショットを少ない数に削減します：

k3s etcd-snapshot prune --snapshot-retention  <NUM-OF-SNAPSHOTS-TO-RETAIN>

"スケジュールされた"スナップショットを少ない数に削減します：

k3s etcd-snapshot prune --name etcd-snapshot --etcd-snapshot-retention <NUM-OF-SNAPSHOTS-TO-RETAIN>

S3互換オブジェクトストアのサポート

K3sは、etcdスナップショットをS3互換オブジェクトストアに複製し、そこから復元することをサポートしています。S3のサポートは、オンデマンドスナップショットとスケジュールされたスナップショットの両方で利用可能です。

フラグ 説明

--etcd-s3

S3へのバックアップを有効にします

--etcd-s3-endpoint

S3エンドポイントURL

--etcd-s3-endpoint-ca

S3エンドポイントに接続するためのS3カスタムCA証明書

--etcd-s3-skip-ssl-verify

S3のSSL証明書検証を無効にします

--etcd-s3-access-key

S3アクセスキー

--etcd-s3-secret-key

S3シークレットキー

--etcd-s3-bucket

S3バケット名

--etcd-s3-region

S3リージョン/バケットの場所（オプション）。デフォルトは`us-east-1`です。

--etcd-s3-folder

S3フォルダー

--etcd-s3-proxy

S3に接続する際に使用するプロキシサーバー、プロキシ関連の環境変数を上書きします

--etcd-s3-insecure

HTTPS経由のS3を無効にします

--etcd-s3-timeout

S3タイムアウト (デフォルト: 5m0s)

--etcd-s3-config-secret

etcd-s3 が有効で、他の etcd-s3 オプションが設定されていない場合に、S3 を構成するために kube-system ネームスペース内で使用される秘密の名前

例えば、S3 でのオンデマンド etcd スナップショットの作成と削除は次のように機能します:

$ k3s etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret save
INFO[0155] Snapshot on-demand-server-0-1753178523 saved.
INFO[0155] Snapshot on-demand-server-0-1753178523 saved.

$ k3s etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret ls
Name                              Location                                                                          Size    Created
on-demand-server-0-1753178523     s3://test-bucket/test-folder/on-demand-server-0-1753178523                        5062688 2025-07-22T10:02:03Z
on-demand-server-0-1753178523     file:///var/lib/rancher/k3s/server/db/snapshots/on-demand-server-0-1753178523     5062688 2025-07-22T10:02:03Z

$ k3s etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret delete on-demand-server-0-1753178523
INFO[0000] Snapshot on-demand-server-0-1753178523 deleted.

$ k3s etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret ls
Name                              Location                                                                          Size    Created

S3 保持

バージョンゲート

バージョン v1.34.0+k3s1、v1.33.4+k3s1、v1.32.8+k3s1、v1.31.12+k3s1 から、K3s には S3 保持のための新しいフラグが含まれています。それはローカルスナップショット保持と同じデフォルト値を持っています。
フラグ 説明

--etcd-s3-retention

保持する S3 のスナップショットの数。（デフォルト：5）

S3 構成秘密のサポート

バージョンゲート

S3 構成秘密のサポートは、2024年8月のリリース： v1.30.4+k3s1、v1.29.8+k3s1、v1.28.13+k3s1 から利用可能です。

K3s は Kubernetes Secret から etcd S3 スナップショット構成を読み取ることをサポートしています。 これは、セキュリティ上の理由から K3s CLI フラグや設定ファイルに資格情報をハードコーディングするよりも好まれる場合があります。また、K3s を再起動せずに資格情報をローテーションする必要がある場合にも適しています。 Secret を介して S3 スナップショット構成を渡すには、--etcd-s3 と --etcd-s3-config-secret=<SECRET-NAME> で K3s を起動します。 K3s が起動する際に Secret は存在する必要はありませんが、スナップショットの保存/リスト/削除/プルーニング操作が行われるたびにチェックされます。

S3 構成 Secret はスナップショットを復元する際には使用できません。なぜなら、復元中に秘密を提供するための apiserver が利用できないからです。 S3 に保存されたスナップショットを復元する際には、CLI を介して S3 構成を渡す必要があります。

Secret を有効にするには、--etcd-s3 と --etcd-s3-config-secret フラグのみを渡してください。 他の S3 構成フラグが設定されている場合、Secret は無視されます。

Secret 内のキーは、上記の --etcd-s3-* CLI フラグに対応しています。 etcd-s3-endpoint-ca キーは PEM エンコードされた CA バンドルを受け入れます。また、etcd-s3-endpoint-ca-name キーを使用して、kube-system ネームスペース内にある 1 つ以上の PEM エンコードされた CA バンドルを含む ConfigMap の名前を指定することができます。

apiVersion: v1
kind: Secret
metadata:
  name: k3s-etcd-snapshot-s3-config
  namespace: kube-system
type: etcd.k3s.cattle.io/s3-config-secret
stringData:
  etcd-s3-endpoint: ""
  etcd-s3-endpoint-ca: ""
  etcd-s3-endpoint-ca-name: ""
  etcd-s3-skip-ssl-verify: "false"
  etcd-s3-access-key: "AWS_ACCESS_KEY_ID"
  etcd-s3-secret-key: "AWS_SECRET_ACCESS_KEY"
  etcd-s3-bucket: "bucket"
  etcd-s3-folder: "folder"
  etcd-s3-region: "us-east-1"
  etcd-s3-insecure: "false"
  etcd-s3-timeout: "5m"
  etcd-s3-proxy: ""

スナップショットの復元

K3sはスナップショットを復元する際にいくつかのステップを実行します：

  1. スナップショットがS3に保存されている場合、ファイルはスナップショットディレクトリにダウンロードされます。

  2. スナップショットが圧縮されている場合、解凍されます。

  3. 存在する場合、現在のetcdデータベースファイルは`<data-dir>/server/db/etcd-old-$TIMESTAMP/`に移動されます。

  4. スナップショットの内容がディスクに抽出され、チェックサムが検証されます。

  5. Etcdが起動し、現在のノードを除くすべてのetcdクラスターのメンバーがクラスターから削除されます。

  6. CA証明書やその他の機密データがデータストアから抽出され、後で使用するためにディスクに書き込まれます。

  7. 復元が完了し、K3sは復元が行われたサーバーで再起動して通常通り使用できます。

  8. （オプション）エージェントとコントロールプレーンサーバーは通常通り起動できます。

  9. （オプション）古いデータベースファイルを削除した後、etcdサーバーを再起動してクラスターに再参加できます。

スナップショットを復元する際、作成時と同じK3sバージョンを使用する必要はありません。より高いマイナーバージョンも使用可能です。

スナップショット復元手順

クラスター構成に一致するタブを以下から選択してください。

  • 単一サーバー

  • 複数のサーバ

  1. K3sサービスを停止します：

    systemctl stop k3s

  2. k3s server`を--cluster-reset`フラグで実行し、--cluster-reset-restore-path`で復元するスナップショットのパスを指定します。 スナップショットがS3に保存されている場合、S3設定フラグ（--etcd-s3`、`--etcd-s3-bucket`など）を提供し、復元パスとしてスナップショットのファイル名のみを指定します。

    復元するスナップショットを指定せずに`--cluster-reset`フラグを使用すると、スナップショットを復元せずにetcdクラスターを単一メンバーにリセットします。

    		 
    k3s server \
  --cluster-reset \
  --cluster-reset-restore-path=<PATH-TO-SNAPSHOT>

    結果:K3sはスナップショットを復元し、クラスターのメンバーシップをリセットし、再起動の準備ができたことを示すメッセージを表示します：
    Managed etcd cluster membership has been reset, restart without --cluster-reset flag now.

  3. K3sを再起動します：

    systemctl start k3s

K3sの設定ファイル内にetcd-s3バックアップ構成が定義されている場合、K3sの復元は設定されたS3バケットからスナップショットファイルを取得しようとします。この場合、引数`--cluster-reset-restore-path`にはスナップショットファイル名のみを渡す必要があります。etcd-s3バックアップ構成が存在するローカルスナップショットファイルから復元するには、引数`--etcd-s3=false`を追加し、引数`--cluster-reset-restore-path`にローカルスナップショットファイルのフルパスを渡します。

安全機構として、K3sがクラスターをリセットするとき、`/var/lib/rancher/k3s/server/db/reset-flag`に空のファイルを作成し、ユーザーが連続して複数のクラスターリセットを誤って実行するのを防ぎます。このファイルはK3sが通常通り起動すると削除されます。

この例では、3つのサーバー、S1、S2、`S3`があります。スナップショットは`S1`にあります。

  1. すべてのサーバでK3sを停止します:

    systemctl stop k3s

  2. S1で、k3s server`を--cluster-reset`オプションで実行し、--cluster-reset-restore-path`には復元するスナップショットへのパスを指定します。 スナップショットがS3に保存されている場合、S3設定フラグ（--etcd-s3`、`--etcd-s3-bucket`など）を提供し、復元パスにはスナップショットのファイル名のみを指定します。

    復元するスナップショットを指定せずに`--cluster-reset`フラグを使用すると、スナップショットを復元せずにetcdクラスターを単一メンバーにリセットします。

    		 
    k3s server \
  --cluster-reset \
  --cluster-reset-restore-path=<PATH-TO-SNAPSHOT>

    結果:K3sはスナップショットを復元し、クラスターのメンバーシップをリセットし、再起動の準備ができたことを示すメッセージを表示します: Managed etcd cluster membership has been reset, restart without --cluster-reset flag now. Backup and delete ${datadir}/server/db on each peer etcd server and rejoin the nodes.

  3. S1でK3sを再起動します:

    systemctl start k3s

  4. S2とS3では、`/var/lib/rancher/k3s/server/db/`にあるデータディレクトリを削除します:

    rm -rf /var/lib/rancher/k3s/server/db/

  5. S2とS3で、復元されたクラスターに参加するためにK3sを再起動します:

    systemctl start k3s

K3sの設定ファイル内にetcd-s3バックアップ構成が定義されている場合、K3sの復元は設定されたS3バケットからスナップショットファイルを取得しようとします。この場合、引数`--cluster-reset-restore-path`にはスナップショットのファイル名のみを渡す必要があります。etcd-s3バックアップ構成が存在するローカルスナップショットファイルから復元するには、引数`--etcd-s3=false`を追加し、引数`--cluster-reset-restore-path`にローカルスナップショットファイルのフルパスを渡します。

安全機構として、K3sがクラスターをリセットするとき、`/var/lib/rancher/k3s/server/db/reset-flag`に空のファイルを作成し、ユーザーが連続して複数のクラスターリセットを誤って実行するのを防ぎます。このファイルはK3sが通常通り起動すると削除されます。

新しいホストへの復元

etcdスナップショットを取得したホストとは異なるホストに復元することが可能です。その際、スナップショットを取得する際に元々使用されたサーバートークンを渡す必要があります。これはスナップショット内のブートストラップデータを復号化するために使用されます。プロセスは上記と同じですが、ステップ2を次のように変更します:

  1. スナップショットを取得したノードで、次の値を保存します: /var/lib/rancher/k3s/server/token.これはステップ3の`<BACKED-UP-TOKEN-VALUE>`です。

  2. スナップショットを新しいノードにコピーしてください。ノード内のパスはステップ3の`<PATH-TO-SNAPSHOT>`です。

  3. 次のコマンドを使用して、最初のサーバーノードからスナップショットの復元を開始してください：

    k3s server \
  --cluster-reset \
  --cluster-reset-restore-path=<PATH-TO-SNAPSHOT>
  --token=<BACKED-UP-TOKEN-VALUE>

    トークンの値はK3sの設定ファイルにも設定できます。

  1. ノードのリソースもそのetcdスナップショットに含まれています。新しいノードセットに復元する場合、クラスターに存在しないすべての古いノードを手動で削除する必要があります。

  2. K3sの設定ファイルにトークンが設定されている場合、それが`<BACKED-UP-TOKEN-VALUE>`と同じであることを確認してください。そうでないと、K3sは起動に失敗します。

ETCDスナップショットファイル カスタムリソース

バージョンゲート

ETCDスナップショットファイルは、2023年11月のリリースから利用可能です：v1.28.4+k3s2、v1.27.8+k3s2、v1.26.11+k3s2、v1.25.16+k3s4。

スナップショットは、クラスター範囲の`ETCDSnapshotFile`リソースをリストまたは説明することで、任意のKubernetesクライアントを使用してリモートで表示できます。`k3s etcd-snapshot list`コマンドがそのノードに表示されるスナップショットのみを表示するのとは異なり、`ETCDSnapshotFile`リソースはクラスターのメンバーに存在するすべてのスナップショットを追跡します。

$ kubectl get etcdsnapshotfile
NAME                                             SNAPSHOTNAME                        NODE           LOCATION                                                                            SIZE      CREATIONTIME
local-on-demand-k3s-server-1-1730308816-3e9290   on-demand-k3s-server-1-1730308816   k3s-server-1   file:///var/lib/rancher/k3s/server/db/snapshots/on-demand-k3s-server-1-1730308816   2891808   2024-10-30T17:20:16Z
s3-on-demand-k3s-server-1-1730308816-79b15c      on-demand-k3s-server-1-1730308816   s3             s3://etcd/k3s-test/on-demand-k3s-server-1-1730308816                                2891808   2024-10-30T17:20:16Z
$ kubectl describe etcdsnapshotfile s3-on-demand-k3s-server-1-1730308816-79b15c
Name:         s3-on-demand-k3s-server-1-1730308816-79b15c
Namespace:
Labels:       etcd.k3s.cattle.io/snapshot-storage-node=s3
Annotations:  etcd.k3s.cattle.io/snapshot-token-hash: b4b83cda3099
API Version:  k3s.cattle.io/v1
Kind:         ETCDSnapshotFile
Metadata:
  Creation Timestamp:  2024-10-30T17:20:16Z
  Finalizers:
    wrangler.cattle.io/managed-etcd-snapshots-controller
  Generation:        1
  Resource Version:  790
  UID:               bec9a51c-dbbe-4746-922e-a5136bef53fc
Spec:
  Location:   s3://etcd/k3s-test/on-demand-k3s-server-1-1730308816
  Node Name:  s3
  s3:
    Bucket:           etcd
    Endpoint:         s3.example.com
    Prefix:           k3s-test
    Region:           us-east-1
    Skip SSL Verify:  true
  Snapshot Name:      on-demand-k3s-server-1-1730308816
Status:
  Creation Time:  2024-10-30T17:20:16Z
  Ready To Use:   true
  Size:           2891808
Events:
  Type    Reason               Age   From            Message
  ----    ------               ----  ----            -------
  Normal  ETCDSnapshotCreated  113s  k3s-supervisor  Snapshot on-demand-k3s-server-1-1730308816 saved on S3