bmctl を使用したクラスタのバックアップと復元

このドキュメントでは、bmctl を使用して、ベアメタル上の Google Distributed Cloud（ソフトウェアのみ）で作成したクラスタをバックアップおよび復元する方法について説明します。これらの手順は、すべてのクラスタタイプに適用されます。

バックアップされるものとバックアップされないもの

bmctl のバックアップと復元のプロセスは Kubernetes コントロール プレーン レイヤで動作し、他のバックアップ ソリューションとは異なります。Kubernetes 以外のバックアップ ソリューションは、ワークロード データ、永続ストレージ、物理マシンのホスト オペレーティング システムをキャプチャします。bmctl のバックアップと復元のプロセスでは、これらの他のコンポーネントをバックアップせずに Kubernetes クラスタを復元します。

コントロール プレーンの状態（bmctl バックアップ プロセスによってバックアップされる）

bmctl は次のオブジェクトをバックアップします。

  • etcd ストア。クラスタの構成と選択した状態（Pod 仕様、デプロイ、ConfigMap、シークレットなど）を定義するすべての Kubernetes リソースとカスタム オブジェクト。
  • PKI 証明書。クラスタ内の安全な通信に使用される証明書。
  • ノード構成ファイルとマニフェスト。クラスタノードに関連する構成。

ワークロードと VM ランタイム ストレージ（bmctl バックアップ プロセスによってバックアップされない）

bmctl は次のデータをバックアップしません。

  • ライブ Pod とコンテナ ランタイムの状態。bmctl は、アクティブなプロセスとメモリ内のアプリケーション データを保存しません。復元後、Kubernetes は etcd 仕様から Pod を再起動します。保存されていないメモリ内の状態は失われます。
  • 永続ボリューム ストレージ。bmctl は、永続ボリューム、ローカル ボリューム プロビジョナー（LVP）によって作成されたボリューム、外部ストレージ ドライバに保存されたデータをバックアップしません。
  • 仮想マシンのディスク。bmctl は、VM 内のデータベース、ファイル、オペレーティング システムの状態など、VM の仮想ハードドライブの内容をバックアップしません。

アプリケーション データと仮想マシンの状態を保護するには、Kubernetes ネイティブまたはゲスト内バックアップ メカニズムを使用する必要があります。基盤となるストレージ ドライバが CSI ボリューム スナップショットをサポートしている場合は、標準の Kubernetes ボリューム スナップショット を使用して、永続ボリュームの特定の時点のコピーを作成します。ストレージの構成の詳細については、ストレージの概要をご覧ください。

VM ランタイム仮想マシンのゲスト オペレーティング システム内でバックアップ エージェントを実行するか、Kubernetes ワークロード内にアプリケーション ネイティブのバックアップ ツールをデプロイします。

物理ホスト オペレーティング システム（サポート対象外）

Google Distributed Cloud ノード上の物理 Linux オペレーティング システムは、使い捨てインフラストラクチャとして扱います。Kubernetes ネットワーク アーキテクチャは、ホストレベルの OS イメージの復元をサポートしていません。そのため、Google は、サードパーティのホストレベルのバックアップ エージェントをホスト OS に直接インストールすることや、OS レベルのイメージ バックアップまたはディスク スナップショットから物理ノードを復元することをサポートしていません。

サードパーティの物理バックアップ エージェントをホスト Linux OS に直接インストールすると、重大なリスクが生じる可能性があります。

多くのバックアップ エージェントは、スナップショット オペレーション中に変更を追跡してローカル ディスクブロックをロックするために、独自のカーネル モジュールまたはブロックレベルのフィルタ ドライバをインストールします。これにより、次の問題が発生する可能性があります。

  • etcd データベースが先行書き込みログに追加できない、ノードのハートビートがタイムアウトする、Raft コンセンサスが失敗する、クラスタが不安定になる。
  • サポートされていないサードパーティのカーネル ドライバが、低レベルのカーネル ルーチンとコンテナ ランタイムと競合し、クラスタのアップグレードが失敗する。
  • イメージ バックアップまたはディスク スナップショットから物理ノードを復元すると、Raft コンセンサス プロトコルに違反する。etcd データベースがコントロール プレーン ノードのログと同期しなくなり、クラスタの状態が大幅に破損する。
  • ワーカーノードが API サーバーの信頼できる情報源と同期しなくなる、Dataplane V2（Cilium）IP アドレスが衝突する、トラフィックがドロップする。

