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

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

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

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

次のセクションは、GKE on VMware のインストールに関する問題のトラブルシューティングに役立つ情報を提供します。

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

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

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

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

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

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

Pod のログを表示します。
```
kubectl --kubeconfig /home/ubuntu/.kube/kind-config-gkectl -n kube-system get logs POD_NAME
```
POD_NAME は、表示する Pod の名前に置き換えます。
ブートストラップクラスタから直接ログを取得するには、クラスタの作成、更新、アップグレード中に次のコマンドを実行します。
```
docker exec -it gkectl-control-plane bash
```
このコマンドにより、ブートストラップクラスタで実行される gkectl-control-plane コンテナ内のターミナルが開かれます。
kubelet ログと containerd ログを検査するには、次のコマンドを使用して、出力でエラーや警告を探します。
```
systemctl status -l kubelet
journalctl --utc -u kubelet
systemctl status -l containerd
journalctl --utc -u containerd
```

ブートストラップクラスタのスナップショットを確認する

管理クラスタを作成またはアップグレードしようとして、そのオペレーションが失敗した場合、GKE on VMware ではブートストラップクラスタの外部スナップショットが取得されます。このブートストラップクラスタのスナップショットは、管理クラスタで 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 のログを調べて問題を調査できます。

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

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

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]
```

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

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 つ以上のノードプールで、gkeOnPremVersion の値を以前のバージョンに設定します。次の例は、バージョン 1.13.1-gke.35 にロールバックする方法を示しています。
```
nodePools:
- name: pool-1
  cpus: 4
  memoryMB: 8192
  replicas: 3
  gkeOnPremVersion: 1.13.1-gke.35
  ...
```

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

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

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

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. 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: ""
```
GKE on VMware のアップグレードの説明に従って、gkectl prepare と gkectl upgrade cluster を実行します。

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

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
 ```

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

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

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

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

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

GKE on VMware バージョン 1.13 からは、Kubernetes Pod イベントを使用して障害を確認できます。

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

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

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.

省略可: マシンオブジェクトのステータスをより詳細に分析するには、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 の問題をデバッグする

インストール後、GKE on VMware は、管理ワークステーションのホームディレクトリに 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 カスタマーケアにお問い合わせください。

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

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

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

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

ブートストラップ クラスタのスナップショットを確認する

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

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

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

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

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

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

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

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

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

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

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

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

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

次のステップ

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

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

ブートストラップクラスタのスナップショットを確認する

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

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

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

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

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

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