AWS 版 Anthos クラスタのトラブルシューティング

AWS 版 Anthos クラスタの作成または使用で問題が発生した場合は、これらのトラブルシューティング手順を使用してください。

クラスタの作成に失敗する

クラスタを作成するリクエストを行うと、Anthos clusters on AWS では一連のプリフライト テストを実行してそのリクエストが検証されます。クラスタの作成に失敗した場合は、このプリフライト テストのいずれかが失敗したか、クラスタを作成するプロセス自体のステップが完了しなかった可能性があります。

プリフライト テストが失敗すると、クラスタはリソースを作成せず、エラーに関する情報を直接返します。たとえば、invalid%%%name という名前のクラスタを作成しようとすると、有効なクラスタ名のプリフライト テストは失敗し、リクエストは次のエラーを返します。

ERROR: (gcloud.container.aws.clusters.create) INVALID_ARGUMENT: must be
between 1-63 characters, valid characters are /[a-z][0-9]-/, should start with a
letter, and end with a letter or a number: "invalid%%%name",
field: aws_cluster_id

また、プリフライト テストに合格した後に、クラスタの作成に失敗する可能性もあります。これは、AWS 版 Anthos クラスタが Google Cloud と AWS にリソースを作成した後、クラスタの作成開始から数分後に発生する可能性があります。この場合、AWS リソースが、その状態が ERROR に設定された Google Cloud プロジェクト内に存在します。

失敗の詳細を取得するには、次のコマンドを実行します。

gcloud container aws clusters describe CLUSTER_NAME \
  --location GOOGLE_CLOUD_LOCATION \
  --format "value(state, errors)"

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

  • CLUSTER_NAME: 状態のクエリを実行するクラスタの名前。
  • GOOGLE_CLOUD_LOCATION: この AWS クラスタを管理する Google Cloud リージョンの名前。

あるいは、Create Cluster API 呼び出しに関連付けられた Operation リソースを記述して、作成エラーの詳細を取得することもできます。

gcloud container aws operations describe OPERATION_ID

OPERATION_ID は、クラスタを作成したオペレーションの ID に置き換えます。クラスタ作成リクエストのオペレーション ID がない場合は、次のコマンドで取得できます。

gcloud container aws operations list \
  --location GOOGLE_CLOUD_LOCATION

タイムスタンプまたは関連情報を使用して、対象のクラスタ作成オペレーションを特定します。

たとえば、AWS IAM ロールに十分な権限が付与されていないことが原因でクラスタの作成に失敗した場合、このコマンドとその結果は次の例のようになります。

gcloud container aws operations describe b6a3d042-8c30-4524-9a99-6ffcdc24b370 \
  --location GOOGLE_CLOUD_LOCATION

レスポンスは次のようになります。

done: true
error:
  code: 9
  message: 'could not set deregistration_delay timeout for the target group: AccessDenied
    User: arn:aws:sts::0123456789:assumed-role/foo-1p-dev-oneplatform/multicloud-service-agent
    is not authorized to perform: elasticloadbalancing:ModifyTargetGroupAttributes
    on resource: arn:aws:elasticloadbalancing:us-west-2:0123456789:targetgroup/gke-4nrk57tlyjva-cp-tcp443/74b57728e7a3d5b9
    because no identity-based policy allows the elasticloadbalancing:ModifyTargetGroupAttributes
    action'
metadata:
  '@type': type.googleapis.com/google.cloud.gkemulticloud.v1.OperationMetadata
  createTime: '2021-12-02T17:47:31.516995Z'
  endTime: '2021-12-02T18:03:12.590148Z'
  statusDetail: Cluster is being deployed
  target: projects/123456789/locations/us-west1/awsClusters/aws-prod1
name: projects/123456789/locations/us-west1/operations/b6a3d042-8c30-4524-9a99-6ffcdc24b370

クラスタの作成またはオペレーションが承認エラーで失敗する

通常、承認エラーを示すエラーは、クラスタの作成コマンドで指定した 2 つの AWS IAM ロールの一方が誤って作成されたことを示します。たとえば、API ロールに elasticloadbalancing:ModifyTargetGroupAttributes 権限が含まれていない場合は、クラスタの作成が失敗し、次のようなエラー メッセージが表示されます。

