[{"data":1,"prerenderedAt":341},["ShallowReactive",2],{"blog-ja-k3s-etcd-snapshot-restore-token-cluster-reset-pitfalls":3,"blog-related-ja-k3s-etcd-snapshot-restore-token-cluster-reset-pitfalls":290,"blog-ja-k3s-etcd-snapshot-restore-token-cluster-reset-pitfalls-alt":278},{"id":4,"title":5,"author":6,"body":7,"date":272,"description":273,"extension":274,"image":275,"locale":276,"meta":277,"navigation":278,"path":279,"seo":280,"stem":281,"tags":282,"__hash__":289},"blog\u002Fblog\u002Fja\u002Fk3s-etcd-snapshot-restore-token-cluster-reset-pitfalls.md","自動etcdスナップショットは毎日取れていた。K3sのリストアが本番障害で動かなかった理由","Kubo Team",{"type":8,"value":9,"toc":263},"minimark",[10,15,19,26,42,46,66,72,81,90,94,101,107,122,129,133,150,160,176,180,197,203,218,222,225,247,250],[11,12,14],"h2",{"id":13},"毎日自動バックアップは取れていたという安心の作り方","「毎日自動バックアップは取れていた」という安心の作り方",[16,17,18],"p",{},"K3sのetcdスナップショットは、デフォルトで12時間おきに自動実行され、直近5世代がローカルまたはS3に保存される。監視ダッシュボードにスナップショット成功のログが並んでいれば、多くのチームは「バックアップは万全」と判断するだろう。",[16,20,21],{},[22,23],"img",{"alt":24,"src":25},"section01","https:\u002F\u002Fcdn.kubo.hexabase.io\u002Fimages\u002Fblog\u002Fja\u002Fk3s-etcd-snapshot-restore-token-cluster-reset-pitfalls\u002Fsection01.webp",[16,27,28,29,36,37,41],{},"だが実際にK3sクラスタが本番障害でリストアを必要とした瞬間、そのスナップショットが役に立たないケースが少なくない。",[30,31,35],"a",{"href":32,"rel":33},"https:\u002F\u002Fkubernetes.io\u002Fdocs\u002Ftasks\u002Fadminister-cluster\u002Fconfigure-upgrade-etcd\u002F",[34],"nofollow","Kubernetes公式ドキュメント","も「etcdを使うクラスタでは必ずバックアップ計画を持つこと」と明記しているが、計画の中身、特に",[38,39,40],"strong",{},"リストア手順","まで検証しているチームは意外と少ない。K3s etcd リストア 失敗の典型パターンを3つ、実際の障害報告をもとに整理する。",[11,43,45],{"id":44},"罠1-サーバートークンを控えていないとスナップショットはただの暗号化データになる","罠1: サーバートークンを控えていないと、スナップショットはただの暗号化データになる",[16,47,48,49,54,55,60,61,65],{},"K3sのetcdスナップショットは、サーバー参加トークンから導出したAES-256鍵で暗号化されている。",[30,50,53],{"href":51,"rel":52},"https:\u002F\u002Fdocs.k3s.io\u002Fcli\u002Fetcd-snapshot",[34],"K3s公式のetcd-snapshotドキュメント","によれば、新しいホストにリストアする際は元のトークン値を明示的に指定する必要があり、",[30,56,59],{"href":57,"rel":58},"https:\u002F\u002Fdocs.k3s.io\u002Fdatastore\u002Fbackup-restore",[34],"Backup and Restoreドキュメント","でも「",[62,63,64],"code",{},"\u002Fvar\u002Flib\u002Francher\u002Fk3s\u002Fserver\u002Ftoken"," を必ずバックアップ対象に含めること。同じトークン値を使わないとスナップショットが使用不可になる」と警告されている。",[16,67,68],{},[22,69],{"alt":70,"src":71},"section02","https:\u002F\u002Fcdn.kubo.hexabase.io\u002Fimages\u002Fblog\u002Fja\u002Fk3s-etcd-snapshot-restore-token-cluster-reset-pitfalls\u002Fsection02.webp",[16,73,74,75,80],{},"この落とし穴が実際に問題化した例が",[30,76,79],{"href":77,"rel":78},"https:\u002F\u002Fgithub.com\u002Fk3s-io\u002Fk3s\u002Fissues\u002F4522",[34],"K3sのGitHub Issue #4522","だ。トークンフラグを指定せずにリストアを実行すると、原因を示さない空白のFATALエラーで処理が止まる。スナップショットファイル自体は無傷でも、トークンという「鍵」を紛失していれば復元は成立しない。バックアップ対象をetcdスナップショットのファイルだけに絞っているチームは、まずここを見直す価値がある。",[16,82,83,84,89],{},"こうしたトークンやスナップショットの保管・世代管理を人力の手順書に依存させず、運用そのものを構造化したいなら、",[30,85,88],{"href":86,"rel":87},"https:\u002F\u002Fkubo.hexabase.io\u002F",[34],"Kubo","のようなマネージドK3sという選択肢もある。",[11,91,93],{"id":92},"罠2-s3からのリストアが逆に全データを消すことがある","罠2: S3からのリストアが、逆に全データを消すことがある",[16,95,96,97,100],{},"K3sはオンデマンド・定期スナップショットをS3互換ストレージへ自動アップロードできる。",[30,98,59],{"href":57,"rel":99},[34],"によればリストア処理はS3からのダウンロード→展開→既存etcdディレクトリの削除・退避→スナップショット内容の抽出、という順序で進む。",[16,102,103],{},[22,104],{"alt":105,"src":106},"section03","https:\u002F\u002Fcdn.kubo.hexabase.io\u002Fimages\u002Fblog\u002Fja\u002Fk3s-etcd-snapshot-restore-token-cluster-reset-pitfalls\u002Fsection03.webp",[16,108,109,110,115,116,121],{},"この手順のどこかで設定や前提を誤ると、復旧のつもりが新たなデータ損失を招く。実際に",[30,111,114],{"href":112,"rel":113},"https:\u002F\u002Fgithub.com\u002Francher\u002Francher\u002Fissues\u002F42251",[34],"rancher\u002FrancherのGitHub Issue #42251","では、S3からのetcdスナップショットリストアがクラスタの全データを消してしまう不具合が報告されている。",[30,117,120],{"href":118,"rel":119},"https:\u002F\u002Fetcd.io\u002Fdocs\u002Fv3.5\u002Fop-guide\u002Frecovery\u002F",[34],"etcd公式の障害復旧ガイド","も、リストア後は全メンバーが同一スナップショットを使い、新しい論理クラスタとして起動する必要があると強調しており、この前提がずれるとクラスタ全体が不整合な状態に陥る。",[16,123,124,125,128],{},"中盤のCTAとしても触れておきたいが、こうしたリストア手順そのものを可視化し、ブラックボックスにしないという点で、Kubo Cloudの",[30,126,88],{"href":86,"rel":127},[34],"はCaptain UIによる運用状態の可視化を標準搭載している。手順書と実際のクラスタ状態が乖離するリスクを減らしたいチームには参考になるはずだ。",[11,130,132],{"id":131},"罠3-cluster-resetのreset-flagを甘く見ると復旧のはずが詰む","罠3: cluster-resetのreset-flagを甘く見ると、復旧のはずが詰む",[16,134,135,136,139,140,145,146,149],{},"全ノード喪失など深刻な障害からの復旧では、",[62,137,138],{},"k3s server --cluster-reset --cluster-reset-restore-path=\u003Csnapshot>"," でリセットとリストアを同時実行する。",[30,141,144],{"href":142,"rel":143},"https:\u002F\u002Fdocs.k3s.io\u002Fcli\u002Fserver",[34],"K3sのserverコマンドリファレンス","では、",[62,147,148],{},"--cluster-reset"," は「既存のピア情報をすべて忘れ、新しいクラスタの唯一のメンバーになる」機能と説明されている。",[151,152,157],"pre",{"className":153,"code":155,"language":156},[154],"language-text","# 全ノード喪失時のリセット＋リストア例\nk3s server --cluster-reset --cluster-reset-restore-path=\u002Fvar\u002Flib\u002Francher\u002Fk3s\u002Fserver\u002Fdb\u002Fsnapshots\u002Fetcd-snapshot-xxxx\n","text",[62,158,155],{"__ignoreMap":159},"",[16,161,162,163,168,169,172,173,175],{},"このリセット処理は、誤って複数回実行されることを防ぐための安全機構を伴う。",[30,164,167],{"href":165,"rel":166},"https:\u002F\u002Fgithub.com\u002Fk3s-io\u002Fk3s\u002Fdiscussions\u002F9788",[34],"K3sのGitHub Discussion","では ",[62,170,171],{},"--cluster-init"," と ",[62,174,148],{}," の挙動の違いが議論されており、フラグの意味を正確に理解しないまま手順を進めると、リセット後にクラスタが正常起動しない状態にはまりやすいことが分かる。障害対応の緊張状態でこの種のフラグの意味を初めて調べることになれば、復旧時間はさらに伸びる。",[11,177,179],{"id":178},"haクラスタが守るのはノード障害であってデータ損失ではない","HAクラスタが守るのは「ノード障害」であって「データ損失」ではない",[16,181,182,183,186,187,192,193,196],{},"K3sのHA embedded etcd構成では、n台のサーバーノードに対してクォーラムは ",[62,184,185],{},"(n\u002F2)+1"," で計算される。",[30,188,191],{"href":189,"rel":190},"https:\u002F\u002Fdocs.k3s.io\u002Fdatastore\u002Fha-embedded",[34],"K3s公式のHA embedded etcdドキュメント","は奇数ノード構成を推奨しており、3ノードなら1台、5ノードなら2台までの障害に耐えられると説明する。",[30,194,35],{"href":32,"rel":195},[34],"も本番環境では奇数メンバー構成、できれば5メンバークラスタを推奨し、さらに「etcdへのアクセスはクラスタのroot権限と同等」であるとして、アクセス制御の重要性を強調している。",[16,198,199],{},[22,200],{"alt":201,"src":202},"section04","https:\u002F\u002Fcdn.kubo.hexabase.io\u002Fimages\u002Fblog\u002Fja\u002Fk3s-etcd-snapshot-restore-token-cluster-reset-pitfalls\u002Fsection04.webp",[16,204,205,206,211,212,217],{},"ここで陥りやすい誤解が、「3台構成でHAにしているから安心」という思い込みだ。HAが守るのは特定ノードの物理的・一時的な障害であり、設定ミスの横展開や同時多発的なストレージ障害、あるいは3台すべてを巻き込む人為的ミスにはHAだけでは対応できない。",[30,207,210],{"href":208,"rel":209},"https:\u002F\u002Franchermanager.docs.rancher.com\u002Fhow-to-guides\u002Fnew-user-guides\u002Fbackup-restore-and-disaster-recovery\u002Frestore-rancher-launched-kubernetes-clusters-from-backup",[34],"Rancherの公式リストアガイド","でも、control planeとetcdノードが完全に失われた場合の復旧手順は「既存のetcdノードをすべて削除してから新規ノードを追加する」という、通常のノード交換とは異なる複雑な手順が必要になると説明されている。こうした複雑な復旧手順を運用チームの暗黙知に頼るのではなく、",[30,213,216],{"href":214,"rel":215},"https:\u002F\u002Fwww.hexabase.com\u002Fproduct\u002Fkubo\u002Fon-premise",[34],"Kubo On-Premise","のようにデータ主権を保ちながら運用そのものをマネージド化する選択肢を検討する価値もある。",[11,219,221],{"id":220},"まとめ-リストアは訓練されて初めてバックアップになる","まとめ: リストアは訓練されて初めてバックアップになる",[16,223,224],{},"K3sのembedded etcdバックアップには、少なくとも3つの構造的な罠がある。",[226,227,228,235,241],"ul",{},[229,230,231,234],"li",{},[38,232,233],{},"トークン管理",": スナップショットはトークン由来の鍵で暗号化されており、トークンを控えていなければ復号できない",[229,236,237,240],{},[38,238,239],{},"S3リストアの手順",": ダウンロード→展開→削除→抽出という流れのどこかでミスがあれば、復旧が新たなデータ損失に変わりうる",[229,242,243,246],{},[38,244,245],{},"cluster-resetの理解不足",": フラグの意味を正確に把握していないと、緊急時に復旧そのものが止まる",[16,248,249],{},"いずれも「スナップショットが取れているか」ではなく「そのスナップショットを実際にリストアできるか」という一段深い問いに関わる。四半期に一度でもステージング環境でリストア訓練を行い、トークン管理・手順書・所要時間を検証しておくことが、本番障害での復旧時間を左右する。",[16,251,252,253,256,257,262],{},"こうした検証・運用そのものを自前で回し続ける負荷を減らしたいなら、",[30,254,88],{"href":86,"rel":255},[34],"のマネージドK3sという選択肢を検討してみてほしい。まずは",[30,258,261],{"href":259,"rel":260},"https:\u002F\u002Fwww.hexabase.com\u002Fcontact-us\u002F",[34],"お問い合わせ","から、現在のバックアップ・リストア運用について相談することもできる。",{"title":159,"searchDepth":264,"depth":264,"links":265},2,[266,267,268,269,270,271],{"id":13,"depth":264,"text":14},{"id":44,"depth":264,"text":45},{"id":92,"depth":264,"text":93},{"id":131,"depth":264,"text":132},{"id":178,"depth":264,"text":179},{"id":220,"depth":264,"text":221},"2026-09-21","K3sのetcdスナップショットは正常に取れていたのに、本番障害でリストアが失敗した——トークン管理、S3リストア事故、cluster-resetの落とし穴という3つの実例から、embedded etcdバックアップの本当のリスクを解説する。","md","https:\u002F\u002Fcdn.kubo.hexabase.io\u002Fimages\u002Fblog\u002Fja\u002Fk3s-etcd-snapshot-restore-token-cluster-reset-pitfalls\u002Ftitle.webp","ja",{},true,"\u002Fblog\u002Fja\u002Fk3s-etcd-snapshot-restore-token-cluster-reset-pitfalls",{"title":5,"description":273},"blog\u002Fja\u002Fk3s-etcd-snapshot-restore-token-cluster-reset-pitfalls",[283,284,285,286,287,288],"k3s","kubernetes","etcd","backup-restore","disaster-recovery","high-availability","mzkJsOWmcG64N4KfDa-Ex3PvL40xWXs5nGyL4hwNuQk",[291,298,306,315,324,333],{"path":292,"title":293,"description":294,"date":295,"tags":296},"\u002Fblog\u002Fja\u002Fk3s-kubeadm-ha-etcd-failover-rto-gap","RTO30秒のはずが3分止まった。K3sとkubeadmのHA構成で\"カタログ値\"と\"実運用\"がズレる理由","K3sのembedded etcdとkubeadmのstacked\u002Fexternal etcd、HA構成のフェイルオーバーは実際どれだけ時間がかかるのか。公式ドキュメントのRTO目安と実運用の体感時間のギャップを、障害ドメインの分離・必要ノード数の違いから検証する。","2026-10-09",[283,284,285,288,297],"kubeadm",{"path":299,"title":300,"description":301,"date":302,"tags":303},"\u002Fblog\u002Fja\u002Fk3s-proxmox-live-migration-etcd-quorum-affinity-design","Proxmoxのライブマイグレーションで、K3sのetcdクォーラムが静かに崩れる。仮想化とRaftが衝突する設計","Proxmox上のK3sコントロールプレーンVMをライブマイグレーションした際にetcdクォーラムが崩れる仕組みを、heartbeat\u002Felection-timeoutとProxmoxのaffinity設計から解説。実運用で使える具体的な対策手順を紹介する。","2026-09-09",[283,284,304,285,305,288],"proxmox","live-migration",{"path":307,"title":308,"description":309,"date":310,"tags":311},"\u002Fblog\u002Fja\u002Fk3s-sealed-secrets-gitops-rebuild-private-key-lost","GitOpsで全部コード化してたのに。K3sクラスタを作り直したら、Sealed Secretsが一つも復号できなくなった理由","K3sクラスタをGitOpsで再構築したらSealed Secretsが全て復号できない状態に陥った。原因は秘密鍵の扱いにある。障害の仕組みと復旧手順、再発防止の運用設計を解説する。","2026-10-15",[283,284,312,313,314,287],"sealed-secrets","secrets-management","gitops",{"path":316,"title":317,"description":318,"date":319,"tags":320},"\u002Fblog\u002Fja\u002Fk3s-velero-backup-restore-local-path-provisioner-empty-pvc","毎晩\"Completed\"と出ていたVeleroのバックアップ。K3sでリストアしたらPVCが空だった理由","K3s標準のlocal-path-provisionerはCSIスナップショット非対応。Veleroのバックアップが\"Completed\"でも、障害時のリストアでPVCが空になることがある。原因の切り分けとFile System Backup・リストアドリルによる対策を解説する。","2026-10-13",[283,284,321,322,287,323],"velero","backup","csi",{"path":325,"title":326,"description":327,"date":328,"tags":329},"\u002Fblog\u002Fja\u002Fk3s-rke2-migration-production-downtime-cis-ha","K3sをRKE2に移行して本番が2時間止まった。\"軽量K8s\"選定で見落とされがちな前提","K3s vs RKE2の選定で見落とされがちな前提を、実際の移行障害事例とCIS Hardening・HA構成・ストレージ設計の違いから整理し、本番環境でどちらのKubernetesディストリビューションを選ぶべきか判断基準を具体的に解説する。","2026-10-05",[283,330,284,331,288,332],"rke2","cis-benchmark","production-kubernetes",{"path":334,"title":335,"description":336,"date":337,"tags":338},"\u002Fblog\u002Fja\u002Fk3s-proxmox-storage-expansion-sata-scsi-pitfall","Proxmoxのディスクを無停止で拡張したつもりが、K3sノードには反映されなかった。SATAコントローラという見落とし","Proxmoxで本番運用中のK3sクラスタのストレージが逼迫した時、無停止で拡張したつもりが反映されない典型的な原因(ディスクコントローラ設定)と、CephでOSDを追加する際にK3sのetcdクォーラムが受ける影響、公式ドキュメントに基づく正しい拡張手順を具体的に解説する。","2026-09-17",[283,284,304,339,340,285],"storage","ceph",1792592605127]