**協助改進此頁面**
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
若要為本使用者指南貢獻內容，請點選每個頁面右側面板中的**在 GitHub 上編輯此頁面**連結。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 排解 Amazon EKS 連接器問題
本主題涵蓋您在使用 Amazon EKS 連接器時可能遇到的一些常見錯誤，包括有關如何解決錯誤和因應措施的說明。
## 基本疑難排解
本節介紹了診斷 Amazon EKS 連接器問題的步驟。
### 檢查 Amazon EKS 連接器狀態
如需檢查 Amazon EKS 連接器狀態，請輸入：
```
kubectl get pods -n eks-connector
```
### 檢查 Amazon EKS 連接器日誌
Amazon EKS 連接器 Pod 由三個容器組成。若要擷取所有這些容器的完整日誌，以便您可以檢查它們，請執行以下命令：
+ `connector-init`
```
kubectl logs eks-connector-0 --container connector-init -n eks-connector
kubectl logs eks-connector-1 --container connector-init -n eks-connector
```
+ `connector-proxy`
```
kubectl logs eks-connector-0 --container connector-proxy -n eks-connector
kubectl logs eks-connector-1 --container connector-proxy -n eks-connector
```
+ `connector-agent`
```
kubectl exec eks-connector-0 --container connector-agent -n eks-connector -- cat /var/log/amazon/ssm/amazon-ssm-agent.log
kubectl exec eks-connector-1 --container connector-agent -n eks-connector -- cat /var/log/amazon/ssm/amazon-ssm-agent.log
```
### 取得有效的叢集名稱
在`clusterName`單一 AWS 帳戶和 AWS 區域中，Amazon EKS 叢集由 唯一識別。如果您在 Amazon EKS 中有多個連接的叢集，您可以確認目前 Kubernetes 叢集註冊了哪個 Amazon EKS 叢集。為此，請輸入下列內容來找出目前叢集的 `clusterName`。
```
kubectl exec eks-connector-0 --container connector-agent -n eks-connector \
-- cat /var/log/amazon/ssm/amazon-ssm-agent.log | grep -m1 -oE "eks_c:[a-zA-Z0-9_-]+" | sed -E "s/^.*eks_c:([a-zA-Z0-9_-]+)_[a-zA-Z0-9]+.*$/\1/"
kubectl exec eks-connector-1 --container connector-agent -n eks-connector \
-- cat /var/log/amazon/ssm/amazon-ssm-agent.log | grep -m1 -oE "eks_c:[a-zA-Z0-9_-]+" | sed -E "s/^.*eks_c:([a-zA-Z0-9_-]+)_[a-zA-Z0-9]+.*$/\1/"
```
### 其他命令
擷取所需資訊以進行問題疑難排解時，以下命令很有用。
+ 使用以下命令收集 Amazon EKS 連接器中 Pod 使用的映像。
```
kubectl get pods -n eks-connector -o jsonpath="{.items[*].spec.containers[*].image}" | tr -s '[[:space:]]' '\n'
```
+ 使用以下命令判斷正在執行 Amazon EKS 連接器的節點名稱。
```
kubectl get pods -n eks-connector -o jsonpath="{.items[*].spec.nodeName}" | tr -s '[[:space:]]' '\n'
```
+ 執行以下命令，以取得 Kubernetes 用戶端和伺服器版本。
```
kubectl version
```
+ 執行以下命令，以取得有關節點的資訊。
```
kubectl get nodes -o wide --show-labels
```
## Helm 問題：403 禁止
如果您在執行 helm 安裝命令時收到下列錯誤：
```
Error: INSTALLATION FAILED: unexpected status from HEAD request to https://public.ecr.aws/v2/eks-connector/eks-connector-chart/manifests/0.0.6: 403 Forbidden
```
您可以執行下列行來修復錯誤：
```
docker logout public.ecr.aws
```
## 主控台錯誤：叢集停留在待定狀態
如果叢集在您註冊之後卡在 Amazon EKS 主控台`Pending`的狀態，可能是因為 Amazon EKS 連接器尚未成功將叢集連線至 AWS 。對於已註冊的叢集，`Pending` 狀態表示連接尚未成功建立。若要解決此問題，請確定您已將清單檔案應用於目標 Kubernetes 叢集。如果您將其套用於叢集，但叢集仍處於 `Pending` 狀態，則 `eks-connector` statefulset 很可能無法正常運作。若要排除此問題，請參閱本主題中的 [Amazon EKS 連接器 Pod 正處於損毀循環](#symp-loop)。
## 主控台錯誤：使用者 system:serviceaccount:eks-connector:eks-connector 無法在叢集範圍內模擬 API 群組內的資源使用者
Amazon EKS 連接器使用 Kubernetes [使用者模擬](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation)，以代表來自 AWS 管理主控台的 [IAM 主體](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html#iam-term-principal)採取動作。從`eks-connector`服務帳戶存取 Kubernetes API AWS 的每個委託人都必須獲得許可，才能以 IAM ARN 做為其 Kubernetes 使用者名稱來模擬對應的 Kubernetes 使用者。在以下範例中，IAM ARN 映射到 Kubernetes 使用者。
+ 從 AWS 帳戶 {{111122223333}} {{加入}}的 IAM 使用者會映射到 Kubernetes 使用者。[IAM 最佳實務](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)建議您將許可授予角色而非使用者。
```
arn:aws: iam::111122223333:user/john
```
+ AWS 帳戶 {{111122223333}} 的 IAM 角色{{管理員}}會映射至 Kubernetes 使用者：
```
arn:aws: iam::111122223333:role/admin
```
結果是 IAM 角色 ARN，而不是 AWS STS 工作階段 ARN。
如需如何設定 `ClusterRole` 和 `ClusterRoleBinding` 以授予 `eks-connector` 服務帳戶權限來模擬映射使用者的說明，請參閱 [授予在 Amazon EKS 主控台上檢視 Kubernetes 叢集資源的存取權](connector-grant-access.md)。請確定在 範本中， `%IAM_ARN%` 已取代為 IAM 主體的 AWS 管理主控台 IAM ARN。
## 主控台錯誤：[…]被禁止：使用者 […] 無法在叢集範圍中列出「在 API 群組中的 […]」的資源
請考量下列問題。Amazon EKS 連接器已成功模擬目標 Kubernetes AWS 管理主控台 叢集中的請求 IAM 主體。但是，模擬主體沒有針對 Kubernetes API 操作的 RBAC 許可。
若要解決此問題，有兩種方法可將許可授予其他使用者。如果您先前透過 Helm Chart 安裝了 eks-connector，您可以透過執行下列命令輕鬆授予使用者存取權。以 IAM 角色的 ARN 清單取代 `userARN1` 和 `userARN2` 以提供存取權來檢視 Kubernetes 資源：
```
helm upgrade eks-connector oci://public.ecr.aws/eks-connector/eks-connector-chart \
--reuse-values \
--set 'authentication.allowedUserARNs={userARN1,userARN2}'
```
或者，身為叢集管理員，向個別 Kubernetes 使用者授予適當層級的 RBAC 權限。如需詳細資訊和範例，請參閱 [授予在 Amazon EKS 主控台上檢視 Kubernetes 叢集資源的存取權](connector-grant-access.md)。
## 主控台錯誤：Amazon EKS 無法與您的 Kubernetes 叢集 API 伺服器通訊。叢集必須處於作用中狀態，才能成功連接。請過幾分鐘後再試。
如果 Amazon EKS 服務無法與目標叢集中的 Amazon EKS 連接器通訊，則可能是由於以下原因之一：
+ 目標叢集中的 Amazon EKS 連接器無法正常運作。
+ 目標叢集與 AWS 區域之間的連線能力不佳或連線中斷。
若要解決此問題，請查看 [Amazon EKS 連接器日誌](#tsc-logs)。如果未看到 Amazon EKS 連接器的錯誤，請在幾分鐘後重試連線。如果您經常遇到目標叢集的高延遲或間歇性連線，請考慮將叢集重新註冊到離您較近 AWS 的區域。
## Amazon EKS 連接器 Pod 正處於損毀循環
導致 Amazon EKS 連接器 Pod 進入 `CrashLoopBackOff` 狀態的原因有很多。此問題可能涉及 `connector-init` 容器。檢查 Amazon EKS 連接器 Pod 的狀態。
```
kubectl get pods -n eks-connector
```
範例輸出如下。
```
NAME READY STATUS RESTARTS AGE
eks-connector-0 0/2 Init:CrashLoopBackOff 1 7s
```
如果您的輸出與之前的輸出相似，請參閱 [檢查 Amazon EKS 連接器日誌](#tsc-logs) 以排除問題。
## 無法初始化 eks-connector：InvalidActivation
當您第一次啟動 Amazon EKS 連接器時，它會使用 Amazon Web Services 註冊 `activationId` 和 `activationCode`。註冊可能會失敗，這可能會導致 `connector-init` 容器損毀，產生與以下錯誤相似的錯誤。
```
F1116 20:30:47.261469 1 init.go:43] failed to initiate eks-connector: InvalidActivation:
```
若要對此問題進行疑難排解，請考慮以下原因和建議的修正：
+ 註冊可能會失敗，因為 `activationId` 和 `activationCode` 不在清單檔案檔案中。如果是這種情況，請確保它們是從 `RegisterCluster` API 操作傳回的正確值，並且 `activationCode` 位於清單檔案檔案中。`activationCode` 新增至 Kubernetes 機密中，因此它必須採用 `base64` 編碼。如需詳細資訊，請參閱[步驟 1：註冊叢集](connecting-cluster.md#connector-connecting)。
+ 註冊可能因啟用過期而失敗。因為出於安全原因，您必須在註冊叢集後的 3 天內啟用 Amazon EKS 連接器。若要解決此問題，請確保在過期日期和時間之前將 Amazon EKS 連接器清單檔案應用於目標 Kubernetes 叢集。若要確認您的啟用過期日期，請呼叫 `DescribeCluster` API 操作。
```
aws eks describe-cluster --name my-cluster
```
在以下範例回應中，過期日期和時間記錄為 `2021-11-12T22:28:51.101000-08:00`。
```
{
"cluster": {
"name": "my-cluster",
"arn": "arn:aws: eks:region:111122223333:cluster/my-cluster",
"createdAt": "2021-11-09T22:28:51.449000-08:00",
"status": "FAILED",
"tags": {
},
"connectorConfig": {
"activationId": "00000000-0000-0000-0000-000000000000",
"activationExpiry": "2021-11-12T22:28:51.101000-08:00",
"provider": "OTHER",
"roleArn": "arn:aws: iam::111122223333:role/my-connector-role"
}
}
}
```
如果超過 `activationExpiry`，請取消註冊叢集，並將其重新註冊。這樣做會產生一個新的啟用。
## 叢集節點遺漏對外連線
若要正常運作，Amazon EKS 連接器需要與多個 AWS 端點的傳出連線。您無法在沒有傳出連線至目標 AWS 區域的私有叢集。若要解決此問題，您必須新增必要的對外連線。如需連接器要求的相關資訊，請參閱 [Amazon EKS 連接器考量事項](eks-connector.md#connect-cluster-reqts)。
## Amazon EKS 連接器 Pod 處於 `ImagePullBackOff` 狀態
如果您執行 `get pods` 命令，並且 Pod 處於 `ImagePullBackOff` 狀態，則它們無法正常運作。如果 Amazon EKS 連接器 Pod 處於 `ImagePullBackOff` 狀態，則它們無法正常運作。檢查 Amazon EKS 連接器 Pod 的狀態。
```
kubectl get pods -n eks-connector
```
範例輸出如下。
```
NAME READY STATUS RESTARTS AGE
eks-connector-0 0/2 Init:ImagePullBackOff 0 4s
```
預設的 Amazon EKS 連接器清單檔案檔案引用來自 [Amazon ECR Public Gallery](https://gallery.ecr.aws/) 的映像。目標 Kubernetes 叢集可能無法從 Amazon ECR Public Gallery 提取映像。解決 Amazon ECR Public Gallery 映像提取問題，或者考慮選擇在私有容器登錄檔中鏡像映像。