ERROR: (gcloud.container.aws.clusters.create) could not set
deregistration_delay timeout for the target group: AccessDenied User:
arn:aws:sts::0123456789:assumed-role/cloudshell-user-dev-api-role/multicloud-
service-agent is not authorized to perform:
elasticloadbalancing:ModifyTargetGroupAttributes on resource:
arn:aws:elasticloadbalancing:us-east-1:0123456789:targetgroup/gke-u6au6c65e4iq-
cp-tcp443/be4c0f8d872bb60e because no identity-based policy allows the
elasticloadbalancing:ModifyTargetGroupAttributes action

クラスタが正常に作成されたように見える場合でも、IAM ロールの指定が誤っていると、後で kubectl logs のようなコマンドを使用する際などにクラスタ オペレーションが失敗する可能性があります。

このような承認エラーを解決するには、クラスタ作成時に指定した 2 つの IAM ロールに関連付けられたポリシーが正しいことを確認します。具体的には、AWS IAM ロールの作成の説明と一致していることを確認してから、クラスタを削除して再作成します。個々のロールの説明は、API ロールとコントロール プレーンのロールで確認できます。

クラスタの作成またはオペレーションがヘルスチェック ステージで失敗する

次のようなオペレーション ステータスでは、ヘルスチェック中にクラスタの作成が失敗する場合があります。

done: true
error:
  code: 4
  message: Operation failed
metadata:
  '@type': type.googleapis.com/google.cloud.gkemulticloud.v1.OperationMetadata
  createTime: '2022-06-29T18:26:39.739574Z'
  endTime: '2022-06-29T18:54:45.632136Z'
  errorDetail: Operation failed
  statusDetail: Health-checking cluster
  target: projects/123456789/locations/us-west1/awsClusters/aws-prod1
name: projects/123456789/locations/us-west1/operations/8a7a3b7f-242d-4fff-b518-f361d41c6597

原因としては、IAM ロールがないか、IAM ロールが誤って指定されていることが考えられます。AWS CloudTrail を使用して IAM の問題を確認できます。

例:

  • API のロールにコントロール プレーンのメイン ボリューム KMS 鍵に対する kms:GenerateDataKeyWithoutPlaintext 権限が含まれていない場合は、次のイベントが表示されます。

    "eventName": "AttachVolume",
"errorCode": "Client.InvalidVolume.NotFound",
"errorMessage": "The volume 'vol-0ff75940ce333aebb' does not exist.",

    と

    "errorCode": "AccessDenied",
"errorMessage": "User: arn:aws:sts::0123456789:assumed-role/foo-1p-dev-oneplatform/multicloud-service-agent is not authorized to perform: kms:GenerateDataKeyWithoutPlaintext on resource: arn:aws:kms:us-west1:0123456789:key/57a61a45-d9c1-4038-9021-8eb08ba339ba because no identity-based policy allows the kms:GenerateDataKeyWithoutPlaintext action",

  • コントロール プレーンのロールにコントロール プレーンのメイン ボリューム KMS 鍵に対する kms:CreateGrant 権限が含まれていない場合は、次のイベントが表示されます。

    "eventName": "AttachVolume",
"errorCode": "Client.CustomerKeyHasBeenRevoked",
"errorMessage": "Volume vol-0d022beb769c8e33b cannot be attached. The encrypted volume was unable to access the KMS key.",

    と

    "errorCode": "AccessDenied",
"errorMessage": "User: arn:aws:sts::0123456789:assumed-role/foo-controlplane/i-0a11fae03eb0b08c1 is not authorized to perform: kms:CreateGrant on resource: arn:aws:kms:us-west1:0123456789:key/57a61a45-d9c1-4038-9021-8eb08ba339ba because no identity-based policy allows the kms:CreateGrant action",

  • コントロール プレーンのルート ボリューム KMS 鍵を使用するために kms:CreateGrant 権限があるサービスにリンクしたロール（AWSServiceRoleForAutoScaling）を指定しなかった場合は、次のイベントが表示されます。

    "errorCode": "AccessDenied",
