本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 快速入門：Amazon EKS 上的 OTel Container Insights 本指南會逐步引導您在現有的 Amazon EKS 叢集上啟用 OTel Container Insights。在此程序結束時，您的叢集會將基礎設施指標和容器日誌傳送至 Amazon CloudWatch，並啟用增強型可觀測性。您可以透過兩種方式啟用 OTel Container Insights：使用 AWS 管理主控台（最快）或使用 AWS CLI。這兩種方法都會使用 `amazon-cloudwatch-observability` OTel Container Insights 組態安裝相同的 EKS 附加元件。您不需要手動代理程式部署、Helm Chart 或自訂收集器管道。整個程序需要不到 5 分鐘的時間。 ## 先決條件啟用 OTel Container Insights 之前，請確認您符合下列要求。 + 執行 Kubernetes 1.28 版或更新版本的現有 Amazon EKS 叢集 + 平台版本 `eks.1` 或更新版本 + 6.2.0 版或更新版本的`amazon-cloudwatch-observability`附加元件 + AWS CLI 2.15.0 版或更新版本（適用於 CLI 型設定） + `kubectl` 設定為與您的目標叢集通訊 + IAM 許可：`eks:DescribeAddon`、 `eks:CreateAddon`和 `iam:CreateServiceLinkedRole` + 叢集上安裝的 EKS Pod Identity Agent 附加元件，或已設定的 IAM Roles for Service Accounts (IRSA) + 從叢集到 CloudWatch 端點的傳出網際網路存取 ## 啟用 OTel Container Insights （主控台） AWS 管理主控台提供最快的路徑來啟用 OTel Container Insights。 **使用主控台啟用 OTel Container Insights** 1. 在 [https://console.aws.amazon.com/eks/](https://console.aws.amazon.com/eks/)：// 開啟 Amazon EKS 主控台。 1. 選擇**叢集**，然後選擇您的叢集名稱。 1. 選擇**可觀測性**索引標籤。 1. 選擇**啟用容器洞見**，然後依照畫面上的指示操作。如需詳細的主控台逐步解說，請參閱 [從主控台啟用 OTel Container Insights](container-insights-eks-otel-console.md)。 ## 啟用 OTel Container Insights (AWS CLI) 使用下列步驟，透過啟用 OTel Container Insights AWS CLI。 ### 步驟 1：建立 IAM 角色建立允許 CloudWatch Observability 附加元件將資料傳送至 CloudWatch 的 IAM 角色。 **建立 CloudWatch 可觀測性附加元件 IAM 角色** 1. 執行下列命令來建立具有 EKS Pod Identity 信任政策的角色。 ``` aws iam create-role \ --role-name EKS-CloudWatch-Observability-Role \ --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": { "Service": "pods.eks.amazonaws.com" }, "Action": ["sts:AssumeRole", "sts:TagSession"] }] }' ``` 1. 將 `CloudWatchAgentServerPolicy` 受管政策連接至角色。 ``` aws iam attach-role-policy \ --role-name EKS-CloudWatch-Observability-Role \ --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy ``` ### 步驟 2：建立 Pod Identity 關聯將 IAM 角色與叢集中的 CloudWatch 代理程式服務帳戶建立關聯。 **建立 Pod Identity 關聯** + 執行下列命令。將 {{cluster-name}} 取代為 Amazon EKS 叢集的名稱，並將 {{account-id}} 取代為您的帳戶 AWS ID。 ``` aws eks create-pod-identity-association \ --cluster-name {{cluster-name}} \ --namespace amazon-cloudwatch \ --service-account cloudwatch-agent \ --role-arn arn:aws:iam::{{account-id}}:role/EKS-CloudWatch-Observability-Role ``` ### 步驟 3：安裝 Amazon CloudWatch Observability 附加元件在啟用 OTel Container Insights 的情況下安裝`amazon-cloudwatch-observability`附加元件。 **安裝附加元件** + 執行下列命令。使用 Amazon EKS 叢集的名稱取代 {{cluster-name}}。 ``` aws eks create-addon \ --cluster-name {{cluster-name}} \ --addon-name amazon-cloudwatch-observability \ --configuration-values '{"otelContainerInsights":{"enabled":true}}' ``` **重要** `otelContainerInsights.enabled` 組態是必要的。預設不會啟用 OTel Container Insights。 ### 步驟 4：驗證附加元件狀態確認附加元件已成功安裝。 **驗證附加元件狀態** + 執行下列命令。使用 Amazon EKS 叢集的名稱取代 {{cluster-name}}。 ``` aws eks describe-addon \ --cluster-name {{cluster-name}} \ --addon-name amazon-cloudwatch-observability \ --query "addon.status" \ --output text ``` 預期的輸出為 `ACTIVE`。 ### 步驟 5：確認代理程式 Pod 正在執行確認 CloudWatch 代理程式 Pod 在 `amazon-cloudwatch` 命名空間中執行。 **確認代理程式 Pod 正在執行** + 執行下列命令。 ``` kubectl get pods -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent ``` 所有代理程式 Pod 必須顯示`Running`狀態。 ## 驗證 CloudWatch 中的資料完成設定後，Container Insights 資料會在 3 到 5 分鐘內顯示在 CloudWatch 中。 ### 檢查指標 **在 CloudWatch 中檢查指標** 1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。 1. 在導覽窗格中，選擇**查詢 Studio**。 1. `container_cpu_usage_seconds_total` 使用 PromQL 搜尋等指標。 ### 檢查日誌若要驗證叢集是否存在日誌群組，請執行下列命令。使用 Amazon EKS 叢集的名稱取代 {{cluster-name}}。 ``` aws logs describe-log-groups \ --log-group-name-prefix "/aws/containerinsights/{{cluster-name}}" \ --query "logGroups[].logGroupName" \ --output table ``` ### 預期的time-to-data 下表顯示啟用 OTel Container Insights 後，每個訊號類型的預期延遲。 | Signal | 預期的延遲 | | --- | --- | | 基礎設施指標 | 2-3 分鐘 | | 容器日誌 | 2-3 分鐘 | | 效能日誌事件 | 3-5 分鐘 | ## 疑難排解當您在 Amazon EKS 上啟用 OTel Container Insights 時，請使用下列指引來解決常見問題。 ### 附加元件狀態顯示 CREATE\_FAILED 或 DEGRADED **徵狀：**執行時`aws eks describe-addon`，狀態會顯示 `CREATE_FAILED`或 `DEGRADED`。 **原因：**附加元件安裝失敗，通常是因為 IAM 許可不足或缺少 Pod Identity 關聯。 **解決方案：**完成下列步驟以解決此問題。 1. 執行下列命令來檢查詳細錯誤資訊。以您的叢集名稱取代 {{cluster-name}}。 ``` aws eks describe-addon \ --cluster-name {{cluster-name}} \ --addon-name amazon-cloudwatch-observability \ --query "addon.health" ``` 1. 確認 IAM 角色存在且已`CloudWatchAgentServerPolicy`連接。 1. 確認 Pod Identity 關聯以正確的命名空間 (`amazon-cloudwatch`) 和服務帳戶 () 為目標`cloudwatch-agent`。 1. 刪除失敗的附加元件，並在解決問題後重新安裝它。 ``` aws eks delete-addon \ --cluster-name {{cluster-name}} \ --addon-name amazon-cloudwatch-observability ``` ### 代理程式 Pod 處於 CrashLoopBackOff 或待定狀態 **徵狀：**執行時`kubectl get pods -n amazon-cloudwatch`，一或多個 Pod 會顯示 `CrashLoopBackOff`或 `Pending` 狀態。 **原因：**代理程式 Pod 無法啟動，因為節點資源不足、缺少許可或網路連線問題。 **解決方案：**完成下列步驟以解決此問題。 1. 檢查 Pod 事件以取得詳細的錯誤訊息。 ``` kubectl describe pod -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent ``` 1. 檢查代理程式容器日誌是否有啟動錯誤。 ``` kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --tail=50 ``` 1. 確認您的節點有足夠的 CPU 和記憶體可供代理程式 Pod 使用。 1. 確認已安裝並執行 EKS Pod Identity Agent 附加元件。 ``` kubectl get pods -n kube-system -l app.kubernetes.io/name=eks-pod-identity-agent ``` ### 指標在 5 分鐘後未出現在 CloudWatch 中 **徵狀：**代理程式 Pod 會顯示`Running`狀態，但 5 分鐘後 CloudWatch 中不會顯示指標。 **原因：**代理程式無法將資料傳送至 CloudWatch，通常是因為網路限制或不正確的 IAM 許可。 **解決方案：**完成下列步驟以解決此問題。 1. 確認代理程式 Pod 可以連線到 CloudWatch 端點。檢查您的 VPC 安全群組和網路 ACLs是否允許傳出 HTTPS 流量（連接埠 443) 到 CloudWatch 端點。 1. 檢查代理程式日誌是否有許可錯誤或連線逾時。 ``` kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --tail=100 | grep -i "error\|timeout\|denied" ``` 1. 確認 IAM 角色已連接`CloudWatchAgentServerPolicy`政策，且信任政策允許 `pods.eks.amazonaws.com`。 1. 如果您將 VPC 端點用於 CloudWatch，請確認端點政策允許必要的動作。