本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 在 Kubernetes 上啟用您的應用程式 依本節所述的自訂設定步驟，在 Kubernetes 上啟用 CloudWatch Application Signals。 對於在 Kubernetes 上執行的應用程式，您可以自行安裝和設定 CloudWatch 代理程式和 AWS Distro for OpenTelemetry。在使用自訂 Application Signals 設定啟用的這些架構上，Application Signals 不會自動探索您的服務或其執行所在的叢集或主機的名稱。您必須在自訂設定期間指定這些名稱，而您指定的名稱是顯示在 Application Signals 儀表板中的名稱。 **需求** + 在啟用 Application Signals 的 Kubernetes 叢集上擁有管理員許可。 + 您必須在執行 Kubernetes 叢集的環境中 AWS CLI 安裝 。如需安裝 的詳細資訊 AWS CLI，請參閱[安裝或更新最新版本的 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。 + 已在本機終端上安裝 kubectl 和 helm。如需詳細資訊，請參閱 [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) 和 [Helm](https://helm.sh/) 文件。 ## 步驟 1：在您的帳戶中啟用 Application Signals 必須先在帳戶中啟用 Application Signals。如果尚未這麼做，請參閱 [在您的帳戶中啟用 Application Signals](CloudWatch-Application-Signals-Enable.md)。 ## 步驟 2：在叢集中安裝 CloudWatch 代理程式運算子 安裝 CloudWatch 代理程式運算子時，系統會將運算子、CloudWatch 代理程式和其他自動檢測功能安裝到您的叢集。若要執行此作業，請輸入以下命令。將 *\$1REGION* 取代為您的 AWS 區域。將 *\$1YOUR\$1CLUSTER\$1NAME* 替換為您希望叢集在 Application Signals 中顯示的名稱。 ``` helm repo add aws-observability https://aws-observability.github.io/helm-charts helm install amazon-cloudwatch-operator aws-observability/amazon-cloudwatch-observability \ --namespace amazon-cloudwatch --create-namespace \ --set region=$REGION \ --set clusterName=$YOUR_CLUSTER_NAME ``` 如需詳細資訊，請參閱 GitHub 上的 [amazon-cloudwatch-observability](https://github.com/aws-observability/helm-charts/tree/main/charts/amazon-cloudwatch-observability)。 ## 步驟 3：設定 Kubernetes 叢集的 AWS 登入資料 **重要** 如果您的 Kubernetes 叢集託管在 Amazon EC2 上，可以略過本節並繼續[步驟 4：新增註釋](#Application-Signals-Enable-Kubernetes-annotations)。 如果您的 Kubernetes 叢集是內部部署託管，您必須使用本節中的指示，將 AWS 登入資料新增至您的 Kubernetes 環境。 **設定內部部署 Kubernetes 叢集的許可** 1. 建立 IAM 使用者，用於為您的內部部署主機提供許可： 1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。 1. 選擇**使用者**、**建立使用者**。 1. 在**使用者詳細資訊**的**使用者名稱**中，輸入新 IAM 使用者的名稱。這是 的登入名稱 AWS ，將用於驗證您的主機。然後選擇**下一步** 1. 在**設定許可**頁面，為**許可選項**選取**直接連結政策**。 1. 在**許可政策**清單中，選取要新增至使用者的 **CloudWatchAgentServerPolicy** 政策。然後選擇**下一步**。 1. 在**檢閱和建立**頁面上，確定您對使用者名稱感到滿意，並且 **CloudWatchAgentServerPolicy** 政策位於**許可摘要**中。 1. 選擇**建立使用者** 1. 建立和擷取您的 AWS 存取金鑰和私密金鑰： 1. 在 IAM 主控台的導覽窗格中，選取**使用者**，然後選取在先前步驟中建立的使用者名稱。 1. 在使用者頁面上，選擇**安全憑證**索引標籤。在**存取金鑰**區段中，選擇**建立存取金鑰**。 1. 針對**建立存取金鑰步驟 1**，請選擇**命令列界面 (CLI)**。 1. 在**建立存取金鑰步驟 2** 中，輸入選用標籤，然後選擇**下一步**。 1. 在**建立存取金鑰步驟 3** 中，選取**下載 .csv 檔案**，以儲存包含 IAM 使用者存取金鑰和私密存取金鑰的 .csv 檔案。您需要這些資訊才能進行後續步驟。 1. 選擇**完成**。 1. 輸入下列命令，在現場部署主機中設定您的 AWS 登入資料。將 *ACCESS\$1KEY\$1ID* 和 *SECRET\$1ACCESS\$1ID* 替換為您在上一個步驟中下載的 .csv 檔案中新產生的存取金鑰和私密存取金鑰。依預設，憑證檔案儲存在 `/home/user/.aws/credentials.` 中 ``` $ aws configure --profile AmazonCloudWatchAgent AWS Access Key ID [None]: ACCESS_KEY_ID AWS Secret Access Key [None]: SECRET_ACCESS_ID Default region name [None]: MY_REGION Default output format [None]: json ``` 1. 編輯 CloudWatch 代理程式使用 Helm Chart 安裝的自訂資源，以新增新建立的 AWS 登入資料秘密。 ``` kubectl edit amazoncloudwatchagent cloudwatch-agent -n amazon-cloudwatch ``` 1. 當檔案編輯器開啟時，將下列組態新增至部署頂端，將 AWS 登入資料掛載到 CloudWatch 代理程式容器中。將路徑取代`/home/user/.aws/credentials`為本機 AWS 登入資料檔案的位置。 ``` apiVersion: cloudwatch.aws.amazon.com/v1alpha1 kind: AmazonCloudWatchAgent metadata: name: cloudwatch-agent namespace: amazon-cloudwatch spec: volumeMounts: - mountPath: /rootfs volumeMounts: - name: aws-credentials mountPath: /root/.aws readOnly: true volumes: - hostPath: path: /home/user/.aws/credentials name: aws-credentials --- ``` ## 步驟 4：新增註釋 **注意** 如果使用 ESM 為 Node.js 應用程式啟用 Application Signals，請跳過本節中的步驟，並參閱 [設定採用 ESM 模組格式的 Node.js 應用程式](#Kubernetes-NodeJs-ESM)。 下一個步驟是將特定語言[註釋](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/)新增至 Kubernetes [工作負載](https://kubernetes.io/docs/concepts/workloads/)或[命名空間](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)，以檢測 CloudWatch Application Signals 應用程式。此注釋會自動檢測應用程式，以便將指標、追蹤和日誌傳送至 Application Signals。 **新增 Application Signals 的註釋** 1. 有兩個注釋選項： + **標註工作負載**會自動檢測叢集中的單一工作負載。 + **標註命名空間**會自動檢測所選命名空間中部署的所有工作負載。 選擇其中一個選項，然後遵循適當的步驟。 1. 若要註釋單一工作負載，輸入下列其中一個命令。將 *\$1WORKLOAD\$1TYPE* 和 *\$1WORKLOAD\$1NAME* 替換為工作負載的值。 + 對於 Java 工作負載： ``` kubectl patch $WORKLOAD_TYPE $WORKLOAD_NAME -p '{"spec": {"template": {"metadata": {"annotations": {"instrumentation.opentelemetry.io/inject-java": "true"}}}}}' ``` + 對於 Python 工作負載： ``` kubectl patch $WORKLOAD_TYPE $WORKLOAD_NAME -p '{"spec": {"template": {"metadata": {"annotations": {"instrumentation.opentelemetry.io/inject-python": "true"}}}}}' ``` 對於 Python 應用程式，還需進行額外的必要設定。如需詳細資訊，請參閱[啟用 Application Signals 後，Python 應用程式無法啟動](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-Python)。 + 對於 .NET 工作負載： ``` kubectl patch $WORKLOAD_TYPE $WORKLOAD_NAME -p '{"spec": {"template": {"metadata": {"annotations": {"instrumentation.opentelemetry.io/inject-dotnet": "true"}}}}}' ``` **注意** 若要為以 Alpine Linux (`linux-musl-x64`) 為基礎之映像上的 .NET 工作負載啟用 Application Signals，請新增下列額外註釋。 ``` instrumentation.opentelemetry.io/otel-dotnet-auto-runtime: "linux-musl-x64" ``` + 對於 Node.js 工作負載： ``` kubectl patch $WORKLOAD_TYPE $WORKLOAD_NAME -p '{"spec": {"template": {"metadata": {"annotations": {"instrumentation.opentelemetry.io/inject-nodejs": "true"}}}}}' ``` 1. 若要標註命名空間中的所有工作負載，輸入下列其中一個命令。將 *\$1NAMESPACE* 替換為命名空間的名稱。 如果命名空間包含 Java、Python 和 .NET 工作負載，將所有註釋新增至命名空間。 + 對於命名空間中的 Java 工作負載： ``` kubectl annotate ns $NAMESPACE instrumentation.opentelemetry.io/inject-java=true ``` + 對於命名空間中的 Python 工作負載： ``` kubectl annotate ns $NAMESPACE instrumentation.opentelemetry.io/inject-python=true ``` 對於 Python 應用程式，還需進行額外的必要設定。如需詳細資訊，請參閱[啟用 Application Signals 後，Python 應用程式無法啟動](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-starting-Python)。 + 對於命名空間中的 .NET 工作負載： ``` kubectl annotate ns $NAMESPACE instrumentation.opentelemetry.io/inject-dotnet=true ``` + 對於命名空間中的 Node.js 工作負載： ``` kubectl annotate ns $NAMESPACE instrumentation.opentelemetry.io/inject-nodejs=true ``` 新增註釋後，輸入以下命令以重新啟動命名空間中的所有 Pod： ``` kubectl rollout restart ``` 1. 完成上述步驟後，在 CloudWatch 主控台中選擇 **Application Signals**、**服務**。此時會開啟儀表板，其中將顯示 Application Signals 收集的資料。可能需要幾分鐘的時間才會顯示資料。 如需**服務**檢視的詳細資訊，請參閱 [使用 Application Signals 監控應用程式的運作狀態](Services.md)。 ### 設定採用 ESM 模組格式的 Node.js 應用程式 對於採用 ESM 模組格式的 Node.js 應用程式，我們提供有限支援。如需詳細資訊，請參閱[Node.js 搭配使用 ESM 的已知限制](CloudWatch-Application-Signals-supportmatrix.md#ESM-limitations)。 對於 ESM 模組格式，無法透過標註資訊清單檔案來啟用 Application Signals。略過先前的程序，改為執行下列動作： **為採用 ESM 的 Node.js 應用程式啟用 Application Signals** 1. 將相關的相依項安裝到 Node.js 應用程式以進行自動檢測： ``` npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation npm install @opentelemetry/instrumentation@0.54.0 ``` 1. 將下列環境變數新增至應用程式的 Dockerfile，然後建置映像。 ``` ... ENV OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true ENV OTEL_TRACES_SAMPLER_ARG='endpoint=http://cloudwatch-agent.amazon-cloudwatch:2000' ENV OTEL_TRACES_SAMPLER='xray' ENV OTEL_EXPORTER_OTLP_PROTOCOL='http/protobuf' ENV OTEL_EXPORTER_OTLP_TRACES_ENDPOINT='http://cloudwatch-agent.amazon-cloudwatch:4316/v1/traces' ENV OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT='http://cloudwatch-agent.amazon-cloudwatch:4316/v1/metrics' ENV OTEL_METRICS_EXPORTER='none' ENV OTEL_LOGS_EXPORTER='none' ENV NODE_OPTIONS='--import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs' ENV OTEL_SERVICE_NAME='YOUR_SERVICE_NAME' #replace with a proper service name ENV OTEL_PROPAGATORS='tracecontext,baggage,b3,xray' ... # command to start the application # for example # CMD ["node", "index.mjs"] ``` 1. 將環境變數 `OTEL_RESOURCE_ATTRIBUTES_POD_NAME`、`OTEL_RESOURCE_ATTRIBUTES_NODE_NAME`、`OTEL_RESOURCE_ATTRIBUTES_DEPLOYMENT_NAME`、`POD_NAMESPACE` 和 `OTEL_RESOURCE_ATTRIBUTES` 新增至應用程式的部署 yaml 檔案。例如： ``` apiVersion: apps/v1 kind: Deployment metadata: name: nodejs-app labels: app: nodejs-app spec: replicas: 2 selector: matchLabels: app: nodejs-app template: metadata: labels: app: nodejs-app # annotations: # make sure this annotation doesn't exit # instrumentation.opentelemetry.io/inject-nodejs: 'true' spec: containers: - name: nodejs-app image:your-nodejs-application-image #replace it with a proper image uri imagePullPolicy: Always ports: - containerPort: 8000 env: - name: OTEL_RESOURCE_ATTRIBUTES_POD_NAME valueFrom: fieldRef: fieldPath: metadata.name - name: OTEL_RESOURCE_ATTRIBUTES_NODE_NAME valueFrom: fieldRef: fieldPath: spec.nodeName - name: OTEL_RESOURCE_ATTRIBUTES_DEPLOYMENT_NAME valueFrom: fieldRef: fieldPath: metadata.labels['app'] # Assuming 'app' label is set to the deployment name - name: POD_NAMESPACE valueFrom: fieldRef: fieldPath: metadata.namespace - name: OTEL_RESOURCE_ATTRIBUTES value: "k8s.deployment.name=$(OTEL_RESOURCE_ATTRIBUTES_DEPLOYMENT_NAME),k8s.namespace.name=$(POD_NAMESPACE),k8s.node.name=$(OTEL_RESOURCE_ATTRIBUTES_NODE_NAME),k8s.pod.name=$(OTEL_RESOURCE_ATTRIBUTES_POD_NAME)" ``` 1. 將 Node.js 應用程式部署至 Kubernetes 叢集。 ## (選用) 步驟 5：監控應用程式運作狀態 在 Kubernetes 上啟用應用程式後，即可監控應用程式的運作狀態。如需詳細資訊，請參閱[使用 Application Signals 監控應用程式的運作狀態](Services.md)。