**協助改進此頁面** 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 若要為本使用者指南貢獻內容，請點選每個頁面右側面板中的**在 GitHub 上編輯此頁面**連結。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Outposts 上的本機 Amazon EKS AWS 叢集疑難排解 本主題涵蓋一些使用本機叢集時可能遇到的常見錯誤與排除這些錯誤的方法。雖然本機叢集與雲端中的 Amazon EKS 叢集相似，但 Amazon EKS 管理本機叢集的方式仍有些許差異。 **重要** 除非 AWS Support 明確指示，否則請勿終止在 Outpost 上執行的任何受管 EKS 本機叢集`Kubernetes`控制平面執行個體。終止這些執行個體會對本機叢集服務可用性帶來風險，包括在同時終止多個執行個體時，遺失本機叢集。EC2 執行個體主控台上的 `eks-local:controlplane-name` 標籤可識別 EKS 本機叢集 `Kubernetes` 控制平面執行個體。 ## API 行為 本機叢集透過 Amazon EKS API 建立，但會以非同步方式執行。這表示本機叢集對 Amazon EKS API 的請求會立即傳回。但是，這些請求可能會成功、因輸入驗證錯誤而快速檢錯，或失敗並附上描述性驗證錯誤。此行為與 Kubernetes API 相似。 本機叢集不會變為 `FAILED` 狀態。Amazon EKS 會嘗試以連續的方式使叢集狀態與使用者請求的所需狀態一致。因此，本機叢集可能會長期保持在 `CREATING` 狀態，直到基礎問題解決為止。 ## 描述叢集運作狀態欄位 您可以使用 [describe-cluster](https://docs.aws.amazon.com/cli/latest/reference/eks/describe-cluster.html) Amazon EKS AWS CLI 命令來發現本機叢集問題。本機叢集問題可透過 `describe-cluster` 命令回應的 `cluster.health` 欄位顯露。此欄位內含的訊息包括錯誤代碼、描述性訊息和相關資源 ID。此資訊僅可透過 Amazon EKS API 和 AWS CLI 取得。在以下範例中，使用您本機叢集的名稱取代 *my-cluster*。 ``` aws eks describe-cluster --name my-cluster --query 'cluster.health' ``` 範例輸出如下。 ``` { "issues": [ { "code": "ConfigurationConflict", "message": "The instance type 'm5.large' is not supported in Outpost 'my-outpost-arn'.", "resourceIds": [ "my-cluster-arn" ] } ] } ``` 如果問題無法解決，您可能需要刪除本機叢集並建立新叢集。例如，嘗試使用在 Outpost 上未提供的執行個體類型佈建叢集。下表包含與運作狀態相關的常見錯誤。 | 錯誤情況 | 代碼 | 訊息 | ResourceIds | | --- | --- | --- | --- | | 找不到提供的子網路。 | `ResourceNotFound` | `The subnet ID subnet-id does not exist` | 所有提供的子網路 ID | | 提供的子網路不屬於同一 VPC。 | `ConfigurationConflict` | `Subnets specified must belong to the same VPC` | 所有提供的子網路 ID | | 某些提供的子網路不屬於指定的 Outpost。 | `ConfigurationConflict` | `Subnet subnet-id expected to be in outpost-arn, but is in other-outpost-arn ` | 有問題的子網路 ID | | 某些提供的子網路不屬於任何 Outpost。 | `ConfigurationConflict` | `Subnet subnet-id is not part of any Outpost` | 有問題的子網路 ID | | 某些提供的子網路沒有足夠的可用地址來為控制平面執行個體建立彈性網路介面。 | `ResourceLimitExceeded` | `The specified subnet does not have enough free addresses to satisfy the request.` | 有問題的子網路 ID | | 您的 Outpost 不支援指定的控制平面執行個體類型。 | `ConfigurationConflict` | `The instance type type is not supported in Outpost outpost-arn ` | 叢集 ARN | | 您已終止控制平面 Amazon EC2 執行個體，或 `run-instance` 已成功，但觀察到的狀態變更為 `Terminated`。您的 Outpost 重新連線後一段時間可能會發生此情況，且 Amazon EBS 內部錯誤會導致 Amazon EC2 內部工作流程失敗。 | `InternalFailure` | `EC2 instance state "Terminated" is unexpected` | 叢集 ARN | | 您在 Outpost 上的容量不足。如果 Outpost 與 AWS 區域中斷連線，則在建立叢集時也會發生這種情況。 | `ResourceLimitExceeded` | `There is not enough capacity on the Outpost to launch or start the instance.` | 叢集 ARN | | 您的帳戶已超過您的安全群組配額。 | `ResourceLimitExceeded` | Amazon EC2 API 傳回的錯誤訊息 | 目標 VPC ID | | 您的帳戶已超過您的彈性網路介面配額。 | `ResourceLimitExceeded` | Amazon EC2 API 傳回的錯誤訊息 | 目標子網路 ID | | 無法透過 AWS Systems Manager 連線控制平面執行個體。如需解決方案，請參閱[無法透過 AWS Systems Manager 存取控制平面執行個體](#outposts-troubleshooting-control-plane-instances-ssm)。 | `ClusterUnreachable` | Amazon EKS 控制平面執行個體無法透過 SSM 連線。請確認您的 SSM 和網路組態，並參考 Outpost 上的 EKS 疑難排解文件。 | Amazon EC2 執行個體 ID | | 取得受管安全群組或彈性網路介面的詳細資訊時發生錯誤。 | 根據 Amazon EC2 用戶端錯誤代碼。 | Amazon EC2 API 傳回的錯誤訊息 | 所有受管的安全群組 ID | | 授權或撤銷安全群組輸入規則時發生錯誤。這適用於叢集和控制平面安全群組。 | 根據 Amazon EC2 用戶端錯誤代碼。 | Amazon EC2 API 傳回的錯誤訊息 | 有問題的安全群組 ID | | 刪除控制平面執行個體的彈性網路介面時發生錯誤。 | 根據 Amazon EC2 用戶端錯誤代碼。 | Amazon EC2 API 傳回的錯誤訊息 | 有問題的彈性網路介面 ID | 下表列出來自其他 AWS 服務的錯誤，這些錯誤會顯示在`describe-cluster`回應的運作狀態欄位中。 | Amazon EC2 錯誤代碼 | 叢集運作狀態問題代碼 | Description | | --- | --- | --- | | `AuthFailure` | `AccessDenied` | 基於各種原因，可能會發生此錯誤。最常見的原因是您意外移除了服務用於從控制平面縮小服務連結角色政策範圍的標籤。如果發生這種情況，Amazon EKS 將無法再管理和監控這些 AWS 資源。 | | `UnauthorizedOperation` | `AccessDenied` | 基於各種原因，可能會發生此錯誤。最常見的原因是您意外移除了服務用於從控制平面縮小服務連結角色政策範圍的標籤。如果發生這種情況，Amazon EKS 將無法再管理和監控這些 AWS 資源。 | | `InvalidSubnetID.NotFound` | `ResourceNotFound` | 找不到安全群組輸入規則的子網路 ID 時，會發生此錯誤。 | | `InvalidPermission.NotFound` | `ResourceNotFound` | 安全群組輸入規則的許可不正確時，會發生此錯誤。 | | `InvalidGroup.NotFound` | `ResourceNotFound` | 找不到安全群組輸入規則的群組時，會發生此錯誤。 | | `InvalidNetworkInterfaceID.NotFound` | `ResourceNotFound` | 找不到安全群組輸入規則的網路介面 ID 時，會發生此錯誤。 | | `InsufficientFreeAddressesInSubnet` | `ResourceLimitExceeded` | 超過子網路資源配額時，會發生此錯誤。 | | `InsufficientCapacityOnOutpost` | `ResourceLimitExceeded` | 超過 Outpost 容量配額時，會發生此錯誤。 | | `NetworkInterfaceLimitExceeded` | `ResourceLimitExceeded` | 超過彈性網路介面配額時，會發生此錯誤。 | | `SecurityGroupLimitExceeded` | `ResourceLimitExceeded` | 超過安全群組配額時，會發生此錯誤。 | | `VcpuLimitExceeded` | `ResourceLimitExceeded` | 在新帳戶中建立 Amazon EC2 執行個體時，便會觀察到這種狀況。此錯誤可能類似以下內容："`You have requested more vCPU capacity than your current vCPU limit of 32 allows for the instance bucket that the specified instance type belongs to. Please visit http://aws.amazon.com/contact-us/ec2-request to request an adjustment to this limit."` | | `InvalidParameterValue` | `ConfigurationConflict` | 如果 Outpost 不支援指定的執行個體類型，Amazon EC2 會傳回此錯誤代碼。 | | 所有其他失敗 | `InternalFailure` | 無 | ## 無法建立或修改叢集 本機叢集需要不同於雲端中託管的 Amazon EKS 叢集的許可和政策。叢集無法建立並產生 `InvalidPermissions` 錯誤時，再次檢查您使用的叢集角色是否擁有連接的 [AmazonEKSLocalOutpostClusterPolicy](security-iam-awsmanpol.md#security-iam-awsmanpol-amazonekslocaloutpostclusterpolicy) 受管政策。所有其他 API 呼叫需要與雲端中 Amazon EKS 叢集相同的許可集。 ## 叢集卡在 `CREATING` 狀態 建立本機叢集所需的時間量因數個因素而異。這些因素包括您的網路組態、Outpost 組態以及叢集的組態。一般而言，本機叢集會在 15-20 分鐘內建立並變更為 `ACTIVE` 狀態。如果本機叢集仍處於 `CREATING` 狀態，則您可以在 `cluster.health` 輸出欄位中呼叫 `describe-cluster` 以取得有關原因的資訊。 最常見的問題如下： + 您的叢集無法從 Systems Manager 所在的 AWS 區域連線至控制平面執行個體。您可以從區域內的堡壘主機呼叫 `aws ssm start-session --target instance-id ` 進行驗證。如果該命令不起作用，則請檢查 Systems Manager 是否在控制平面執行個體上執行。或者，另一個解決方法是刪除叢集，然後重新建立叢集。 + 由於 EBS 磁碟區的 KMS 金鑰許可，無法建立控制平面執行個體。使用加密 EBS 磁碟區的使用者受管 KMS 金鑰時，如果無法存取金鑰，控制平面執行個體將會終止。如果執行個體終止，請切換到 AWS 受管 KMS 金鑰，或確保您的使用者受管金鑰政策授予叢集角色必要的許可。 + Systems Manager 控制平面執行個體可能無法存取網際網路。檢查您在建立叢集時提供的子網路是否具有 NAT 閘道和具有網際網路閘道的 VPC。使用 VPC Reachability Analyzer 確認控制平面執行個體是否可連線至網際網路閘道。如需詳細資訊，請參閱 [Getting started with VPC Reachability Analyzer](https://docs.aws.amazon.com/vpc/latest/reachability/getting-started.html) (VPC Reachability Analyzer 入門)。 + 您提供的角色 ARN 缺少政策。檢查 [AWS 受管政策：AmazonEKSLocalOutpostClusterPolicy](security-iam-awsmanpol.md#security-iam-awsmanpol-amazonekslocaloutpostclusterpolicy) 是否已從角色中移除。如果 An AWS CloudFormation 堆疊設定錯誤，也可能發生這種情況。 + 所有提供的子網路必須與相同的 Outpost 關聯，並且必須互相連線。如果在建立叢集時指定多個子網路，Amazon EKS 會嘗試將控制平面執行個體散佈到多個子網路。 + Amazon EKS 受管的安全群組將套用至彈性網路介面。但是，其他組態元素 (例如 NACL 防火牆規則) 可能會與彈性網路介面的規則衝突。 + VPC 和子網路 DNS 組態設定錯誤或遺失。檢閱[在 AWS Outpost 上建立 Amazon EKS 叢集的 VPC 和子網路](eks-outposts-vpc-subnet-requirements.md)。 ## 叢集卡在 `UPDATING` 狀態 Amazon EKS 會自動將所有現有的本機叢集更新到與其對應之 Kubernetes 次要版本的最新平台版本。如需平台版本的詳細資訊，請參閱 [了解 AWS Outposts 的 Kubernetes 和 Amazon EKS 平台版本](eks-outposts-platform-versions.md)。 在自動平台版本推展期間，叢集狀態會變更為 `UPDATING`。更新程序包含將所有 Kubernetes 控制平面執行個體取代為新的執行個體，其中包含針對個別 Kubernetes 次要版本發行的最新安全修補程式和錯誤修正。一般而言，本機叢集平台更新程序會在 30 分鐘內完成，且叢集會變更回 `ACTIVE` 狀態。如果本機叢集長期保持在 `UPDATING` 狀態，則您可以呼叫 `describe-cluster`，以在 `cluster.health` 輸出欄位中檢查有關原因的資訊。 Amazon EKS 可確保 3 個 Kubernetes 控制平面執行個體中至少有 2 個是運作狀態良好的操作叢集節點，以維持本機叢集可用性並防止服務中斷。如果本機叢集停滯在 `UPDATING` 狀態，通常是因為存在一些基礎結構或組態問題，導致在程序繼續進行的情況下，無法保證至少有兩個執行個體可用。因此，為防止本機叢集服務中斷，更新程序會停止。 請務必對停滯在 `UPDATING` 狀態的本機叢集進行孤故障診斷，並解決根本原因，以便更新程序可以完成，並將本機叢集還原為 `ACTIVE` 狀態，且達到 3 個 Kubernetes 控制平面執行個體的高可用性。 除非 AWS Support 明確指示，否則請勿終止 Outposts 上的任何受管 EKS 本機叢集`Kubernetes`執行個體。這對卡在 `UPDATING` 狀態的本機叢集尤其重要，因為另一個控制平面節點可能無法完全正常運作，且終止錯誤的執行個體可能會導致服務中斷，並造成本機叢集資料遺失的風險。 最常見的問題如下： + 由於自本機叢集首次建立以來發生聯網組態變更，因此一或多個控制平面執行個體無法連接至 System Manager。您可以從區域內的堡壘主機呼叫 `aws ssm start-session --target instance-id ` 進行驗證。如果該命令不起作用，則請檢查 Systems Manager 是否在控制平面執行個體上執行。 + 由於 EBS 磁碟區的 KMS 金鑰許可，無法建立新的控制平面執行個體。使用加密 EBS 磁碟區的使用者受管 KMS 金鑰時，如果無法存取金鑰，控制平面執行個體將會終止。如果執行個體終止，請切換到 AWS 受管 KMS 金鑰，或確保您的使用者受管金鑰政策授予叢集角色必要的許可。 + Systems Manager 控制平面執行個體可能已失去網際網路存取。檢查您在建立叢集時提供的子網路是否具有 NAT 閘道和具有網際網路閘道的 VPC。使用 VPC Reachability Analyzer 確認控制平面執行個體是否可連線至網際網路閘道。如需詳細資訊，請參閱 [Getting started with VPC Reachability Analyzer](https://docs.aws.amazon.com/vpc/latest/reachability/getting-started.html) (VPC Reachability Analyzer 入門)。如果您的私有網路沒有傳出網際網路連線，請確保叢集的區域子網路中仍存在所有必要的 VPC 端點和閘道端點 (請參閱 [AWS 服務的子網路存取權](eks-outposts-vpc-subnet-requirements.md#subnet-access-to-services))。 + 您提供的角色 ARN 缺少政策。檢查 [AWS 受管政策：AmazonEKSLocalOutpostClusterPolicy](security-iam-awsmanpol.md#security-iam-awsmanpol-amazonekslocaloutpostclusterpolicy) 是否未從角色中移除。 + 其中一個新的 Kubernetes 控制平面執行個體可能會遇到未預期的引導失敗。如需有關此例外情況的故障診斷和日誌收集的進一步指引，請向 [AWS Support Center](https://console.aws.amazon.com/support/home) 填寫票證。 ## 無法將節點加入叢集 + AMI 問題： + 您正在使用不相容的 AMI。僅支援 Amazon EKS 最佳化 Amazon Linux 2 AMIs (`amazon-linux-2`、`amazon-linux-2-gpu`、`amazon-linux-2-arm64`)。如果您嘗試將 AL2023 節點加入 AWS Outposts 上的 EKS LocalClusters，節點將無法加入叢集。如需詳細資訊，請參閱在 [AWS Outposts 上建立 Amazon Linux 節點](eks-outposts-self-managed-nodes.md)。 + 如果您使用 an AWS CloudFormation 範本來建立節點，請確定它不是使用不支援的 AMI。 + 遺失 AWS IAM Authenticator `ConfigMap` – 如果遺失，您必須建立它。如需詳細資訊，請參閱 [將 `aws-auth` `ConfigMap` 套用至您的叢集](auth-configmap.md#aws-auth-configmap)。 + 使用錯誤的安全群組 – 確保將 `eks-cluster-sg-cluster-name-uniqueid ` 用於您工作節點的安全群組。 AWS CloudFormation 會變更選取的安全群組，以允許每次使用堆疊時有新的安全群組。 + 依照未預期的私人連結 VPC 步驟：傳遞了錯誤的 CA 資料 (`--b64-cluster-ca`) 或 API 端點 (`--apiserver-endpoint`)。 ## 收集日誌 當 Outpost 與其相關聯的 AWS 區域中斷連線時，Kubernetes 叢集可能會繼續正常運作。不過，如果叢集無法正常運作，請遵循在 [AWS Outposts 上準備本機 Amazon EKS 叢集以進行網路中斷連線](eks-outposts-network-disconnects.md)中的疑難排解步驟。如果您遇到其他問題，請聯絡 AWS Support。 AWS Support 可以引導您下載和執行日誌收集工具。如此一來，您就可以從 Kubernetes 叢集控制平面執行個體收集日誌，並將其傳送至 AWS Support 進行進一步調查。 ## 無法透過 AWS Systems Manager 存取控制平面執行個體 當 Amazon EKS 控制平面執行個體無法透過 AWS Systems Manager (Systems Manager) 連線時，Amazon EKS 會顯示叢集的下列錯誤。 ``` Amazon EKS control plane instances are not reachable through SSM. Please verify your SSM and network configuration, and reference the EKS on Outposts troubleshooting documentation. ``` 若要解決此問題，請確定您的 VPC 和子網路符合在 [AWS Outposts 上為 Amazon EKS 叢集建立 VPC 和子網路](eks-outposts-vpc-subnet-requirements.md)的要求，而且您已完成 AWS Systems Manager 使用者指南中[設定 Session](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started.html) Manager 的步驟。