クラスタの作成またはアップグレードのトラブルシューティング

このページでは、Google Distributed Cloud でクラスタの作成とアップグレードに関する問題を調査する方法について説明します。

さらにサポートが必要な場合は、Cloud カスタマーケアにお問い合わせください。

インストールに関する問題

以下のセクションでは、Google Distributed Cloud のインストールに関する問題のトラブルシューティングに役立つ情報を提供します。

ブートストラップ クラスタを使用して問題をデバッグする

インストール中、Google Distributed Cloud により一時的なブートストラップ クラスタが作成されます。インストールが正常に完了すると、Google Distributed Cloud によってブートストラップ クラスタが削除され、管理クラスタとユーザー クラスタが残されます。通常、ブートストラップ クラスタを操作する理由はありません。 ただし、インストール中に問題が発生した場合は、ブートストラップ クラスタのログを使用して問題のデバッグを行うことができます。

--cleanup-external-cluster=false を gkectl create cluster に渡した場合、ブートストラップ クラスタは削除されず、ブートストラップ クラスタを使用してインストールの問題をデバッグできます。

ブートストラップ クラスタのログを調べる

1. kube-system 名前空間で実行されている Pod の名前を確認します。

   kubectl --kubeconfig /home/ubuntu/.kube/kind-config-gkectl get pods -n kube-system
   

2. Pod のログを表示します。

   kubectl --kubeconfig /home/ubuntu/.kube/kind-config-gkectl -n kube-system get logs POD_NAME
   

   POD_NAME は、表示する Pod の名前に置き換えます。

3. ブートストラップ クラスタから直接ログを取得するには、クラスタの作成、更新、アップグレード中に次のコマンドを実行します。

   docker exec -it gkectl-control-plane bash
   

   このコマンドにより、ブートストラップ クラスタで実行される gkectl-control-plane コンテナ内のターミナルが開かれます。

4. kubelet ログと containerd ログを検査するには、次のコマンドを使用して、出力でエラーや警告を探します。

   systemctl status -l kubelet
   journalctl --utc -u kubelet
   systemctl status -l containerd
   journalctl --utc -u containerd
   

ブートストラップ クラスタのスナップショットを調べる

管理クラスタを作成またはアップグレードしようとして、そのオペレーションが失敗した場合、Google Distributed Cloud ではブートストラップ クラスタの外部スナップショットが取得されます。このブートストラップ クラスタのスナップショットは、管理クラスタで gkectl diagnose snapshot コマンドを実行すると取得されるスナップショットと似ていますが、プロセスは自動的にトリガーされます。ブートストラップ クラスタのスナップショットには、管理クラスタの作成とアップグレード プロセスに関する重要なデバッグ情報が含まれています。必要な場合は、Cloud カスタマーケアにこのスナップショットを提供できます。

外部スナップショットには、onprem-admin-cluster-controller の Pod ログが含まれます。このログを表示して、クラスタの作成やアップグレードに関する問題をデバッグできます。ログは別々のファイルに保存されます。例:

kubectl_logs_onprem-admin-cluster-controller-6767f6597-nws8g_ \
    --container_onprem-admin-cluster-controller_ \
    --kubeconfig_.home.ubuntu..kube.kind-config-gkectl_\
    --namespace_kube-system

管理コントロール プレーンの起動後に VM が起動しない

管理コントロール プレーンの起動後に VM が起動しない場合は、管理クラスタの Cluster API コントローラ Pod のログを調べて問題を調査できます。

1. Cluster API コントローラ Pod の名前を見つけます。

   kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG --namespace kube-system \
       get pods | grep clusterapi-controllers
   

2. vsphere-controller-manager からのログを表示します。まず、Pod を指定しますが、コンテナは指定しません。

   kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG --namespace kube-system \
       logs POD_NAME
   

   出力には、コンテナを指定する必要があることが示され、Pod 内のコンテナの名前が示されます。例:

   ... a container name must be specified ...,
   choose one of: [clusterapi-controller-manager vsphere-controller-manager rbac-proxy]
   

3. コンテナを選んで、そのログを表示します。

   kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG --namespace kube-system \
       logs POD_NAME --container CONTAINER_NAME
   

