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

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

gkectlgkeadm のデフォルトのロギング動作

gkectlgkeadm では、デフォルトのロギング設定を使用するだけで十分です。

  • gkectl の場合、デフォルトのログファイルは /home/ubuntu/.config/gke-on-prem/logs/gkectl-$(date).log で、このファイルは gkectl を実行するローカル ディレクトリの logs/gkectl-$(date).log ファイルにシンボリック リンクされます。

  • gkeadm の場合、デフォルトのログファイルは、gkeadm を実行するローカル ディレクトリの logs/gkeadm-$(date).log です。

  • デフォルトの -v5 詳細レベルは、サポートチームが必要とするログエントリすべてを対象としています。

  • ログファイルには、実行されたコマンドとエラー メッセージが含まれます。

サポートが必要な場合は、サポートチームにログファイルを送信することをおすすめします。

ログファイルにデフォルト以外の場所を指定する

gkectl ログファイルにデフォルト以外の場所を指定するには、--log_file フラグを使用します。指定したログファイルは、ローカル ディレクトリにシンボリック リンクされません。

gkeadm ログファイルにデフォルト以外の場所を指定するには、--log_file フラグを使用します。

管理クラスタで Cluster API ログを見つける

管理コントロール プレーンの起動後に 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]
    

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

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

種類クラスタが削除されない

管理クラスタを作成すると、プロセスの一部として kind クラスタ(ブートストラップ クラスタとも呼ばれます)が作成されます。管理クラスタのオペレーションが完了すると、kind クラスタは自動的に削除されます。

エラー メッセージ Failed to delete the kind cluster が表示された場合は、管理ワークステーションで次の手順を実行して kind クラスタを手動で削除できます。

  1. kind コンテナ ID を取得します:

    docker inspect --format="{{.Id}}" gkectl-control-plane
    
  2. containerd-shim プロセス ID を取得します。

    sudo ps awx | grep containerd-shim | grep CONTAINER_ID | awk '{print $1}'
    
  3. プロセスを強制終了します。

    sudo kill -9 PROCESS_ID
    

govc を使用して vSphere に関する問題を解決する

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

ブートストラップ クラスタのログを使用したデバッグ

インストール時、GKE on VMware により一時的なブートストラップ クラスタが作成されます。インストールが正常に完了した後、GKE on VMware によってブートストラップ クラスタが削除され、管理クラスタとユーザー クラスタが残されます。通常、ブートストラップ クラスタを操作する理由はありません。

--cleanup-external-cluster=falsegkectl 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
    
  3. ブートストラップ クラスタから直接ログを取得するには、クラスタの作成、更新、アップグレード中に次のコマンドを実行します。

    docker exec -it gkectl-control-plane bash
    

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

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

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

ノードプールのアップグレード後のロールバック

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

選択したノードプールのロールバックは 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.14.1)で問題が修正されたとします。これで、すべてのノードプールとコントロール プレーンを新しいパッチ バージョンにアップグレードできるようになりました。

ユーザー クラスタの構成ファイルで、次の操作を行います。

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

  • ノードプールごとに、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 preparegkectl 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

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

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

ユーザー クラスタのサイズ変更に失敗する

ユーザー クラスタのサイズ変更が失敗した場合:

  1. MachineDeployments とマシンの名前を確認します。

    kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get machinedeployments --all-namespaces
    kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get machines --all-namespaces
    
  2. ログを表示する MachineDeployment を記述します。

    kubectl --kubeconfig USER_CLUSTER_KUBECONFIG describe machinedeployment MACHINE_DEPLOYMENT_NAME
    
  3. 新しく作成したマシンでエラーを確認します。

    kubectl --kubeconfig USER_CLUSTER_KUBECONFIG describe machine MACHINE_NAME
    

クラスタのサイズ変更にアドレスを割り振ることができない

この問題は、ユーザー クラスタのサイズを変更するのに十分な IP アドレスが使用できない場合に発生します。

kubectl describe machine を実行すると、次のエラーが表示されます。

Events:
Type     Reason  Age                From                    Message
----     ------  ----               ----                    -------
Warning  Failed  9s (x13 over 56s)  machineipam-controller  ipam: no addresses can be allocated

この問題を解決するには、クラスタに追加の IP アドレスを割り振ります。次に、影響を受けたマシンを削除します。

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG delete machine MACHINE_NAME

GKE on VMware によって、新しいマシンが作成され、新しく使用可能になった IP アドレスのいずれかが割り当てられます。

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

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

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

管理クラスタの作成またはアップグレードが失敗すると、自動的にスナップショットが作成される

管理クラスタの作成やアップグレードをしようとして、そのオペレーションが失敗した場合、GKE on VMware では、ブートストラップ クラスタ(管理クラスタの作成やアップグレードに使用される一時的なクラスタ)の外部スナップショットが取得されます。このブートストラップ クラスタのスナップショットは、管理クラスタで gkectl diagnose snapshot コマンドを実行すると実行されるスナップショットと似ていますが、自動的にトリガーされる点が異なります。このブートストラップ クラスタのスナップショットには、管理クラスタの作成やアップグレード プロセスに関する重要なデバッグ情報が含まれています。必要な場合は、Google 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

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

管理クラスタまたはユーザー クラスタをアップグレードしようとして、そのオペレーションが失敗した場合、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 イベントを使用して障害を確認できます。

  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.

マシン オブジェクトのステータスをより詳細に分析するには、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 を再度追加できます。

仮想マシンのステータスを診断する

仮想マシンの作成で問題が発生した場合は、gkectl diagnose cluster を実行して、仮想マシンのステータスの診断を取得します。

出力の例を次に示します。


- Validation Category: Cluster Healthiness
Checking cluster object...SUCCESS
Checking machine deployment...SUCCESS
Checking machineset...SUCCESS
Checking machine objects...SUCCESS
Checking machine VMs...FAILURE
    Reason: 1 machine VMs error(s).
    Unhealthy Resources:
    Machine [NODE_NAME]: The VM's UUID "420fbe5c-4c8b-705a-8a05-ec636406f60" does not match the machine object's providerID "420fbe5c-4c8b-705a-8a05-ec636406f60e".
    Debug Information:
    null
...
Exit with error:
Cluster is unhealthy!
Run gkectl diagnose cluster automatically in gkectl diagnose snapshot
Public page https://cloud.google.com/anthos/clusters/docs/on-prem/latest/diagnose#overview_diagnose_snapshot

詳細については、クラスタの問題を診断するをご覧ください。

欠落しているユーザー クラスタの 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 ファイルのパス。

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

クラスタを 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 を再実行します。

VPC Service Controls の使用時の gkectl コマンドエラー

VPC Service Controls を使用している場合、"Validation Category: GCP - [UNKNOWN] GCP service: [Stackdriver] could not get GCP services" などの一部の gkectl コマンドを実行するとエラーが表示されることがあります。これらのエラーを回避するには、コマンドに --skip-validation-gcp パラメータを追加します。