"errorMessage": "User: arn:aws:sts::0123456789:assumed-role/AWSServiceRoleForAutoScaling/AutoScaling is not authorized to perform: kms:CreateGrant on resource: arn:aws:kms:us-west1:0123456789:key/c77a3a26-bc91-4434-bac0-0aa963cb0c31 because no identity-based policy allows the kms:CreateGrant action",

  • コントロール プレーンのルート ボリューム KMS 鍵を使用するために kms:GenerateDataKeyWithoutPlaintext 権限があるサービスにリンクしたロール（AWSServiceRoleForAutoScaling）を指定しなかった場合は、次のイベントが表示されます。

    "errorCode": "AccessDenied",
"errorMessage": "User: arn:aws:sts::0123456789:assumed-role/AWSServiceRoleForAutoScaling/AutoScaling is not authorized to perform: kms:GenerateDataKeyWithoutPlaintext on resource: arn:aws:kms:us-west1:0123456789:key/c77a3a26-bc91-4434-bac0-0aa963cb0c31 because no identity-based policy allows the kms:CreateGrant action",

ノードがクラスタに参加するのを待機している

ノードプールの作成時に次のエラーが発生した場合は、VPC に関連付けられているセカンダリ IPv4 CIDR ブロックが含まれていないことを確認します。

errorDetail: Operation failed
statusDetail: Waiting for nodes to join the cluster (0 out of 1 are ready)

この問題を解決するには、すべての CIDR ブロックを含むセキュリティ グループを作成し、そのグループをクラスタに追加します。詳細については、VPC セカンダリ CIDR ブロックのノードプールをご覧ください。

インスタンスのシステムログを取得する

コントロール プレーンまたはノードプール インスタンスが起動しない場合に、そのシステムログを調査できます。システムログを調べるには、次の操作を行います。

  1. AWS EC2 インスタンス コンソールを開きます。
  2. [Instances] をクリックします。
  3. 名前でインスタンスを検索します。Anthos clusters on AWS は通常、コントロール プレーン ノード用に CLUSTER-NAME-cp、ノードプール ノード用に CLUSTER-NAME-np という名前のインスタンスを作成します。
  4. [Actions] -> [Monitor and Troubleshooter] -> [Get System Log] を選択します。インスタンスのシステムログが表示されます。

クラスタ更新の失敗

クラスタを更新すると、新しいクラスタを作成するときと同様に、AWS 版 Anthos クラスタは最初に一連のプリフライト テストを実行してリクエストを検証します。クラスタの更新に失敗した場合は、このプリフライト テストのいずれかが失敗したか、クラスタを更新するプロセス自体のステップが完了しなかった可能性があります。

プリフライト テストが失敗すると、クラスタはリソースを更新せず、エラーに関する情報を直接返します。たとえば、test_ec2_keypair という SSH 認証鍵ペアを使用するようにクラスタを更新しようとすると、プリフライト テストは EC2 鍵ペアの取得を試行して失敗し、リクエストは次のエラーを返します。

ERROR: (gcloud.container.aws.clusters.update) INVALID_ARGUMENT: key pair
"test_ec2_keypair" not found,
field: aws_cluster.control_plane.ssh_config.ec2_key_pair

プリフライト テストに合格した後、クラスタの更新に失敗する場合もあります。これは、クラスタの更新が開始されてから数分かかる場合があります。また、Google Cloud プロジェクトの AWS リソースの状態が DEGRADED に設定されます。

失敗とそれに関連するオペレーションの詳細を確認するには、クラスタの作成失敗で説明されている手順に従ってください。

コントロール プレーン タグの更新時にクラスタの更新が失敗する

AWS update API で、コントロール プレーンタグの更新がサポートされるようになりました。タグを更新するには、Kubernetes バージョン 1.24 以降のクラスタが必要です。また、コントロール プレーンタグを更新するための [クラスタの更新] ページに記載されている適切な権限が AWS IAM ロールに付与されている必要があります。