十分な数の IP アドレスが割り振られているが、クラスタにマシンを登録できない

この問題は、IP アドレスの競合が存在する場合に発生する可能性があります。たとえば、マシンに指定した IP アドレスがロードバランサで使用されている場合が該当します。

この問題を解決するには、クラスタ IP ブロック ファイルを更新して、マシンのアドレスがクラスタ構成ファイル、またはSeesaw IP ブロック ファイルで指定されたアドレスと競合しないようにします。

クラスタ アップグレードの問題

以降のセクションでは、クラスタのアップグレード中に発生する可能性のある問題を解決する方法について説明します。

アップグレード後にノードプールをロールバックする

ユーザー クラスタをアップグレードした後にクラスタノードで問題が見つかった場合は、選択したノードプールを以前のバージョンにロールバックできます。

選択したノードプールのロールバックは、Ubuntu ノードプールと COS ノードプールではサポートされていますが、Windows ノードプールではサポートされていません。

対応するノードプールのバージョンは、ユーザー クラスタ コントロール プレーンのバージョンと同じか、1 つ古いマイナー バージョンです。たとえば、コントロール プレーンがバージョン 1.14 の場合、ノードプールはバージョン 1.14 または 1.13 にできます。

使用可能なノードプールのバージョンを表示する

最近、ユーザー クラスタのワーカーノードとコントロール プレーンをバージョン 1.13.1-gke.35 からバージョン 1.14.0 にアップグレードし、アップグレードしたワーカーノードで問題が見つかったとします。そのため、あなたは 1 つ以上のノードプールを以前実行していたバージョン（1.13.1-gke.35）にロールバックすることにしました。ロールバックを開始する前に、ロールバックに使用できる以前のバージョンがあることを確認する必要があります。

利用可能なバージョンを表示するには、次のコマンドを実行します。

gkectl version --cluster-name USER_CLUSTER_NAME \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG

出力には、各ノードプールの現在のバージョンと以前のバージョンが表示されます。例:

user cluster version: 1.14.0-gke.x

node pools:
- pool-1:
  - version: 1.14.0-gke.x
  - previous version: 1.13.1-gke.35
- pool-2:
  - version: 1.14.0-gke.x
  - previous version: 1.13.1-gke.35

available node pool versions:
- 1.13.1-gke.35
- 1.14.0-gke.x

ノードプール バージョンをロールバックする

ノード プールのバージョンについて、一度に 1 つのノード プールずつロールバックすることも、1 つの手順で複数のノード プールをロールバックすることもできます。

ノードプールのバージョンをロールバックする手順は次のとおりです。

1. ユーザー クラスタ構成ファイルの 1 つ以上のノードプールで、gkeOnPremVersion の値を以前のバージョンに設定します。次の例は、バージョン 1.13.1-gke.35 にロールバックする方法を示しています。

   nodePools:
   - name: pool-1
     cpus: 4
     memoryMB: 8192
     replicas: 3
     gkeOnPremVersion: 1.13.1-gke.35
     ...
   

2. ノードプールをロールバックするようにクラスタを更新します。

   gkectl update cluster --config USER_CLUSTER_CONFIG \
       --kubeconfig ADMIN_CLUSTER_KUBECONFIG
   

3. ロールバックが成功したことを確認します。

   gkectl version --cluster-name USER_CLUSTER_NAME \
       --kubeconfig ADMIN_CLUSTER_KUBECONFIG
   

   次の出力は、pool-1 がバージョン 1.13.1-gke.35 にロールバックされたことを示しています。

   user cluster version: 1.14.0-gke.x
   
   node pools:
   - pool-1:
     - version: 1.13.1-gke.35
     - previous version: 1.14.0-gke.x
   - pool-2:
     - version: 1.14.0-gke.x
     - previous version: 1.13.1-gke.35
   
   available node pool versions:
   - 1.13.1-gke.35
   - 1.14.0-gke.x
   

新しいパッチ バージョンにアップグレードする

すべてのノードプールとコントロール プレーンを新しいパッチ バージョンにアップグレードできます。これは、以前のバージョンにロールバックし、修正を含むバージョンにアップグレードする必要がある場合に役立ちます。