オペレーティング システムまたはハードウェアの障害が発生した物理ノードを復旧するには、OS イメージを復元しないでください。代わりに、クラスタからノードを完全に削除し、クリーンなベース オペレーティング システムを再インストールして、ノードをノードプールに再度追加します。復旧手順の詳細については、 障害が発生したノードをリセットするをご覧ください。

さらにサポートが必要な場合は、 Cloud カスタマーケアにお問い合わせください。 サポート リソースの詳細（以下の内容など）については、サポートを受けるもご覧ください。
  • サポートケースを登録するための要件。
  • 環境構成、ログ、指標など、トラブルシューティングに役立つツール。
  • サポート対象のコンポーネント。

クラスタをバックアップする

bmctl backup cluster コマンドは、クラスタの etcd データと PKI 証明書を tar ファイルにパッケージ化します。etcd データベースは、すべてのクラスタデータの中央データストアであり、クラスタの状態の管理に必要なすべての Kubernetes オブジェクトとカスタム リソースが含まれています。PKI 証明書は TLS で認証します。 このデータは、クラスタのコントロール プレーン、または高可用性（HA）デプロイの コントロール プレーンのいずれかからバックアップされます。

バックアップ tar ファイルには、サービス アカウント キーと SSH 認証鍵を含む機密性の高い認証情報が含まれています。バックアップ ファイルを安全な場所に保存してください。意図しないファイルの公開を防ぐため、Google Distributed Cloud のバックアップ プロセスは、メモリ内ファイルのみを使用します。

クラスタは定期的にバックアップして、スナップショット データが比較的新しくなるようにしてください。バックアップの頻度は、クラスタへの大きな変更の頻度が反映されるように調整します。

クラスタのバックアップに使用する bmctl バージョンは、管理するクラスタのバージョンと一致する必要があります。

クラスタにノード エージェントをインストールした場合は、管理ノードとすべてのターゲット ノードの /tmp ディレクトリに 12 GB の空き容量が必要です。ターゲット ノードの /tmp ディレクトリのサイズを変更できない場合は、ターゲット ノードのローカル ストレージ容量を変更するをご覧ください。管理ノードの /tmp ディレクトリのサイズを変更できない場合は、 管理ノードのローカル ストレージ容量を変更するをご覧ください。

クラスタをバックアップするには:

  1. すべてのノードでの使用中の認証情報と SSH 接続で、クラスタが正常に動作していることを確認します。

    バックアップ プロセスの目的は、既知の正常な状態にあるクラスタをキャプチャして、重大な障害が発生した場合に運用を再開できるようにすることです。

    次のコマンドを使用してクラスタを確認します。

    bmctl check cluster -c CLUSTER_NAME --kubeconfig ADMIN_KUBECONFIG

    次のように置き換えます。

    • CLUSTER_NAME: バックアップを計画するクラスタの名前。
    • ADMIN_KUBECONFIG: 管理クラスタの kubeconfig ファイルのパス。

  2. 次のコマンドを実行して、ターゲット クラスタが整合化状態ではないことを確認します。

    kubectl describe cluster CLUSTER_NAME -n CLUSTER_NAMESPACE --kubeconfig ADMIN_KUBECONFIG

    次のように置き換えます。

    • CLUSTER_NAME: バックアップするクラスタの名前。
    • CLUSTER_NAMESPACE: クラスタの名前空間。デフォルトでは、Google Distributed Cloud のクラスタの Namespace は、先頭に cluster- が付いたクラスタの名前です。たとえば、クラスタに test という名前を付けると、名前空間の名前は cluster-test のようになります。
    • ADMIN_KUBECONFIG: 管理クラスタの kubeconfig ファイルのパス。

  3. コマンド出力の Status セクションで、Conditions のタイプ Reconciling を確認します。

    次の例に示すように、これらの Conditions のステータスが False であれば、クラスタが安定していてバックアップの準備ができていることを意味します。

    ...
