為什麼我無法使用 kubectl 連線到 EKS 叢集？

解決方法

如果您在使用 kubectl 時無法連線到 Amazon EKS 叢集，那麼您的服務、權限或設定可能設定有錯。當本機環境無法與 EKS 叢集的 API 伺服器通訊時，也會發生錯誤。根據您收到的錯誤訊息進行疑難排解。

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

先決條件：

• 執行以下命令，檢查系統是否可以與正確的叢集建立連線：

  kubectl config current-context

• 執行下列 get-caller-identity AWS CLI 命令，確認目前經過驗證的 AWS Identity and Access Management (IAM) 使用者或角色是否正確：

  aws sts get-caller-identity

  **注意：**允許 IAM 主體根據叢集驗證模式存取叢集上的 Kubernetes 物件。

"exec plugin invalid" 錯誤訊息

當 kubeconfig 檔案中的驗證 API 版本與 Kubernetes API 控制平面版本不相容時，您會收到以下錯誤訊息：

"exec plugin: invalid apiVersion "client.authentication.k8s.io/v1alpha""

執行以下 update-kubeconfig 命令，以更新叢集的 kubeconfig 檔案：

aws eks update-kubeconfig --region region-code --name my-cluster

**注意：**將 region-code 替換為您叢集所在的 AWS 區域，並將 my-cluster 替換為您叢集的名稱。

您的 kubectl 版本必須與 Amazon EKS 叢集控制平面的版本號碼相差不超過一個次版本。例如，kubectl 版本 1.29 用戶端可與 Kubernetes 1.28、1.29 和 1.30 叢集搭配使用。

"couldn't get current server API group list" 錯誤訊息

當 kubeconfig 檔案不存在或不包含憑證認證機構 (CA) 時，您會收到下列錯誤訊息：

"couldn't get current server API group list: Get "https://xxxxxxxxxxxxxxxxxxxx..eks.amazonaws.com/api?timeout=32s": tls: failed to verify certificate: x509: certificate signed by unknown authority"

1. 執行以下命令，檢查主目錄中的預設位置 (.kube) 中是否存在 kubeconfig 檔案：

   cat ~/.kube/config

2. 如果該檔案存在，請確認 base64 編碼的叢集 CA 是否存在於 kubeconfig 檔案中。另外，請檢查 certificate-authority-data 檔案是否存在，以及您是否已正確設定。

3. 如果 kubeconfig 檔案不存在，請執行以下命令重新建立：

   kubectl get svc --insecure-skip-tls-verify

4. 檢查您是否使用了可能封鎖 TLS 的 Proxy 或 VPN。

"could not get current server API group list" 逾時錯誤訊息

如果來源主機無法與連接埠 443 上的 API 伺服器通訊，則請求將逾時，並且您會收到以下錯誤訊息：

"could not get current server API group list: Get "https://xxxxxxxxxxxxxxxxxxxx.gr7.<region-code>.eks.amazonaws.com/api?timeout=32s": dial tcp xx.yy.zz.vvv:443: i/o timeout"

執行以下命令，使用連接埠 443 上的 telnet 檢查裝置的 API 伺服器端點連線：

$ echo exit | telnet

輸出範例：

xxxxxxxxxxxxxxxxxxxx.gr7.us-east-2.eks.amazonaws.com 443Trying 18.224.160.210...
Connected to xxxxxxxxxxxxxxxxxxxx.gr7.us-east-2.eks.amazonaws.com.
Escape character is '^]'.
Connection closed by foreign host.

如果 telnet 命令無法解決問題，請執行下列動作：

• 如果您在 API 伺服器端點上啟動了公開存取，請檢查是否將對 API 伺服器端點的存取權限制在特定的 CIDR 範圍內。確認裝置的 IP 位址屬於 CIDR 區塊。另外，請檢查 API 伺服器端點存取行為。
• 如果您僅在 API 伺服器端點上啟動了私有存取，則所有叢集 API 伺服器流量都必須來自虛擬私有雲端 (VPC) 或連線的網路。此外，kubectl 命令必須來自 VPC 或已連線的網路內部。如需詳細資訊，請參閱僅限私有 API 伺服器的存取。
• 檢查安全群組或網路存取控制清單 (網路 ACL) 是否封鎖對 Kubernetes API 伺服器的請求。確認叢集安全群組允許來自來源 CIDR 的流量通過連接埠 443。

