如何對 Amazon EKS 的 Amazon VPC CNI 外掛的問題進行疑難排解？

解決方法

**注意：**如果您在執行 AWS Command Line Interface (AWS CLI) 命令時收到錯誤訊息，請參閱對 AWS CLI 錯誤進行疑難排解。此外，請確定您使用的是最新的 AWS CLI 版本。

如果由於 Amazon VPC CNI 附加元件未初始化，而導致工作節點尚未準備就緒，那麼您將收到類似於以下範例的錯誤訊息：

"container runtime network not ready: NetworkReady=false reason:NetworkPluginNotReady message:Network plugin returns error: cni plugin not initialized" (容器運行時網路尚未準備好：NetworkReady=false 原因：NetworkPluginNotReady 訊息：網頁外掛程式傳回錯誤：cni 外掛程式未初始化」

若要檢查此問題，請執行下列命令：

kubectl describe node node_name

**注意：**將 node_name 替換為節點的名稱。您可以在輸出中找到 cni plugin no initialed (cni 外掛程式未初始化) 錯誤訊息。

請執行下列動作對該問題進行疑難排解。

確認您已安裝 Amazon VPC CNI 附加元件

如果叢集中缺少 aws-node Pod，那麼您會在 containerd 日誌中收到類似下列範例的錯誤訊息：

"cni config load failed: no network config found in /etc/cni/net.d: cni plugin not initialized: failed to load cni config" (「cni 組態載入失敗：在 /etc/cni/net.d 中找不到網路組態：cni 外掛程式未初始化：無法載入 cni 組態」)

若要解決此問題，請安裝 Amazon VCP CNI 附加元件。

檢查 IAM 權限問題

若要使用 Amazon VPC CNI 附加元件，請使用 AmazonEKS_CNI_Policy AWS Identity and Access Management (IAM) 受管政策。或者，如果您使用自訂政策，請確定其包含下列權限：

 "ec2:AssignPrivateIpAddresses",
 "ec2:AttachNetworkInterface",
 "ec2:CreateNetworkInterface",
 "ec2:DeleteNetworkInterface",
 "ec2:DescribeInstances",
 "ec2:DescribeTags",
 "ec2:DescribeNetworkInterfaces",
 "ec2:DescribeInstanceTypes",
 "ec2:DescribeSubnets",
 "ec2:DetachNetworkInterface",
 "ec2:ModifyNetworkInterfaceAttribute",
 "ec2:UnassignPrivateIpAddresses"
 "ec2:CreateTags"

若要識別缺少的 IAM 權限，請檢查 /var/log/aws-routed-eni/ipamd.log 主機目錄中的 L-IPAM 常駐程式 (IPAMD) 日誌。如果 Amazon VPC CNI 附加元件沒有必要的 IAM 權限，那麼您會收到類似下列範例的錯誤訊息：

{"level":"error","ts":"2023-11-18T01:08:34.083Z","caller":"aws-k8s-agent/main.go:28","msg":"Initialization failure: ipamd init: failed to retrieve attached ENIs info: UnauthorizedOperation: You are not authorized to perform this operation.User: arn:aws:sts::XXXXXXXXXXXXXXXXXXXX:assumed-role/rolename is not authorized to perform: ec2:DescribeNetworkInterfaces because no identity-based policy allows the ec2:DescribeNetworkInterfaces action\n\tstatus code: 403, request id: request id"} (「"level":"error","ts":"2023-11-18T01:08:34.083Z","呼叫者":"aws-k8s-agent/main.go:28","msg":"初始化失敗：ipamd init：無法擷取附加的 ENI 資訊：UnauthorizedOperation：您未獲授權執行此作業。使用者：arn:aws:sts::XXXXXXXXXXXXXXXXXXXX:assumed-role/rolename 未獲授權執行：ec2:DescribeNetworkInterfaces，因為沒有身分型政策允許 ec2:DescribeNetworkInterfaces 動作\n\t狀態代碼：403，請求 ID：請求 ID」)

上述範例錯誤訊息表示該附加元件需要 ec2:DescribeNetworkInterfaces 權限。

如果您無法直接存取工作節點，請檢查工作器節點上的 aws-node Pod。若要辨識工作節點上的 aws-node Pod，請執行下列命令：

kubectl describe node node_name

**注意：**將 node_name 替換為節點的名稱。檢查輸出的 Non-terminated Pods 區段，找出 aws-node Pod 名稱。

然後，執行以下命令以查看有關 aws-node Pod 的詳細資訊：

kubectl describe pod pod-name -n kube-system

**注意：**將 pod-name 替換為 aws-node Pod 名稱。

在輸出中，檢查 Event 以取得缺少權限的資訊。

輸出範例：

Type Reason Age From Message
---- ------ ---- ---- -------
Warning MissingIAMPermissions 105s (x2 over 105s) aws-node Unauthorized operation: failed to call ec2:DescribeNetworkInterfaces due to missing permissions. Please refer https://github.com/aws/amazon-vpc-cni-k8s/blob/master/docs/iam-policy.md to attach relevant policy to IAM role in the event section you can able to see the error message also you can check the AWS cloud trail event for the particular instance by filtering the cloudtrail with username and provide the instanceID there.

或者，使用 AWS CloudTrail 檢查特定事件。例如，檢查 DescribeNetworkInterfaces API 呼叫的使用者名稱和執行個體 ID，以確定呼叫是否已執行。

檢查網路問題

Amazon VPC CNI 附加元件執行時必須到達 API 伺服器端點和 Amazon Elastic Compute Cloud (Amazon EC2) 端點。如果任一連線失敗，則附加元件無法初始化，且節點將進入 NotReady 狀態。

若要檢查特定的錯誤訊息，請查看 /var/log/aws-routed-eni/ipamd.log 主機目錄中的 IPAMD 日誌。確認 kube-proxy 和 coreDNS Pod 可以正常運作。

檢查附加元件版本

最佳做法是將核心元件更新到最新版本。如果附加元件版本不符合您的 Kubernetes 叢集版本，則該附加元件無法初始化。確定附加元件版本與 Kubernetes 叢集版本相容。

對 Amazon VPC CNI 附加元件錯誤進行疑難排解

若要識別附加元件錯誤，請使用 SSH 連線到附加元件無法指派 IP 位址的工作節點。然後，檢查 /var/log/aws-routed-eni/ipamd.log 檔案中的 IPAMD 日誌是否有錯誤訊息。

無法指派 IP 錯誤

當 Amazon VPC CNI 附加元件無法為排程到工作節點的 Pod 指派 IP 位址時，就會發生 Failed to assign ip (無法指派 IP) 錯誤。若要辨識錯誤，您也可以檢查 CloudTrail 事件歷史記錄頁面中的 AssignPrivateIpAddresses 事件。

若要判斷指派的子網路是否沒有可用的 IP 位址，請執行以下 describe-subnets AWS CLI 命令：

aws ec2 describe-subnets --filters "Name=vpc-id,Values= VPCID" | jq '.Subnets[] | .SubnetId + "=" + "\(.AvailableIpAddressCount)"'

**注意：**將 VPCID 替換為您的 VPC ID。

當您將 WARM_ENI_TARGET、WARM_IP_TARGET 或 MINIMUM_IP_TARGET 環境變數的值設得太低時，也可能會出現 Failed to assign ip (無法指派 IP) 錯誤。請確認您的子網路 CIDR 範圍夠寬，並為您的使用案例提供了足夠的 IP 位址分配。如需詳細資訊，請參閱 GitHub 網站上的 WARM\ENI\TARGET、WARM\IP\TARGET 和 MINIMUM_IP_TARGET。

若要檢查環境變數的值，請執行下列命令，以查看您的 Pod 詳細資訊：

kubectl describe pod pod-name -n kube-system

**注意：**將 pod-name 替換為 aws-node Pod 名稱。

您可以更新 aws-node DaemonSet 中的環境變數：

env:
  - name: WARM_ENI_TARGET
    value: "1"
  - name: WARM_IP_TARGET
    value: "5"
  - name: MINIMUM_IP_TARGET
    value: "25"

或者，執行下列命令以更新環境變數：

kubectl set env ds aws-node -n kube-system WARM_ENI_TARGET=1 WARM_IP_TARGET=5 MINIMUM_IP_TARGET=25

如果您使用首碼委派模式且不使用專用的 Pod 子網路範圍，則子網路碎片化可能會導致附加元件失敗。此附加元件必須為網路介面指派連續的 /28 (用於 IPv4) 和 /80 (用於 IPv6) 首碼範圍。如需首碼委派的詳細資訊，請參閱 GitHub 網站上的 ENABLE_PREFIX_DELEGATION。

您無法直接檢查子網路是否發生碎片化。請改為檢查子網路 CIDR 範圍中是否仍有超過 16 個可用的 IP 位址。如果您有足夠的 IP 位址，但仍然頻繁收到Failed to assign ip (無法指派 IP) 錯誤，那麼問題通常是子網路碎片化造成的。若要對此問題進行疑難排解，最佳做法是使用首碼委派的自訂網路來為 Pod 建立專用子網路。如需詳細資訊，請參閱 GitHub 網站上的 AWS_VPC_K8S_CNI_CUSTOM_NETWORK_CFG。

Failed to get pod ENI config (無法取得 Pod ENI 組態) 錯誤

如果您使用 AWS_VPC_K8S_CNI_CUSTOM_NETWORK_CFG 來啟用自訂網路，但未建立 ENIConfig 資源，那麼您會收到類似下列範例的錯誤訊息：

"{"level":"error","ts":"","caller":"ipamd/ipamd.go:798","msg":"Failed to get pod ENI config"}" (「{level":"error","ts":"","caller":"ipamd/ipamd.go:798","msg":"無法取得 pod ENI 組態"}」)

若要檢查叢集中是否存在 ENIConfig 資源，請執行下列命令：

kubectl get eniconfig -o yaml

如果 ENIConfig 自訂資源不存在，請建立資源。如需自訂網路的詳細資訊，請參閱 GitHub 網站上的 AWS_VPC_K8S_CNI_CUSTOM_NETWORK_CFG。

Failed to watch (無法觀看) 錯誤

如果您沒有以正確的格式編寫 YAML 檔案，那麼您可能會收到類似於以下範例的錯誤訊息：

"Failed to watch *v1alpha1.ENIConfig: failed to list *v1alpha1.ENIConfig:json: cannot unmarshal string into Go struct field ENIConfigSpec.items.spec.securityGroups of type []string" (「無法觀看 *v1alpha1.ENIConfig：無法列出 *v1alpha1.ENIConfig:json：無法將字串解譯為 Go 結構中 ENIConfigSpec.items.spec.securityGroups 欄位的 []string 類型」)

當 JSON 資料與 Go 資料類型定義之間不相符時，通常會發生此問題。上述範例錯誤訊息表示 securityGroups 欄位存在問題。

若要解決此問題，請執行下列命令來檢查您的 JSON 資料：

kubectl describe ENIConfig

在命令的輸出中，根據錯誤訊息中找出的問題檢查語法。例如，確保 JSON 中的 securityGroups 欄位是字串數組，而不是單一字串。

輸出範例：

cat >$az_1.yaml <<EOF
apiVersion: crd.k8s.amazonaws.com/v1alpha1
kind: ENIConfig
metadata:
  name: us-west-2a
spec:
  securityGroups:
    - sg-0123456789abcdef0
  subnet: subnet-0123456789abcdef0
EOF