新しいバージョンにアップグレードする手順は次のとおりです。

1. ユーザー クラスタ構成ファイルで次の変更を行います。

   1. gkeOnPremVersion の値を新しいパッチ バージョンに設定します。この例では 1.14.1-gke.x を使用します。

   2. ノードプールごとに、gkeOnPremVersion フィールドを削除するか、空の文字列に設定します。ノードプールにバージョンが指定されていない場合、ノードプールのバージョンはクラスタに指定されたデフォルトのバージョンに設定されます。

      こうした変更は次の例のようになります。

      gkeOnPremVersion: 1.14.1-gke.x
      
      nodePools:
      -   name: pool-1
        cpus: 4
        memoryMB: 8192
        replicas: 3
        gkeOnPremVersion: ""
      -   name: pool-2
        cpus: 8
        memoryMB: 8192
        replicas: 2
        gkeOnPremVersion: ""
      

2. Google Distributed Cloud のアップグレードの説明に沿って、gkectl prepare と gkectl upgrade cluster を実行します。

3. 新しいクラスタ バージョンを確認し、ロールバックに利用可能なバージョンを確認します。

   gkectl version --cluster-name USER_CLUSTER_NAME \
       --kubeconfig ADMIN_CLUSTER_KUBECONFIG
   

   出力は次のようになります。

    user cluster version: 1.14.1-gke.y
   
    node pools:
    - pool-1:
      - version: 1.14.1-gke.y
      - previous version: 1.13.1-gke.35
    - pool-2:
      - version: 1.14.1-gke.y
      - previous version: 1.13.1-gke.35
   
    available node pool versions:
    - 1.13.1-gke.35
    - 1.14.0-gke.x
    - 1.14.1-gke.y
    ```
   

クラスタのアップグレードに失敗すると、ヘルスチェックが自動的に実行される

管理クラスタまたはユーザー クラスタをアップグレードしようとして、そのオペレーションが失敗した場合、Google Distributed Cloud は、クラスタに対して gkectl diagnose cluster コマンドを自動的に実行します。

自動診断をスキップするには、--skip-diagnose-cluster フラグを gkectl upgrade に渡します。

アップグレード プロセスが停止する

アップグレード中、Google Distributed Cloud はバックグラウンドで Kubernetes drain コマンドを使用します。この drain 手順は、minAvailable: 1 を使用して作成された PodDisruptionBudget（PDB）を持つ唯一のレプリカを含む Deployment によってブロックされます。

Google Distributed Cloud バージョン 1.13 から、Kubernetes Pod イベントを使用してエラーを確認できます。

1. マシンの名前を見つけます。

   kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get machines --all-namespaces
   

2. kubectl describe machine コマンドを使用してエラーを確認します。

   kubectl --kubeconfig USER_CLUSTER_KUBECONFIG describe machine MACHINE_NAME
   

   出力は次のようになります。

   Events:
     Type     Reason              Age    From                Message
     ----     ------              ----   ----                -------
     Warning  PodEvictionTooLong  3m49s  machine-controller  Waiting too long(12m10.284294321s) for pod(default/test-deployment-669b85c4cc-z8pz7) eviction.
   

3. 省略可: マシン オブジェクトのステータスを詳細に分析するには、gkectl diagnose cluster を実行します。

   出力は次のようになります。

   ...
   Checking machineset...SUCCESS
   Checking machine objects...FAILURE
       Reason: 1 machine objects error(s).
       Unhealthy Resources:
       Pod test-deployment-669b85c4cc-7zjpq: Pod cannot be evicted successfully. There is 1 related PDB.
   ...
   Checking all poddisruptionbudgets...FAILURE
       Reason: 1 pod disruption budget error(s).
       Unhealthy Resources:
       PodDisruptionBudget test-pdb: default/test-pdb might be configured incorrectly, the total replicas(3) should be larger than spec.MinAvailable(3).
   ...
   Some validation results were FAILURE or UNKNOWN. Check report above.
   

この問題を解決するには、PDB を保存して、クラスタから削除してからアップグレードを試してください。アップグレードが完了したら、PDB を再度追加できます。

サポートされていない変更を削除してアップグレードを解除する

クラスタを 1.16 以前のバージョンにアップグレードすると、ほとんどのフィールドの変更はアップグレード時に自動的に無視されます。つまり、アップグレード中やアップグレード後に変更は適用されません。

ユーザー クラスタを 1.28 以降のバージョンにアップグレードする場合は、構成ファイルで行われたすべての変更を検証し、サポートされていない変更を無視するのではなく、エラーを返します。この機能はユーザー クラスタのみを対象とします。管理クラスタをアップグレードする場合、ほとんどのフィールドの変更は通知なく無視され、アップグレード後に有効になりません。

たとえば、ユーザー クラスタを 1.28 にアップグレードする際にノードの自動修復を無効にしようとすると、アップグレードが失敗し、次のエラー メッセージが表示されます。

failed to generate desired create config: failed to generate desired OnPremUserCluster from seed config: failed to apply validating webhook to OnPremUserCluster: the following changes on immutable fields are forbidden during upgrade: (diff: -before, +after):
   v1alpha1.OnPremUserClusterSpec{
    ... // 20 identical fields
    UsageMetering:         nil,
    CloudAuditLogging:     &{ProjectID: "syllogi-partner-testing", ClusterLocation: "us-central1", ServiceAccountKey: &{KubernetesSecret: &{Name: "user-cluster-creds", KeyName: "cloud-audit-logging-service-account-key"}}},
-   AutoRepair:            &v1alpha1.AutoRepairConfig{Enabled: true},
+   AutoRepair:            &v1alpha1.AutoRepairConfig{},
    CARotation:            &{Generated: &{CAVersion: 1}},
    KSASigningKeyRotation: &{Generated: &{KSASigningKeyVersion: 1}},
    ... // 8 identical fields
  }

このエラーを回避する必要がある場合は、次の回避策を使用できます。

• 変更を元に戻してから、アップグレードを再実行します。たとえば、前のシナリオでは、AutoRepair 構成に加えた変更を元に戻してから、gkectl upgrade を再実行します。
• または、gkectl get-config を実行して、クラスタの現在の状態と一致する構成ファイルを生成し、構成ファイルのクラスタおよびノードプールの gkeOnPremVersion フィールドを更新してから、gkectl upgrade を再実行します。

内部 kubeconfig ファイルを使用して F5 BIG-IP の問題をデバッグする

インストール後、Google Distributed Cloud は、管理ワークステーションのホーム ディレクトリに internal-cluster-kubeconfig-debug という名前の kubeconfig ファイルを生成します。この kubeconfig ファイルは、Kubernetes API サーバーが実行される管理クラスタのコントロール プレーン ノードを直接参照することを除いて、管理クラスタの kubeconfig ファイルと同じです。この internal-cluster-kubeconfig-debug ファイルを使用して、F5 BIG-IP の問題をデバッグできます。

vSphere に関する問題をデバッグする

govc を使用すると、vSphere に関する問題を調査できます。たとえば、vCenter ユーザー アカウントの権限とアクセスを確認し、vSphere のログを収集できます。

欠落しているユーザー クラスタの kubeconfig ファイルを再作成する

次のような状況では、ユーザー クラスタの kubeconfig ファイルの再作成が必要になるかもしれません。

• ユーザー クラスタを作成しようとして、作成オペレーションが失敗し、そのユーザー クラスタ kubeconfig ファイルを取得する必要がある場合。
• ユーザー クラスタの kubeconfig ファイルが見つからない（削除後など）場合。

次のコマンドを実行して、ユーザー クラスタの kubeconfig ファイルを再作成します。

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG get secrets -n admin \
  -o jsonpath='{.data.admin\.conf}' | base64 -d  > USER_CLUSTER_KUBECONFIG

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

• USER_CLUSTER_KUBECONFIG: ユーザー クラスタの新しい kubeconfig ファイルの名前。
• ADMIN_CLUSTER_KUBECONFIG: 管理クラスタの kubeconfig ファイルのパス。

次のステップ

• さらにサポートが必要な場合は、Cloud カスタマーケアにお問い合わせください。