以下のように認証の失敗を示すエラーは、通常、IAM 権限を追加できなかったことを示します。たとえば、API ロールに ec2:DeleteTags 権限が含まれていない場合、タグのクラスタ更新は、次のようなエラー メッセージが返されて失敗する可能性があります（<encoded_auth_failure_message> は簡略化されています）。

ERROR: (gcloud.container.aws.clusters.update) could not delete tags:
UnauthorizedOperation You are not authorized to perform this operation.
Encoded authorization failure message: <encoded_auth_failure_message>

上記のエンコードされたエラー メッセージをデバッグするには、次のように AWS STS decode-authorization-message API にリクエストを送信します。

aws sts decode-authorization-message --encoded-message
<encoded_auth_failure_message> --query DecodedMessage --output
text | jq '.' | less

コンソールの出力は次のようになります。

...
"principal": {
  "id": "AROAXMEL2SCNPG6RCJ72B:iam-session",
  "arn": "arn:aws:sts::1234567890:assumed-role/iam_role/iam-session"
},
"action": "ec2:DeleteTags",
"resource": "arn:aws:ec2:us-west-2:1234567890:security-group-rule/sgr-00bdbaef24a92df62",
...

上述のレスポンスは、AWS クラスタの EC2 セキュリティ グループ ルール リソースに対して ec2:DeleteTags アクションを実行できなかったことを示しています。必要に応じて API ロールを更新し、更新の API リクエストを再送信してコントロール プレーン タグを更新します。

kubectl を使用してクラスタに接続できない

このセクションでは、kubectl コマンドライン ツールを使用してクラスタに接続する際の問題を診断するヒントをいくつか説明します。

サーバーにリソースがない

クラスタで実行中のノードプールがない場合、または Connect ゲートウェイがノードプールに接続できない場合、error: the server doesn't have a resource type "services" などのエラーが発生することがあります。ノードプールのステータスを確認するには、次のコマンドを実行します。

gcloud container aws node-pools list \
    --cluster-name CLUSTER_NAME \
    --location LOCATION

以下を置き換えます。

  • CLUSTER_NAME: クラスタの名前
  • LOCATION: クラスタを管理する Google Cloud のロケーション

出力には、クラスタのノードプールのステータスが含まれます。ノードプールが表示されない場合は、ノードプールを作成します。

Connect ゲートウェイのトラブルシューティング

お使いのユーザー名にクラスタに対する管理者アクセス権がない場合は、次のエラーが発生します。

Error from server (Forbidden): users "administrator@example.com" is forbidden:
User "system:serviceaccount:gke-connect:connect-agent-sa" cannot impersonate
resource "users" in API group "" at the cluster scope

追加のユーザーを構成するには、クラスタの作成時に --admin-users フラグを渡します。

Connect ゲートウェイを使用していてクラスタに接続できない場合は、次の手順をお試しください。

  1. クラスタの承認されたユーザーを取得します。

    gcloud container aws clusters describe CLUSTER_NAME \
  --format 'value(authorization.admin_users)'

    CLUSTER_NAME をクラスタ名で置き換えます。

    出力には、クラスタに対する管理者権限があるユーザー名が含まれます。 次に例を示します。

    {'username': 'administrator@example.com'}

  2. Google Cloud CLI で現在認証されているユーザー名を取得します。

    gcloud config get-value account

    出力には、Google Cloud CLI で認証されたアカウントが含まれます。gcloud containers aws clusters describe と gcloud config get-value account の出力が一致しない場合は、gcloud auth login を実行し、クラスタに対する管理者権限を持つユーザーとして認証を行います。

kubectl コマンドが応答しない

kubectl コマンドが応答しない、またはタイムアウトする場合、最も一般的な理由は、ノードプールがまだ作成されていないことです。デフォルトで Anthos clusters on AWS は、インターネットに接続可能なエンドポイントとして Connect ゲートウェイを使用する kubeconfig ファイルを生成します。これが機能するには、クラスタのノードプールで gke-connect-agent Deployment が実行されている必要があります。

