本文档适用于 2021 年 11 月发布的当前版本的 GKE on AWS。如需了解详情，请参阅版本说明。

排查集群创建或更新问题

本页面介绍如何解决与安装或升级 GKE on AWS 相关的问题。

如果您需要其他帮助，请与 Cloud Customer Care 联系。

集群创建失败

当您发出集群创建请求时，GKE 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

在预检测试通过后，集群创建也可能会失败。这可能会在集群创建开始几分钟后，在 GKE on AWS 在 Google Cloud 和 AWS 中创建了资源后发生。在这种情况下，AWS 资源将存在于您的 Google Cloud 项目中，其状态设置为 ERROR。

如需获取有关失败的详细信息，请运行以下命令：

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

请替换以下内容：

将 CLUSTER_NAME 替换为您要查询其状态的集群的名称
将 GOOGLE_CLOUD_LOCATION 替换为管理此 AWS 集群的 Google Cloud 地区的名称

或者，您可以通过描述与创建集群 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

集群创建或操作失败并显示授权错误

显示授权失败的错误通常表示您在集群创建命令期间指定的两个 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 之类的命令时。

如需解决此类授权错误，请确认与您在集群创建期间指定的两个 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",

如果您没有为名为 AWSServiceRoleForAutoScaling 的服务关联角色提供 kms:CreateGrant 权限以使用控制平面根卷 KMS 密钥，您将看到以下事件：

"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",

如果您没有为名为 AWSServiceRoleForAutoScaling 的服务关联角色提供 kms:GenerateDataKeyWithoutPlaintext 权限以使用控制平面根卷 KMS 密钥，您将看到以下事件：

"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 地址块中的节点池。

获取实例的系统日志

如果控制平面或节点池实例未启动，您可以检查其系统日志。如需检查系统日志，请执行以下操作：

打开 AWS EC2 实例控制台。
点击实例。
按名称查找实例。GKE on AWS 通常会为控制平面节点创建名为 CLUSTER_NAME-cp 的实例，或为节点池节点创建名为 CLUSTER_NAME-np 的实例。
选择操作 -> 监控和问题排查 -> 获取系统日志。随即会显示实例的系统日志。

集群更新失败

在更新集群时，与创建新集群时一样，GKE on AWS 首先运行一组预检测试来验证请求。如果集群更新失败，原因可能是这些预检测试之一失败，或者集群更新过程本身的某个步骤未完成。

如果预检测试失败，则您的集群不会更新任何资源，还会直接向您返回错误相关信息。例如，如果您尝试更新集群以使用名为 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 请求以更新控制平面标记。

后续步骤

如果您需要其他帮助，请与 Cloud Customer Care 联系。