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

排查 Anthos clusters on Azure 问题

如果您在创建或使用 Anthos clusters on Azure 时遇到问题，请使用以下问题排查步骤。

集群创建失败

当您发出集群创建请求时，Anthos clusters on Azure 首先会运行一组预检测试来验证请求。如果集群创建失败，原因可能是这些预检测试之一失败，或者集群创建过程本身的某个步骤未完成。

如果预检测试失败，则您的集群不会创建任何资源，还会直接向您返回错误相关信息。例如，如果您尝试创建名为 invalid%%%name 的集群，则有效集群名称的预检测试会失败，并且请求会返回以下错误：

ERROR: (gcloud.container.azure.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: azure_cluster_id

在预检测试通过后，集群创建也可能会失败。当 Anthos clusters on Azure 在 Google Cloud 和 Azure 中创建资源后，可能会在集群创建已经开始后发生此错误。在这种情况下，Azure 资源将存在于您的 Google Cloud 项目中，其状态设置为 ERROR。

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

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

替换：

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

或者，您可以通过描述与创建集群 API 调用关联的 Operation 资源来获取有关创建失败的详细信息。

gcloud container azure operations describe OPERATION_ID

将 OPERATION_ID 替换创建集群的操作的 ID。如果您没有集群创建请求的操作 ID，可以使用以下命令进行提取：

gcloud container azure operations list \
  --location GOOGLE_CLOUD_LOCATION

使用时间戳或相关信息来识别感兴趣的集群创建操作。

集群更新失败

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

如果预检测试失败，则您的集群不会更新任何资源，还会直接向您返回错误相关信息。例如，如果您尝试更新集群以使用名为 test_ec2_keypair 的 SSH 密钥对，则预检测试会尝试提取 EC2 密钥对，并且请求将返回以下错误：

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

在预检测试通过后，集群更新也可能会失败。这可能在集群更新开始几分钟后发生，您的 Google Cloud 项目中的 Azure 资源状态将设置为 DEGRADED。

如需详细了解失败和相关操作，请按照集群创建失败中所述的步骤操作。

无法使用 kubectl 连接到集群

本部分提供了一些使用 kubectl 命令行工具诊断集群连接问题的提示。

服务器没有资源

如果集群没有正在运行的节点池，或者 Connect 网关无法连接到节点池，则可能会发生 error: the server doesn't have a resource type "services" 等错误。如需检查节点池的状态，请运行以下命令：

gcloud container azure 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 网关且无法连接到集群，请尝试以下步骤：

获取集群的授权用户。

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

将 CLUSTER_NAME 替换为您的集群名称。

输出包括对集群具有管理员访问权限的用户名。例如：

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

获取当前使用 Google Cloud CLI 进行身份验证的用户名。
```
gcloud config get-value account
```
输出包括使用 Google Cloud CLI 进行身份验证的账号。如果 gcloud containers azure clusters describe 和 gcloud config get-value account 的输出不匹配，请运行 gcloud auth login 并以对集群具有管理员权限的用户名进行身份验证。

kubectl 命令停止响应

如果 kubectl 命令无响应或超时，最常见的原因是您尚未创建节点池。默认情况下，Anthos clusters on Azure 会生成 kubeconfig 文件，这些文件使用 Connect 网关作为互联网可访问端点。为此，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 服务器端点时，需要遵守此限制。

如需解决此问题，请使用 kubeconfig 来指定集群的专用端点。如需了解如何通过集群的专用端点访问集群，请参阅为 kubectl 配置集群访问权限。

常规 kubectl 问题排查

如果您使用 Connect 网关，请注意以下几点：

确保您已在 Google Cloud 项目中启用 Connect 网关：
```
gcloud services enable connectgateway.googleapis.com
```
确保您至少有一个 Linux 节点池正在运行。
确保 gke-connect-agent 正在运行。如需了解详情，请参阅排查连接问题。

API 错误

Kubernetes 1.22 中弃用并替换了一些 API。如果您已将集群升级到 1.22 版或更高版本，则应用对任何已弃用 API 进行的所有调用都将失败。

解决方案

升级您的应用以将已弃用的 API 调用替换为对应的新版 API 调用。

在界面中检测到无法访问的集群错误

Google Cloud 控制台中的一些界面在连接到版本 1.25.5-gke.1500 和 1.25.4-gke.1300 集群时遇到问题。特别是 Anthos Service Mesh 的集群列表。

此问题会导致一条警告，告知集群虽然可以从其他页面登录并与其交互，但无法访问。

这是在两个集群版本中移除 gateway-impersonate ClusterRoleBinding 而导致的回归。

解决方法是应用此 YAML 手动添加所需的权限：

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: connect-agent-impersonate-admin-users
rules:
- apiGroups:
  - ""
  resourceNames:
  - ADMIN_USER1
  - ADMIN_USER2
  resources:
  - users
  verbs:
  - impersonate
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: connect-agent-impersonate-admin-users
roleRef:
  kind: ClusterRole
  name: connect-agent-impersonate-admin-users
  apiGroup: rbac.authorization.k8s.io
subjects:
- kind: ServiceAccount
  name: connect-agent-sa
  namespace: gke-connect

将 ADMIN_USER1 和 ADMIN_USER2 替换为您的特定集群管理员用户帐号（电子邮件地址）。在此示例中，只有两个管理员用户假定两个管理员用户。

如需查看为集群配置的管理员用户列表，请执行以下操作：

gcloud container azure clusters describe CLUSTER_NAME \
  --location GOOGLE_CLOUD_LOCATION \
  --format "value(authorization.adminUsers)"

升级到较新的集群版本时，系统会自动覆盖此 ClusterRole。