この場合の詳細な診断情報を確認するには、次のコマンドを実行します。

kubectl cluster-info -v=9

動作しているノードプールがない場合、connectgateway.googleapis.com へのリクエストは 404 cannot find active connections for cluster エラーで失敗します。

kubectl exec、attach、port-forward コマンドが失敗する

Connect ゲートウェイを使用しているときに、kubectl exec、kubectl attach、kubectl port-forward コマンドがメッセージ「error: unable to upgrade connection」で失敗することがあります。これは、Connect ゲートウェイを Kubernetes API Server エンドポイントとして使用する場合の制限事項です。

この問題を回避するには、kubeconfig を使用してクラスタのプライベート エンドポイントを指定します。プライベート エンドポイントを介してクラスタにアクセスする手順については、kubectl 用のクラスタ アクセスを構成するをご覧ください。

kubectl logs が remote error: tls: internal error で失敗する

これは、コントロール プレーン API ロールに権限がない場合に発生することがあります。たとえば、AWS ロールに ec2:DescribeDhcpOptions 権限がない場合にこれが発生することがあります。この場合、ノードからの証明書署名リクエストは承認されず、ワーカーノードには有効な証明書がありません。

この問題かどうかを判断するには、次のコマンドで承認されなかった保留中の証明書署名リクエストがあるかどうかを確認します。

kubectl get csr

この問題を解決するには、AWS ロールがドキュメントの要件と一致していることを確認します。

kubectl の一般的なトラブルシューティング

Connect ゲートウェイを使用する場合:

  • Google Cloud プロジェクトで Connect ゲートウェイが有効になっていることを確認します。

    gcloud services enable connectgateway.googleapis.com

  • 1 つ以上の Linux ノードプールが実行されていることを確認します。

  • gke-connect-agent が実行されていることを確認します。詳細については、接続のトラブルシューティングをご覧ください。

Kubernetes Service（LoadBalancer）や Kubernetes Ingress が機能しない

AWS Elastic Load Balancer（ELB/NLB/ALB）が作成されたが、想定どおりに動作しない場合は、サブネットのタグ付けに問題があることが原因として考えられます。詳細については、ロードバランサのサブネットをご覧ください。

API エラー

Kubernetes 1.22 では、一部の API が非推奨になり、置き換えられます。クラスタをバージョン 1.22 以降にアップグレードした場合、非推奨 API のいずれかに対するアプリケーションからの呼び出しはすべて失敗します。

解決策

アプリケーションをアップグレードして、非推奨の API 呼び出しを新しいものに置き換えます。

クラスタを削除できない

FAILED_PRECONDITION: ロールを引き継げない

次のようなエラーが表示された場合、Anthos Multi-Cloud API ロールが存在しない可能性があります。

ERROR: (gcloud.container.aws.clusters.delete) FAILED_PRECONDITION: Could not
assume role
"arn:aws:iam::ACCOUNT_NUMBER:role/gke123456-anthos-api-role"
through service account
"service-123456789@gcp-sa-gkemulticloud.iam.gserviceaccount.com".
Please make sure the role has a trust policy allowing the GCP service agent to
assume it: WebIdentityErr failed to retrieve credentials

問題を解決するには、Anthos Multi-Cloud API ロールの作成の手順に従います。同じ名前と権限を持つロールを再作成する場合は、コマンドを再試行できます。

ARM ワークロードのトラブルシューティング

Arm ノードの Pod がクラッシュする

Arm ノードに Pod をデプロイしても、コンテナ イメージが Arm アーキテクチャ用にビルドされていないと、次の問題が発生します。

問題を特定するには、次のタスクを行います。

  1. Pod のステータスを取得します。

    kubectl get pods

  2. クラッシュした Pod のログを取得します。

    kubectl logs POD_NAME

    POD_NAME は、クラッシュした Pod の名前に置き換えます。

    Pod ログのエラー メッセージは次のようになります。

    exec ./hello-app: exec format error

この問題を解決するには、コンテナ イメージが Arm アーキテクチャをサポートしていることを確認してください。複数のアーキテクチャ イメージを作成することをおすすめします。