Status:
  ...
  Cluster State:  Running
  ...
  Control Plane Node Pool Status:
    ...
    Conditions:
      Last Transition Time:  2023-11-03T16:37:15Z
      Observed Generation:   1
      Reason:                ReconciliationCompleted
      Status:                False
      Type:                  Reconciling
  ...

  4. 次のコマンドを実行して、クラスタをバックアップします。

    bmctl backup cluster -c CLUSTER_NAME --kubeconfig ADMIN_KUBECONFIG

    次のように置き換えます。

    • CLUSTER_NAME: バックアップするクラスタの名前。
    • ADMIN_KUBECONFIG: 管理クラスタの kubeconfig ファイルのパス。

    デフォルトでは、管理ワークステーションのワークスペース ディレクトリ（デフォルトでは bmctl-workspace）に保存されたバックアップ tar ファイルです。tar ファイルの名前は CLUSTER_NAME_backup_TIMESTAMP.tar.gz です。ここで、CLUSTER_NAME はバックアップされるクラスタの名前、TIMESTAMP はバックアップが実行された日時です。たとえば、クラスタ名が testuser の場合、バックアップ ファイルの名前は testuser_backup_2006-01-02T150405Z0700.tar.gz のようになります。

    バックアップ ファイルに異なる名前と場所を指定するには、--backup-file フラグを使用します。

バックアップ ファイルは 1 年経つと期限切れになり、クラスタ復元プロセスは期限切れのバックアップ ファイルでは動作しません。

クラスタを復元する

バックアップからのクラスタの復元は最後の手段です。クラスタにおいて重大な障害が発生したため、他の方法ではサービスに戻ることができない場合に使用する必要があります。たとえば、etcd データが破損している、あるいは etcd Pod がクラッシュ ループの状態にある場合に使用します。

バックアップ tar ファイルには、サービス アカウント キーと SSH 認証鍵を含む機密性の高い認証情報が含まれています。意図しないファイルの公開を防ぐため、Google Distributed Cloud の復元プロセスは、メモリ内ファイルのみを使用します。

クラスタの復元に使用する bmctl バージョンは、管理するクラスタのバージョンと一致している必要があります。

クラスタを復元するには:

  1. バックアップを作成したときにクラスタで使用可能だったすべてのノードマシンが正しく動作し、到達可能であることを確認します。

  2. ノード間の SSH 接続がバックアップ時に使用された SSH 認証鍵で動作することを確認します。

    これらの SSH 認証鍵は、復元プロセスの一環として復元されます。

  3. バックアップ時に使用されたサービス アカウント キーがまだ有効であることを確認します。

    これらのサービス アカウント キーは、復元されたクラスタのために復元されます。

  4. 管理クラスタ、ハイブリッド クラスタ、またはスタンドアロン クラスタを復元するには、次のコマンドを実行します。

    bmctl restore cluster -c CLUSTER_NAME --backup-file BACKUP_FILE

    次のように置き換えます。

    • CLUSTER_NAME: 復元するクラスタの名前。
    • BACKUP_FILE: 使用しているバックアップ ファイルのパスと名前。

  5. ユーザー クラスタを復元するには、次のコマンドを実行します。

    bmctl restore cluster -c CLUSTER_NAME --backup-file BACKUP_FILE \
    --kubeconfig ADMIN_KUBECONFIG

    次のように置き換えます。

    • CLUSTER_NAME: 復元するクラスタの名前。
    • BACKUP_FILE: 使用しているバックアップ ファイルのパスと名前。
    • ADMIN_KUBECONFIG: 管理クラスタの kubeconfig ファイルのパス。

復元プロセスの最後に、復元されたクラスタ用に新しい kubeconfig ファイルが生成されます。

復元が完了したら、次の手順で復元が成功したことを確認します。

  1. 次のコマンドを実行して、生成された kubeconfig ファイルでノードの準備状況とシステム Pod が実行されていることを確認します。

    etcd Pod には次の 2 種類があります。

    • etcd-HOST_NAME（メインの etcd Pod に対応）
    • etcd-events-HOST_NAME（etcd-events Pod に対応）
    kubectl get pods -n kube-system --kubeconfig GENERATED_KUBECONFIG