"couldn't get current API server group list" 錯誤訊息

當您嘗試執行某項動作，但沒有權限存取 Amazon EKS 叢集上的 Kubernetes API 時，您會收到以下錯誤訊息：

"couldn't get current server API group list: the server has asked for the client to provide credentials"

若要解決此問題，請完成下列步驟：

1. 執行 get-caller-identity 命令，檢查誰提出了存取 EKS 叢集的請求：

   aws sts get-caller-identity

   輸出範例：

   {
    "UserId": "user-ID",
    "Account": "account-ID",
    "Arn": "arn:aws:iam::account-ID:user/kube-user"
   }

   **注意：**上述範例輸出包含發出請求的 IAM 實體的使用者 ID、AWS 帳戶和 ARN。

2. 將驗證模式改為 API_AND_CONFIG_MAP 或 API，然後使用 EKS 存取項目授予 IAM 使用者存取 Kubernetes 的權限。

3. 若要授予適當的權限，請使用 API 或 API_AND_CONFIG_MAP 驗證模式新增 IAM 實體的項目。
   API 驗證模式
   執行以下 create-access-entry 以建立存取項目，讓 IAM 主體能驗證您的 Amazon EKS 叢集：

   aws eks create-access-entry --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:user/my-user --type STANDARD --username my-user

   **注意：**在上述命令中，將主體 ARN 替換為您 IAM 實體的 ARN。
   執行以下 associate-access-policy 命令，將存取項目與存取政策建立關聯：

   aws eks associate-access-policy --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:role/my-role \
       --access-scope type=cluster --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSViewPolicy

   API_AND_CONFIG_MAP 驗證模式
   對於 API_AND_CONFIG_MAP 驗證模式，您可以使用上述的 API 驗證模式，也可以編輯 configmap。
   若要編輯 aws-auth configmap，請執行下列命令：

   kubectl edit configmap aws-auth -n kube-system

   將您的 IAM 角色或使用者新增至 mapRoles 或 mapUsers 區段。
   以下是包含 IAM 角色項目的 mapRoles 區段範例：

   mapRoles: |
       - groups:
         - system:masters
         rolearn: arn:aws:iam::111122223333:role/MyEKSrole
         username: eks-user

   **注意：**將範例 ARN 替換為您 IAM 角色的 ARN。如果您使用的是 IAM 使用者，則將 MapRoles 替換為 MapUsers，並將 ARN 替換為 IAM 使用者的 ARN。

上述範例會將 IAM 主體對應到授予叢集完全管理存取權的 system:masters 群組。如需更嚴格的存取權，請將 IAM 主體對應到自訂 Kubernetes 使用者或群組，並使用 Kubernetes 角色型存取控制 (RBAC) 物件來定義必要的權限。如需詳細資訊，請參閱 Kubernetes 網站上的使用 RBAC 授權。

"Did you specify the right host or port?" 錯誤訊息

如果您未正確設定 kubeconfig 文件，則 kubectl 無法連線到 EKS 叢集，並且您會收到以下錯誤訊息：

"The connection to the server localhost:8080 was refused - did you specify the right host or port?"

若要解決此問題，請執行下列動作：

• 執行以下命令來更新 kubeconfig 檔案：

  aws eks update-kubeconfig --region region-code --name my-cluster

• 執行以下命令檢查目前 kubeconfig 檔案中的內容：

  kubectl config current-context

• 如果 current-context 命令的輸出未指向預期的 EKS 叢集，請執行以下命令：

  kubectl config use-context ;

相關資訊

透過建立 kubeconfig 檔案，將 kubectl 連線到 EKS 叢集