**帮助改进此页面**
要帮助改进本用户指南，请选择位于每个页面右侧窗格中的**在 GitHub 上编辑此页面**链接。
# 混合节点故障排除
本主题介绍在使用 Amazon EKS 混合节点功能时可能遇到的一些常见错误以及修复方法。有关其他故障排除信息，请参阅[排查 Amazon EKS 集群和节点问题](troubleshooting.md)以及 AWS re:Post** 上[有关 Amazon EKS 的知识中心标签](https://repost.aws/tags/knowledge-center/TA4IvCeWI1TE66q4jEj4Z9zg/amazon-elastic-kubernetes-service)。如果您无法解决问题，请联系 AWS Support。
**使用 `nodeadm debug` 对节点进行故障排除** 您可以从混合节点运行 `nodeadm debug` 命令来验证是否满足联网和凭证要求。有关 `nodeadm debug` 命令的更多信息，请参阅 [混合节点 `nodeadm` 参考](hybrid-nodes-nodeadm.md)。
**使用集群见解检测混合节点的问题** Amazon EKS 集群见解包括*见解检查*，可检测集群中 EKS 混合节点配置的常见问题。您可以从 AWS 管理控制台、AWS CLI 和 AWS SDK 中查看所有见解检查的结果。有关集群见解的更多信息，请参阅 [利用集群见解为 Kubernetes 版本升级做好准备并对错误配置进行问题排查](cluster-insights.md)。
## 混合节点安装故障排除
以下故障排除主题与使用 `nodeadm install` 命令在主机上安装混合节点依赖项有关。
** `nodeadm`命令失败，`must run as root`**
运行 `nodeadm install` 命令的用户必须具有主机上的根权限或 `sudo` 权限。如果以没有根权限或 `sudo` 权限的用户身份运行 `nodeadm install`，则会在 `nodeadm` 输出中看到以下错误。
```
"msg":"Command failed","error":"must run as root"
```
**无法连接到依赖项**
`nodeadm install` 命令会安装混合节点必需的依赖项。混合节点依赖项包括 `containerd`、`kubelet`、`kubectl` 和 AWS SSM 或 AWS IAM Roles Anywhere 组件。您必须具有从运行 `nodeadm install` 的位置访问的权限才能下载这些依赖项。要详细了解您必须具有访问权限的位置列表，请参阅[准备混合节点的联网](hybrid-nodes-networking.md)。如果您没有访问权限，则会在 `nodeadm install` 输出中看到与以下类似的错误。
```
"msg":"Command failed","error":"failed reading file from url: ...: max retries achieved for http request"
```
**更新软件包管理器失败**
`nodeadm install` 命令会在安装混合节点依赖项之前运行 `apt update` 或 `yum update` 或 `dnf update`。如果此步骤未成功，您可能会看到与以下类似的错误。要修复错误，您可以首先运行 `apt update` 或 `yum update` 或 `dnf update`，然后再运行 `nodeadm install`，也可以尝试重新运行 `nodeadm install`。
```
failed to run update using package manager
```
**超时或超过上下文截止时间**
运行 `nodeadm install` 时，如果您在安装过程的若干阶段看到问题，并错误消息指示超时或超过上下文截止时间，则可能说明连接速度较慢，导致无法在超时之前安装混合节点依赖项。要解决这些问题，您可以尝试在 `nodeadm` 中使用 `--timeout` 标志来延长下载依赖项的超时期限。
```
nodeadm install K8S_VERSION --credential-provider CREDS_PROVIDER --timeout 20m0s
```
## 混合节点连接故障排除
本节中的故障排除主题与使用 `nodeadm init` 命令将混合节点连接到 EKS 集群的过程有关。
**操作错误或架构不受支持**
运行 `nodeadm init` 时，如果您看到与 `operation error` 或 `unsupported scheme` 相关的错误，请检查 `nodeConfig.yaml` 以确保其格式正确并且已传递给 `nodeadm`。有关 `nodeConfig.yaml` 格式和选项的更多信息，请参阅[混合节点 `nodeadm` 参考](hybrid-nodes-nodeadm.md)。
```
"msg":"Command failed","error":"operation error ec2imds: GetRegion, request canceled, context deadline exceeded"
```
**混合节点 IAM 角色缺少 `eks:DescribeCluster` 操作的权限**
运行 `nodeadm init` 时，`nodeadm` 会尝试通过调用 EKS `DescribeCluster` 操作来收集有关 EKS 集群的信息。若混合节点 IAM 角色不具备 `eks:DescribeCluster` 操作的权限，则在执行 `nodeadm init` 时，您必须在传入 `nodeadm` 的节点配置中，手动指定 Kubernetes API 端点、集群 CA 证书包以及服务 IPv4 CIDR。请参阅[准备用于混合节点的凭证](hybrid-nodes-creds.md)，以了解有关混合节点 IAM 角色所需权限的更多信息。
```
"msg":"Command failed","error":"operation error EKS: DescribeCluster, https response error StatusCode: 403 ... AccessDeniedException"
```
**混合节点 IAM 角色缺少 `eks:ListAccessEntries` 操作的权限**
执行 `nodeadm init` 时，`nodeadm` 会尝试调用 EKS `ListAccessEntries` 操作，验证 EKS 集群是否存在一个与该混合节点 IAM 角色绑定的、类型为 `HYBRID_LINUX` 的访问条目。若混合节点 IAM 角色不具备 `eks:ListAccessEntries` 操作的权限，那么在执行 `nodeadm init` 命令时，您必须传入 `--skip cluster-access-validation` 标记。请参阅[准备用于混合节点的凭证](hybrid-nodes-creds.md)，以了解有关混合节点 IAM 角色所需权限的更多信息。
```
"msg":"Command failed","error":"operation error EKS: ListAccessEntries, https response error StatusCode: 403 ... AccessDeniedException"
```
**节点 IP 不在远程节点网络 CIDR 范围内**
运行 `nodeadm init` 时，如果节点 IP 地址不在指定远程节点网络 CIDR 范围内，则可能会出现错误。此错误将与以下示例类似：
```
node IP 10.18.0.1 is not in any of the remote network CIDR blocks [10.0.0.0/16 192.168.0.0/16]
```
此示例显示一个 IP 为 10.18.0.1 的节点正在尝试加入一个远程网络 CIDR 为 10.0.0.0/16 和 192.168.0.0/16 的集群。之所以出现此错误，是因为这两个 CIDR 均不包含 10.18.0.1。
确认您已正确配置 `RemoteNodeNetworks`，使其包含所有节点 IP 地址。有关网络配置的更多信息，请参阅[准备混合节点的联网](hybrid-nodes-networking.md)。
+ 在集群所在区域运行以下命令，检查您的 `RemoteNodeNetwork` 配置。验证输出中列出的 CIDR 块是否包含您的节点 IP 范围，并且与错误消息中列出的 CIDR 块相同。如果不一致，请确认 `nodeConfig.yaml` 中的集群名称和区域与预期的集群一致。
```
aws eks describe-cluster --name CLUSTER_NAME --region REGION_NAME --query cluster.remoteNetworkConfig.remoteNodeNetworks
```
+ 确认您使用的是预期的节点：
+ 检查节点的主机名和 IP 地址是否与您计划注册到集群的主机名和 IP 地址一致，从而确认节点是否正确。
+ 确认此节点所在的本地网络是否正确（其 CIDR 范围在集群设置期间注册为 `RemoteNodeNetwork`）。
如果节点 IP 仍不符合预期，请检查以下内容：
+ 如果您使用的是 IAM Roles Anywhere，`kubelet` 将对 IAM Roles Anywhere `nodeName` 执行 DNS 查找，并使用与节点名称关联的 IP（如果可用）。如果您负责维护节点的 DNS 条目，请确认这些条目指向远程节点网络 CIDR 内的 IP。
+ 如果节点有多个网络接口，`kubelet` 选择的默认接口的 IP 地址可能在远程节点网络 CIDR 范围外。要使用其他接口，请使用 `nodeConfig.yaml` 中的 `--node-ip` `kubelet` 标志指定其 IP 地址。有关更多信息，请参阅 [混合节点 `nodeadm` 参考](hybrid-nodes-nodeadm.md)。您可以通过在节点上运行以下命令，来查看节点的网络接口及其 IP 地址：
```
ip addr show
```
**混合节点未在 EKS 集群中出现**
如果运行 `nodeadm init`，但在运行完成后，您的混合节点未在集群中出现，则说明混合节点与 EKS 控制面板之间的网络连接可能存在问题，您可能没有配置所需的安全组权限，或者可能没有将混合节点 IAM 角色映射到 Kubernetes 基于角色的访问控制（RBAC）。您可以使用以下命令检查 `kubelet` 和 `kubelet` 日志的状态，从而启动调试进程。从加入集群失败的混合节点上运行以下命令。
```
systemctl status kubelet
```
```
journalctl -u kubelet -f
```
**无法与集群通信**
如果混合节点无法与集群控制面板通信，则可能会看到与以下类似的日志。
```
"Failed to ensure lease exists, will retry" err="Get ..."
```
```
"Unable to register node with API server" err="Post ..."
```
```
Failed to contact API server when waiting for CSINode publishing ... dial tcp : i/o timeout
```
如果您看到此类消息，请检查以下内容以确保其符合[准备混合节点的联网](hybrid-nodes-networking.md)中详述的混合节点要求。
+ 确认传递给 EKS 集群的 VPC 具有指向本地节点以及（可选）容器组 CIDR 的中转网关（TGW）或虚拟专用网关（VGW）的路由。
+ 确认您的 EKS 集群还有一个额外的安全组，其中包含针对本地节点 CIDR 和（可选）容器组 CIDR 的入站规则。
+ 确认您的本地路由器已配置为允许进出 EKS 控制面板的流量。
**未授权**
如果混合节点能够与 EKS 控制面板通信但无法注册，则可能会看到与以下类似的日志。请注意，以下日志消息的主要区别在于 `Unauthorized` 错误。这表明该节点无法执行其任务，因为没有所需的权限。
```
"Failed to ensure lease exists, will retry" err="Unauthorized"
```
```
"Unable to register node with API server" err="Unauthorized"
```
```
Failed to contact API server when waiting for CSINode publishing: Unauthorized
```
如果您看到此类消息，请检查以下内容以确保其符合[准备用于混合节点的凭证](hybrid-nodes-creds.md)和[准备混合节点的集群访问权限](hybrid-nodes-cluster-prep.md)中详述的混合节点要求。
+ 确认混合节点的身份与您预期的混合节点 IAM 角色相符。这可以通过在混合节点上运行 `sudo aws sts get-caller-identity` 来完成。
+ 确认混合节点 IAM 角色具有必需的权限。
+ 确认集群中是否有混合节点 IAM 角色的 EKS 访问条目，或者确认 `aws-auth` ConfigMap 中是否有混合节点 IAM 角色的条目。如果使用 EKS 访问条目，请确认混合节点 IAM 角色的访问条目具有 `HYBRID_LINUX` 访问类型。如果使用 `aws-auth` ConfigMap，请确认您输入的混合节点 IAM 角色符合[准备混合节点的集群访问权限](hybrid-nodes-cluster-prep.md)中详述的要求和格式。
### 混合节点已在 EKS 集群中注册但显示的状态为 `Not Ready`
如果混合节点已成功注册到您的 EKS 集群，但混合节点显示状态为 `Not Ready`，则首先要检查的是容器网络接口（CNI）状态。如果您尚未安装 CNI，则混合节点状态预期将为 `Not Ready`。一旦 CNI 安装并成功运行，节点的状态就会更新为 `Ready`。如果您尝试安装 CNI 但未成功运行，请参阅本页上的[混合节点 CNI 故障排除](#hybrid-nodes-troubleshooting-cni)。
**证书签名请求（CSR）停滞在待处理状态**
将混合节点连接到 EKS 集群后，如果您发现混合节点有待处理的 CSR，则表示您的混合节点不满足自动批准的要求。如果混合节点的 CSR 是由带有 `eks.amazonaws.com/compute-type: hybrid` 标签的节点创建的，并且 CSR 具有以下主体备用名称（SAN），则会自动批准和颁发混合节点的 CSR：至少有一个 DNS SAN 等于节点名称且 IP SAN 属于远程节点网络 CIDR。
**混合配置文件已经存在**
如果您更改了 `nodeadm` 配置并尝试使用新配置重新注册节点，则可能会看到一条错误消息，指示混合配置文件已经存在，但其内容已更改。请勿在配置更改之间运行 `nodeadm init`，而应运行 `nodeadm uninstall`，然后再运行 `nodeadm install` 和 `nodeadm init`。这样可以确保根据配置更改进行正确的清理。
```
"msg":"Command failed","error":"hybrid profile already exists at /etc/aws/hybrid/config but its contents do not align with the expected configuration"
```
**混合节点解析私有 API 失败**
运行 `nodeadm init` 后，如果您在 `kubelet` 日志中看到某个错误，显示由于存在 `no such host` 而无法连接到 EKS Kubernetes API 服务器，则可能需要在本地网络或主机级别更改 EKS Kubernetes API 端点的 DNS 条目。请参阅《AWS Route53 文档》**中的 [Forwarding inbound DNS queries to your VPC](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resolver-forwarding-inbound-queries.html)。
```
Failed to contact API server when waiting for CSINode publishing: Get ... no such host
```
**无法在 EKS 控制台中查看混合节点**
如果您已注册了混合节点，但无法在 EKS 控制台中查看，请检查您用于查看控制台的 IAM 主体的权限。您使用的 IAM 主体必须具有特定的最低 IAM 和 Kubernetes 权限，才能在控制台中查看资源。有关更多信息，请参阅 [在 AWS 管理控制台中查看 Kubernetes 资源](view-kubernetes-resources.md)。
## 混合节点运行故障排查
如果混合节点已注册到 EKS 集群并且状态为 `Ready`，但状态很快变为 `Not Ready`，则可能存在多种导致运行不正常的问题，例如节点缺少足够的 CPU、内存或可用磁盘空间资源，或者节点与 EKS 控制面板之间的连接已断开等。您可以使用以下步骤对节点进行故障排除，如果无法解决问题，请联系 AWS Support。
从您的混合节点运行 `nodeadm debug` 以验证是否满足网络和凭证要求。有关 `nodeadm debug` 命令的更多信息，请参阅 [混合节点 `nodeadm` 参考](hybrid-nodes-nodeadm.md)。
**获取节点状态**
```
kubectl get nodes -o wide
```
**检查节点条件和事件**
```
kubectl describe node NODE_NAME
```
**获取容器组状态**
```
kubectl get pods -A -o wide
```
**检查容器组状况和事件**
```
kubectl describe pod POD_NAME
```
**检查容器组日志**
```
kubectl logs POD_NAME
```
**检查 `kubectl` 日志**
```
systemctl status kubelet
```
```
journalctl -u kubelet -f
```
**容器组存活探针失败或 Webhook 不起作用**
如果在混合节点上运行的应用程序、附加组件或 Webhook 未正常启动，则可能存在网络问题，阻碍了与容器组的通信。要让 EKS 控制面板连接到在混合节点上运行的 Webhook，您必须将 EKS 集群配置为远程容器组网络，并在 VPC 路由表中包含本地容器组 CIDR 的路由，以中转网关（TGW）、虚拟专用网关（VPW）或您用于将 VPC 与本地网络连接的其他网关为目标。有关混合节点联网要求的更多信息，请参阅[准备混合节点的联网](hybrid-nodes-networking.md)。此外，您还必须在本地防火墙中允许此流量，并确保您的路由器可以正确路由到您的容器组。要详细了解在混合节点上运行 Webhook 的要求，请参阅[为混合节点配置 Webhook](hybrid-nodes-webhooks.md)。
下方显示了此场景的一条常见容器组日志消息，其中 ip-address 是 Kubernetes 服务的集群 IP。
```
dial tcp :443: connect: no route to host
```
**`kubectl logs` 或者 `kubectl exec` 命令不起作用（`kubelet` API 命令）**
如果 `kubectl attach`、`kubectl cp`、`kubectl exec`、`kubectl logs` 和 `kubectl port-forward` 命令超时，而其他 `kubectl` 命令能够成功运行，则问题可能与远程网络配置有关。这些命令通过集群连接到节点上的 `kubelet` 端点。有关更多信息，请参阅 [`kubelet` 端点](hybrid-nodes-concepts-kubernetes.md#hybrid-nodes-concepts-k8s-kubelet-api)。
确认节点 IP 和容器组 IP 位于为集群配置的远程节点网络和远程容器组网络 CIDR 范围内。使用以下命令检查 IP 分配。
```
kubectl get nodes -o wide
```
```
kubectl get pods -A -o wide
```
将这些 IP 与您配置的远程网络 CIDR 进行比较，确保路由正确。有关网络配置要求，请参阅[准备混合节点的联网](hybrid-nodes-networking.md)。
## 混合节点 CNI 故障排除
如果您在首次使用混合节点启动 Cilium 或 Calico 时遇到问题，则通常是由于混合节点或在混合节点上运行的 CNI 容器组与 EKS 控制面板之间的网络问题所致。确保您的环境符合“准备混合节点的联网”中的要求。将问题分解成若干部分会非常实用。
EKS 集群配置
RemoteNodeNetwork 和 RemotePodNetwork 的配置是否正确？
VPC 配置
VPC 路由表中是否有 RemoteNodeNetwork 和 RemotePodNetwork 的路由，并以中转网关或虚拟专用网关为目标？
安全组配置
是否有 RemoteNodeNetwork 和 RemoteNetwork 的入站和出站规则？
本地网络
是否存在往返于 EKS 控制面板、混合节点以及在混合节点上运行的容器组的路由和访问权限？
CNI 配置
如果使用叠加网络，CNI 的 IP 池配置是否与使用 Webhook 时为 EKS 集群配置的 RemotePodNetwork 相匹配？
**混合节点的状态为 `Ready`，但未安装 CNI**
如果混合节点显示状态为 `Ready`，但您尚未在集群上安装 CNI，则说明混合节点上可能存在旧的 CNI 构件。默认情况下，当您使用 Helm 等工具卸载 Cilium 和 Calico 时，磁盘上的资源不会从物理计算机或虚拟机中移除。此外，在旧安装中，这些 CNI 的自定义资源定义（CRD）可能仍存在于集群上。有关更多信息，请参阅[为混合节点配置 CNI](hybrid-nodes-cni.md)中的 Cilium 和 Delete Calico 部分。
**Cilium 故障排除**
如果您在混合节点上运行 Cilium 时遇到问题，请参阅 Cilium 文档中的[故障排除步骤](https://docs.cilium.io/en/stable/operations/troubleshooting/)。以下章节介绍了在混合节点上部署 Cilium 时可能遇到的特有问题。
**Cilium 未启动**
如果在每个混合节点上运行的 Cilium 代理都未启动，请检查 Cilium 代理容器组的日志中是否存在错误。Cilium 代理需要连接到 EKS Kubernetes API 端点才能启动。如果此连接配置不正确，Cilium 代理将无法启动。在这种情况下，您将在 Cilium 代理容器组日志中看到与以下类似的日志消息。
```
msg="Unable to contact k8s api-server"
level=fatal msg="failed to start: Get \"https://:443/api/v1/namespaces/kube-system\": dial tcp :443: i/o timeout"
```
Cilium 代理在主机网络上运行。您的 EKS 集群必须将 Cilium 连接配置为 `RemoteNodeNetwork`。确认您的 EKS 集群还有一个额外的安全组，其中包含 `RemoteNodeNetwork` 的入站规则，您的 VPC 中有 `RemoteNodeNetwork` 的路由，并且您的本地网络配置正确，从而能够连接到 EKS 控制面板。
如果 Cilium 操作符正在运行，并且某些但不是全部 Cilium 代理正在运行，请确认您有可用的容器组 IP 可以分配给集群中的所有节点。在 Cilium 配置中使用带 `clusterPoolIPv4PodCIDRList` 的集群池 IPAM 时，您需要配置可分配的容器组 CIDR 的大小。每节点 CIDR 大小是使用 Cilium 配置中的 `clusterPoolIPv4MaskSize` 设置来配置的。有关更多信息，请参阅 Cilium 文档中的 [Expanding the cluster pool](https://docs.cilium.io/en/stable/network/concepts/ipam/cluster-pool/#expanding-the-cluster-pool)。
**Cilium BGP 不起作用**
如果您使用 Cilium BGP 控制面板向本地网络公开您的容器组或服务地址，则可以使用以下 Cilium CLI 命令来检查 BGP 是否在公开指向您的资源的路由。有关安装 Cilium CLI 的步骤，请参阅 Cilium 文档中的 [Install the Cilium CLI](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-default/#install-the-cilium-cli)。
如果 BGP 工作正常，则应在输出中看到会话状态为 `established` 的混合节点。您可能需要联系网络团队，确定环境的本地 AS、对等连接 AS 和对等连接地址的正确值。
```
cilium bgp peers
```
```
cilium bgp routes
```
如果您使用 Cilium BGP 来公开 `LoadBalancer` 类型的服务 IP，则您的 `CiliumLoadBalancerIPPool` 和服务上必须使用相同的标签，该标签应在 `CiliumBGPAdvertisement` 的选择器中使用。下面显示了一个示例。注意，如果您使用 Cilium BGP 来公开 LoadBalancer 类型服务的 IP，则在 Cilium 代理重启期间，BGP 路由可能会中断。有关更多信息，请参阅 Cilium 文档中的 [Failure Scenarios](https://docs.cilium.io/en/latest/network/bgp-control-plane/bgp-control-plane-operation/#failure-scenarios)。
**服务**：
```
kind: Service
apiVersion: v1
metadata:
name: guestbook
labels:
app: guestbook
spec:
ports:
- port: 3000
targetPort: http-server
selector:
app: guestbook
type: LoadBalancer
```
**CiliumLoadBalancerIPPool**
```
apiVersion: cilium.io/v2alpha1
kind: CiliumLoadBalancerIPPool
metadata:
name: guestbook-pool
labels:
app: guestbook
spec:
blocks:
- cidr:
serviceSelector:
matchExpressions:
- { key: app, operator: In, values: [ guestbook ] }
```
**CiliumBGPAdvertisement**
```
apiVersion: cilium.io/v2alpha1
kind: CiliumBGPAdvertisement
metadata:
name: bgp-advertisements-guestbook
labels:
advertise: bgp
spec:
advertisements:
- advertisementType: "Service"
service:
addresses:
- ExternalIP
- LoadBalancerIP
selector:
matchExpressions:
- { key: app, operator: In, values: [ guestbook ] }
```
**Calico 故障排除**
如果您在混合节点上运行 Calico 时遇到问题，请参阅 Calico 文档中的[故障排除步骤](https://docs.tigera.io/calico/latest/operations/troubleshoot/)。以下章节介绍了在混合节点上部署 Calico 时可能遇到的特有问题。
下表总结了 Calico 的组件以及这些组件默认情况下是在节点网络还是在容器组网络上运行。如果将 Calico 配置为使用 NAT 来处理传出的容器组流量，则必须将本地网络配置为将流量路由到本地节点 CIDR，并且 VPC 路由表必须配置本地节点 CIDR 的路由，并将中转网关（TGW）或虚拟专用网关（VGW）作为目标。如果未将 Calico 配置为使用 NAT 来处理传出的容器组流量，则必须将本地网络配置为将流量路由到本地容器组 CIDR，并且 VPC 路由表必须配置本地容器组 CIDR 的路由，并将中转网关（TGW）或虚拟专用网关（VGW）作为目标。
| 组件 | Network |
| --- | --- |
| Calico API 服务器 | 节点 |
| 适用于 Kubernetes 的 Calico 控制器 | Pod |
| Calico 节点代理 | 节点 |
| Calico `typha` | 节点 |
| Calico CSI 节点驱动程序 | Pod |
| Calico 操作符 | 节点 |
**Calico 资源在封锁的节点上调度或运行**
默认情况下，不作为 DaemonSet 运行的 Calico 资源具有灵活的容忍度，可以将其调度到尚未准备好调度或运行容器组的封锁节点上。您可以通过更改操作符安装来包括以下内容，从而收紧对非 DaemonSet Calico 资源的容忍度。
```
installation:
...
controlPlaneTolerations:
- effect: NoExecute
key: node.kubernetes.io/unreachable
operator: Exists
tolerationSeconds: 300
- effect: NoExecute
key: node.kubernetes.io/not-ready
operator: Exists
tolerationSeconds: 300
calicoKubeControllersDeployment:
spec:
template:
spec:
tolerations:
- effect: NoExecute
key: node.kubernetes.io/unreachable
operator: Exists
tolerationSeconds: 300
- effect: NoExecute
key: node.kubernetes.io/not-ready
operator: Exists
tolerationSeconds: 300
typhaDeployment:
spec:
template:
spec:
tolerations:
- effect: NoExecute
key: node.kubernetes.io/unreachable
operator: Exists
tolerationSeconds: 300
- effect: NoExecute
key: node.kubernetes.io/not-ready
operator: Exists
tolerationSeconds: 300
```
## 凭证故障排除
对于 AWS SSM 混合激活和 AWS IAM Roles Anywhere，您都可以通过在混合节点上运行以下命令来验证混合节点上的混合节点 IAM 角色凭证配置是否正确。确认节点名称和混合节点 IAM 角色名称是否符合预期。
```
sudo aws sts get-caller-identity
```
```
{
"UserId": "ABCDEFGHIJKLM12345678910:",
"Account": "",
"Arn": "arn:aws:sts:::assumed-role/"
}
```
** AWSSystems Manager（SSM）故障排除**
如果将 AWS SSM 混合激活用作混合节点凭证，请注意以下将由 `nodeadm` 在混合节点上安装的 SSM 目录和构件。有关更多信息，请参阅《AWS Systems Manager 用户指南》**中的[使用 SSM Agent](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent.html)。
| 说明 | 位置 |
| --- | --- |
| SSM 代理 | Ubuntu – `/snap/amazon-ssm-agent/current/amazon-ssm-agent` RHEL 和 AL2023 – `/usr/bin/amazon-ssm-agent` |
| SSM 代理日志 | `/var/log/amazon/ssm` |
| AWS 凭证 | `/root/.aws/credentials` |
| SSM 安装 CLI | `/opt/ssm/ssm-setup-cli` |
**重新启动 SSM Agent**
有些问题可以通过重新启动 SSM Agent 来解决。您可以使用以下命令重新启动此代理。
**AL2023 和其他操作系统**
```
systemctl restart amazon-ssm-agent
```
**Ubuntu** -
```
systemctl restart snap.amazon-ssm-agent.amazon-ssm-agent
```
**检查与 SSM 端点的连接**
确认您可以从混合节点连接到 SSM 端点。有关 SSM 端点列表，请参阅 [AWS Systems Manager endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/ssm.html)。对于 AWS SSM 混合激活，请将以下命令中的 `us-west-2` 替换为 AWS 区域。
```
ping ssm.us-west-2.amazonaws.com
```
**查看已注册 SSM 实例的连接状态**
您可以使用以下 AWS CLI 命令检查通过 SSM 混合激活注册的实例的连接状态。请将 machine ID 替换为实例的机器 ID。
```
aws ssm get-connection-status --target mi-012345678abcdefgh
```
**SSM 安装 CLI 校验和不匹配**
运行 `nodeadm install` 时，如果您发现 `ssm-setup-cli` 校验和不匹配问题，应确认主机上没有早期版本的现有 SSM 安装。如果您的主机上有早期版本的 SSM 安装，请将其移除并重新运行 `nodeadm install` 以解决问题。
```
Failed to perform agent-installation/on-prem registration: error while verifying installed ssm-setup-cli checksum: checksum mismatch with latest ssm-setup-cli.
```
**SSM `InvalidActivation`**
如果您在将实例注册到 AWS SSM 时看到错误，请确认 `nodeConfig.yaml` 中的 `region`、`activationCode` 和 `activationId` 正确无误。EKS 集群的 AWS 区域必须与 SSM 混合激活区域一致。如果这些值的配置错误，则可能会看到与以下类似的错误。
```
ERROR Registration failed due to error registering the instance with AWS SSM. InvalidActivation
```
**SSM `ExpiredTokenException`：请求中包含的安全令牌已过期**
如果 SSM Agent 无法刷新凭证，您可能会看到 `ExpiredTokenException`。在这种情况下，如果能够从混合节点连接到 SSM 端点，则可能需要重新启动 SSM Agent 以强制刷新凭证。
```
"msg":"Command failed","error":"operation error SSM: DescribeInstanceInformation, https response error StatusCode: 400, RequestID: eee03a9e-f7cc-470a-9647-73d47e4cf0be, api error ExpiredTokenException: The security token included in the request is expired"
```
**运行注册计算机命令时出现 SSM 错误**
如果在将计算机注册到 SSM 时看到错误，则可能需要重新运行 `nodeadm install` 以确保正确安装所有 SSM 依赖项。
```
"error":"running register machine command: , error: fork/exec /opt/aws/ssm-setup-cli: no such file or directory"
```
**SSM `ActivationExpired`**
运行 `nodeadm init` 时，如果在将实例注册到 SSM 时因激活已过期而出现错误，则需要创建新的 SSM 混合激活，使用新 SSM 混合激活的 `activationCode` 和 `activationId` 更新 `nodeConfig.yaml`，然后重新运行 `nodeadm init`。
```
"msg":"Command failed","error":"SSM activation expired. Please use a valid activation"
```
```
ERROR Registration failed due to error registering the instance with AWS SSM. ActivationExpired
```
**SSM 刷新缓存的凭证失败**
如果发现无法刷新缓存的凭证，则说明 `/root/.aws/credentials` 文件可能已从主机中删除。首先检查您的 SSM 混合激活并确保其处于活动状态，并且混合节点已正确配置为使用该激活。检查 `/var/log/amazon/ssm` 中的 SSM Agent 日志，并在解决 SSM 端的问题后重新运行 `nodeadm init` 命令。
```
"Command failed","error":"operation error SSM: DescribeInstanceInformation, get identity: get credentials: failed to refresh cached credentials"
```
**清理 SSM**
要从主机上移除 SSM Agent，可以运行以下命令。
```
dnf remove -y amazon-ssm-agent
sudo apt remove --purge amazon-ssm-agent
snap remove amazon-ssm-agent
rm -rf /var/lib/amazon/ssm/Vault/Store/RegistrationKey
```
** AWSIAM Roles Anywhere 故障排除**
如果将 AWS IAM Roles Anywhere 用作混合节点凭证，请注意将由 `nodeadm` 在混合节点上安装的以下目录和构件。有关 IAM Roles Anywhere 故障排除的更多信息，请参阅《AWS IAM Roles Anywhere 用户指南》**中的 [Troubleshooting AWS IAM Roles Anywhere identity and access](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/security_iam_troubleshoot.html)。
| 说明 | 位置 |
| --- | --- |
| IAM Roles Anywhere CLI | `/usr/local/bin/aws_signing_helper` |
| 默认证书位置和名称 | `/etc/iam/pki/server.pem` |
| 默认密钥位置和名称 | `/etc/iam/pki/server.key` |
**IAM Roles Anywhere 刷新缓存的证书失败**
如果您发现刷新缓存的证书失败，请检查 `/etc/aws/hybrid/config` 的内容并确认 `nodeadm` 配置中正确配置了 IAM Roles Anywhere。确认 `/etc/iam/pki` 存在。每个节点都必须具有唯一的证书和密钥。默认情况下，凭证提供者为 IAM Roles Anywhere 作时，`nodeadm` 将 `/etc/iam/pki/server.pem` 作为证书位置和名称，并将 `/etc/iam/pki/server.key` 作为私有密钥。在将证书和密钥放入目录之前，您可能需要首先使用 `sudo mkdir -p /etc/iam/pki` 创建目录。您可以使用以下命令验证证书的内容。
```
openssl x509 -text -noout -in server.pem
```
```
open /etc/iam/pki/server.pem: no such file or directory
could not parse PEM data
Command failed {"error": "... get identity: get credentials: failed to refresh cached credentials, process provider error: error in credential_process: exit status 1"}
```
**IAM Roles Anywhere 无权执行 `sts:AssumeRole`**
在 `kubelet` 日志中，如果您在使用 IAM Roles Anywhere 时看到 `sts:AssumeRole` 操作出现访问被拒绝的问题，请检查混合节点 IAM 角色的信任策略，以确认允许 IAM Roles Anywhere 服务主体代入该混合节点 IAM 角色。此外，请确认在混合节点 IAM 角色信任策略中正确配置了信任锚 ARN，并且已将混合节点 IAM 角色添加到 IAM Roles Anywhere 配置文件中。
```
could not get token: AccessDenied: User: ... is not authorized to perform: sts:AssumeRole on resource: ...
```
**IAM Roles Anywhere 无权设置 `roleSessionName`**
在 `kubelet` 日志中，如果您发现设置 `roleSessionName` 时出现访问被拒绝的问题，请确认您已将 IAM Roles Anywhere 配置文件的 `acceptRoleSessionName` 设置为 true。
```
AccessDeniedException: Not authorized to set roleSessionName
```
## 操作系统故障排除
### RHEL
**授权或订阅管理器注册失败**
如果您运行的是 `nodeadm install`，但由于授权注册问题而无法安装混合节点依赖项，请确保在主机上正确设置了 Red Hat 用户名和密码。
```
This system is not registered with an entitlement server
```
### Ubuntu
**找不到 GLIBC**
如果您的操作系统为 Ubuntu 操作系统，混合节点的凭证提供者为 IAM Roles Anywhere，但出现找不到 GLIBC 的问题，则可以通过手动安装该依赖项来解决问题。
```
GLIBC_2.32 not found (required by /usr/local/bin/aws_signing_helper)
```
运行以下命令安装依赖项：
```
ldd --version
sudo apt update && apt install libc6
sudo apt install glibc-source
```
### Bottlerocket
如果启用了 Bottlerocket 管理容器，则可以使用 SSH 访问该容器，从而使用更高的权限进行高级调试和故障排除。以下章节包含需要在 Bottlerocket 主机的上下文中运行的命令。进入管理容器后，您可以运行 `sheltie` 来获取 Bottlerocket 主机中的完整根 Shell。
```
sheltie
```
此外还可以通过在各个命令前加上前缀 `sudo chroot /.bottlerocket/rootfs`，从而在管理容器 Shell 中运行以下章节中的命令。
```
sudo chroot /.bottlerocket/rootfs
```
**使用 logdog 收集日志**
Bottlerocket 提供了 `logdog` 实用程序，可用来高效地收集日志和系统信息，以满足故障排除的需要。
```
logdog
```
`logdog` 实用程序可从 Bottlerocket 主机的不同位置收集日志，然后组合成压缩包。默认情况下，该压缩包将在 `/var/log/support/bottlerocket-logs.tar.gz` 位置创建，并且可以从主机容器的 `/.bottlerocket/support/bottlerocket-logs.tar.gz` 位置访问。
**使用 journalctl 访问系统日志**
您可以使用以下命令检查各种系统服务（例如 `kubelet`、`containerd` 等）的状态以及查看其日志。`-f` 标志会实时跟踪日志。
要检查 `kubelet` 服务状态和检索 `kubelet` 日志，您可以运行以下命令：
```
systemctl status kubelet
journalctl -u kubelet -f
```
要检查 `containerd` 服务状态和检索已编排的 `containerd` 实例的日志，您可以运行以下命令：
```
systemctl status containerd
journalctl -u containerd -f
```
要检查 `host-containerd` 服务状态和检索主机 `containerd` 实例的日志，您可以运行以下命令：
```
systemctl status host-containerd
journalctl -u host-containerd -f
```
要检索引导容器和主机容器的日志，您可以运行以下命令：
```
journalctl _COMM=host-ctr -f
```