Outposts 上的本機 Amazon EKS AWS 叢集疑難排解

本主題涵蓋一些使用本機叢集時可能遇到的常見錯誤與排除這些錯誤的方法。本機叢集類似於雲端中的 Amazon EKS 叢集，但 Amazon EKS 管理它們的方式有一些差異。

重要

除非 AWS Support 明確指示，否則請勿終止在 Outpost 上執行的任何受管 EKS 本機叢集Kubernetes控制平面執行個體。終止這些執行個體會對本機叢集服務可用性造成風險，包括遺失本機叢集，以防同時終止多個執行個體。EC2 執行個體主控台eks-local:controlplane-name上的標籤可識別 EKS 本機叢集Kubernetes控制平面執行個體。

本機叢集透過 Amazon EKS API 建立，但會以非同步方式執行。這表示本機叢集對 Amazon EKS API 的請求會立即傳回。但是，這些請求可能會成功、因輸入驗證錯誤而快速檢錯，或失敗並附上描述性驗證錯誤。此行為類似於 Kubernetes API。

本機叢集不會轉換為 FAILED 狀態。Amazon EKS 會嘗試以連續的方式使叢集狀態與使用者請求的所需狀態一致。因此，本機叢集可能會長期保持在 CREATING 狀態，直到基礎問題解決為止。

您可以使用 describe-cluster 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 存取控制平面執行個體。	`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 錯誤代碼	叢集運作狀態問題代碼	描述
`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 受管政策。所有其他 API 呼叫需要與雲端中 Amazon EKS 叢集相同的許可集。

建立本機叢集所需的時間量因數個因素而異。這些因素包括您的網路組態、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 (VPC Reachability Analyzer 入門)。
您提供的角色 ARN 缺少政策。檢查 AWS 受管政策：AmazonEKSLocalOutpostClusterPolicy 是否已從角色中移除。如果 An AWS CloudFormation 堆疊設定錯誤，也可能發生這種情況。
所有提供的子網路必須與相同的 Outpost 關聯，並且必須互相連線。如果在建立叢集時指定多個子網路，Amazon EKS 會嘗試將控制平面執行個體散佈到多個子網路。
Amazon EKS 受管的安全群組將套用至彈性網路介面。但是，其他組態元素 (例如 NACL 防火牆規則) 可能會與彈性網路介面的規則衝突。

VPC 和子網路 DNS 組態設定錯誤或遺失

檢閱在 AWS Outpost 上為 Amazon EKS 叢集建立 VPC 和子網路。

Amazon EKS 會自動將所有現有的本機叢集更新為其對應 Kubernetes 次要版本的最新平台版本。如需平台版本的詳細資訊，請參閱了解 AWS Outposts 的 Kubernetes 和 Amazon EKS 平台版本。

在自動平台版本推展期間，叢集狀態會變更為 UPDATING。更新程序包含將所有 Kubernetes 控制平面執行個體取代為新的執行個體，其中包含針對個別 Kubernetes 次要版本發行的最新安全路徑和錯誤修正。一般而言，本機叢集平台更新程序會在 30 分鐘內完成，且叢集會變更回 ACTIVE 狀態。如果本機叢集長時間保持 UPDATING 狀態，您可以呼叫 describe-cluster 在cluster.health輸出欄位中檢查原因的相關資訊。

Amazon EKS 可確保 3 個 Kubernetes 控制平面執行個體中至少有 2 個運作狀態良好且運作中的叢集節點，以維持本機叢集可用性並防止服務中斷。如果本機叢集停滯在 UPDATING 狀態，通常是因為有一些基礎設施或組態問題，導致在程序繼續的情況下，無法保證兩個執行個體的最低可用性。因此，更新程序會停止進行以保護本機叢集服務中斷。

請務必對卡在 UPDATING 狀態的本機叢集進行疑難排解，並解決根本原因，以便更新程序可以使用 3 個 ACTIVE 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 (VPC Reachability Analyzer 入門)。如果您的私有網路沒有傳出網際網路連線，請確保叢集的區域子網路中仍存在所有必要的 VPC 端點和閘道端點（請參閱 AWS 服務的子網路存取)。
您提供的角色 ARN 缺少政策。檢查 AWS 受管政策：AmazonEKSLocalOutpostClusterPolicy 是否未從角色中移除。
其中一個新的 Kubernetes 控制平面執行個體可能遇到非預期的引導失敗。請在此特殊情況下向AWS 支援中心提交票證，以取得疑難排解和收集日誌的進一步指引。

AMI 問題：
- 您正在使用不支援的 AMI。您必須針對具有最佳化 Amazon Linux AMIs Amazon EKS 最佳化 Amazon Linux 的建立節點使用 v20220620 或更新版本。
- 如果您使用 an AWS CloudFormation 範本來建立節點，請確定它不是使用不支援的 AMI。
遺失 AWS IAM Authenticator ConfigMap – 如果遺失，您必須建立它。如需詳細資訊，請參閱將 aws-authConfigMap 套用至您的叢集。
使用錯誤的安全群組 – 確保將 eks-cluster-sg-cluster-name-uniqueid 用於您工作節點的安全群組。 AWS CloudFormation 會變更選取的安全群組，以允許每次使用堆疊時有新的安全群組。
依照未預期的私人連結 VPC 步驟：傳遞了錯誤的 CA 資料 (--b64-cluster-ca) 或 API 端點 (--apiserver-endpoint)。

當 Outpost 與其相關聯的 AWS 區域中斷連線時，Kubernetes 叢集可能會繼續正常運作。不過，如果叢集無法正常運作，請遵循在 AWS Outposts 上準備本機 Amazon EKS 叢集以進行網路中斷連線中的疑難排解步驟。如果您遇到其他問題，請聯絡 AWS Support。 AWS Support 可以引導您下載和執行日誌收集工具。如此一來，您可以從 Kubernetes 叢集控制平面執行個體收集日誌，並將其傳送至 AWS Support 以進行進一步調查。

當 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 和子網路的要求，而且您已完成 AWS Systems Manager 使用者指南中設定 Session Manager 的步驟。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

容量考量事項

節點