kubectl get nodes --kubeconfig GENERATED_KUBECONFIG

  2. 各 etcd Pod で、次のコマンドを実行して etcd の健全性を確認します。

    kubectl exec ETCD_POD_NAME -n kube-system \
    --kubeconfig GENERATED_KUBECONFIG \
    -- /bin/sh -c 'ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 \
    --cacert=/etc/kubernetes/pki/etcd/ca.crt --key=/etc/kubernetes/pki/etcd/peer.key \
    --cert=/etc/kubernetes/pki/etcd/peer.crt endpoint health'

    正常な etcd メンバーの場合、レスポンスは次のようになります。

    https://127.0.0.1:2379 is healthy: successfully committed proposal: took = 11.514177ms

  3. 各 etcd-events Pod に対して、次のコマンドを実行して etcd-events の健全性を確認します。

    kubectl exec ETCD_EVENTS_POD_NAME -n kube-system \
    --kubeconfig GENERATED_KUBECONFIG \
    -- /bin/sh -c 'ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2382 \
    --cacert=/etc/kubernetes/pki/etcd/ca.crt --key=/etc/kubernetes/pki/etcd/peer.key \
    --cert=/etc/kubernetes/pki/etcd/peer.crt endpoint health'

    正常な etcd-events メンバーの場合、レスポンスは次のようになります。

    https://127.0.0.1:2382 is healthy: successfully committed proposal: took = 14.308148ms

トラブルシューティング

バックアップまたは復元のプロセスで問題が発生した際は、以降のセクションをトラブルシューティングにお役立てください。

さらにサポートを必要とされる場合は、 Google サポートにお問い合わせください。

バックアップまたは復元中のメモリ不足

バックアップや復元プロセス中に、次のステップで自明または明確でないエラー メッセージが表示されることがあります。bmctl コマンドを実行するワークステーションの RAM が不足している場合は、バックアップまたは復元プロセスを行うためのメモリが不足している可能性があります。

Google Distributed Cloud のバージョン 1.13 以降では、バックアップ コマンドで --use-disk パラメータを使用できます。ファイル権限を保持するために、このパラメータによってファイルの権限が変更されるため、コマンドを実行するユーザーは root ユーザーである必要があります（または sudo を使用します）。

復元中にファイルへの権限がない

復元タスクが正常に終了すると、ブートストラップの削除が、次のようなエラーメッセージで失敗する場合があります。

  Error: failed to restore node config files: sftp: "Failure" (SSH_FX_FAILURE)

このエラーによって、復元に必要な一部のディレクトリが書き込みできない可能性があります。

Google Distributed Cloud バージョン 1.14 以降では、書き込み可能なディレクトリに関するエラー メッセージがより明確になっています。報告されたディレクトリが書き込み可能であることを確認し、必要に応じてディレクトリの権限を更新してください。

バックアップ後に SSH 鍵を更新すると、復元プロセスが中断される

バックアップが行われたに SSH 認証鍵が更新されると、復元プロセス中の SSH 関連のオペレーションが失敗することがあります。この場合、復元プロセスで新しい SSH 認証鍵は無効になります。

この問題を解決するには、元の SSH 認証鍵を一時的に追加してから、復元を実行します。復元プロセスが完了したら、SSH 認証鍵をローテーションできます。

ノード エージェント ノードのバックアップを作成できない

ノード エージェントを使用しているときに、バックアップの作成が失敗してアーカイブ ファイルを作成できないというエラーが表示された場合は、次のようにします。

  I0508 15:29:36.831790  657351 backup_cluster.go:255] Retrying backup node: 128.187.102.133, due to error: failed receive chunk data: rpc error: code = Unknown desc = archiver.CreateArchiveWithList
  failed: failed to create archive file: failed to copy data from file: var/lib/etcd-events/member/snap/db, file size: 26136576, copy bytes: 12478464,
  error: write /tmp/uploadFileTemp1561164777: no space left on device

管理ノードとすべてのターゲット ノードの /tmp ディレクトリに 12 GB の空き容量があることを確認します。ターゲット ノードの /tmp ディレクトリのサイズを変更できない場合は、ノード エージェント バックアップのローカル ストレージ容量を増やすをご覧ください。

管理ノードとすべてのターゲット ノードの /tmp ディレクトリに 12 GB の空き容量があることを確認したら、バックアップをもう一度試してください。