AWS AmazonCloudWatch documentation change
Summary
Restructured documentation to merge console and AWS CDK enablement methods, added detailed implementation steps for EKS cluster configuration, Node.js ESM support, and AWS CDK code examples
Security assessment
Added IAM role configuration details and policy attachments (CloudWatchAgentServerPolicy, AWSXRayWriteOnlyAccess) which are security-related configurations, but no evidence of addressing a specific vulnerability or security incident
Diff
diff --git a/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-EKS.md b/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-EKS.md index 54fa6962f..19feb1cd3 100644 --- a//AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-EKS.md +++ b//AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-EKS.md @@ -5 +5 @@ -# Enable Application Signals on Amazon EKS clusters +Enable Application Signals on an Amazon EKS cluster using the consoleEnable Application Signals on Amazon EKS using AWS CDK @@ -7 +7 @@ -CloudWatch Application Signals is supported for Java, Python, Node.js, and .NET applications. To enable Application Signals for applications in an Amazon EKS cluster, you have two options: +# Enable your applications on Amazon EKS clusters @@ -9 +9 @@ CloudWatch Application Signals is supported for Java, Python, Node.js, and .NET - * To enable Application Signals for your applications on an existing Amazon EKS cluster, use the steps in [Enable Application Signals on an Amazon EKS cluster with your services](./CloudWatch-Application-Signals-Enable-EKS-Console.html). +CloudWatch Application Signals is supported for Java, Python, Node.js, and .NET applications. To enable Application Signals for your applications on an existing Amazon EKS cluster, you can use the AWS Management Console or the AWS CDK. @@ -11 +11 @@ CloudWatch Application Signals is supported for Java, Python, Node.js, and .NET - * To try out Application Signals in a non-production environment with a sample application, use the instructions in [Enable Application Signals on a new Amazon EKS cluster with a sample app](./CloudWatch-Application-Signals-Enable-EKS-sample.html). This workflow uses scripts provided by AWS to create a new Amazon EKS cluster and install a sample application enabled for Application Signals. This lets you see and test the end-to-end functionality of Application Signals. +###### Topics @@ -12,0 +13 @@ CloudWatch Application Signals is supported for Java, Python, Node.js, and .NET + * Enable Application Signals on an Amazon EKS cluster using the console @@ -13,0 +15 @@ CloudWatch Application Signals is supported for Java, Python, Node.js, and .NET + * Enable Application Signals on Amazon EKS using AWS CDK @@ -16 +17,0 @@ CloudWatch Application Signals is supported for Java, Python, Node.js, and .NET -###### Topics @@ -18 +18,0 @@ CloudWatch Application Signals is supported for Java, Python, Node.js, and .NET - * [Enable Application Signals on an Amazon EKS cluster with your services](./CloudWatch-Application-Signals-Enable-EKS-Console.html) @@ -20 +20,323 @@ CloudWatch Application Signals is supported for Java, Python, Node.js, and .NET - * [Enable Application Signals on a new Amazon EKS cluster with a sample app](./CloudWatch-Application-Signals-Enable-EKS-sample.html) +## Enable Application Signals on an Amazon EKS cluster using the console + +To enable CloudWatch Application Signals on your applications on an existing Amazon EKS cluster, use the instructions in this section. + +###### Important + +If you are already using OpenTelemetry with an application that you intend to enable for Application Signals, see [OpenTelemetry compatibility](./CloudWatch-Application-Signals-supportmatrix.html#CloudWatch-Application-Signals-compatibility) before you enable Application Signals. + +###### To enable Application Signals for your applications on an existing Amazon EKS cluster + +###### Note + +If you haven't already enabled Application Signals, follow the instructions in [Enable Application Signals in your account](./CloudWatch-Application-Signals-Enable.html) and then follow the procedure below. + + 1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). + + 2. Choose **Application Signals**. + + 3. For **Specify platform** , choose **EKS**. + + 4. For **Select an EKS cluster** , select the cluster where you want to enable Application Signals. + + 5. If this cluster does not already have the Amazon CloudWatch Observability EKS add-on enabled, you are prompted to enable it. If this is the case, do the following: + + 1. Choose **Add CloudWatch Observability EKS add-on**. The Amazon EKS console appears. + + 2. Select the check box for **Amazon CloudWatch Observability** and choose **Next**. + +The CloudWatch Observability EKS add-on enables both Application Signals and CloudWatch Container Insights with enhanced observability for Amazon EKS. For more information about Container Insights, see [Container Insights](./ContainerInsights.html). + + 3. Select the most recent version of the add-on to install. + + 4. Select an IAM role to use for the add-on. If you choose **Inherit from node** , attach the correct permissions to the IAM role used by your worker nodes. Replace `my-worker-node-role` with the IAM role used by your Kubernetes worker nodes. + + aws iam attach-role-policy \ + --role-name my-worker-node-role \ + --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy \ + --policy-arn arn:aws:iam::aws:policy/AWSXRayWriteOnlyAccess + + 5. If you want to create a service role to use the add-on, see [Install the CloudWatch agent with the Amazon CloudWatch Observability EKS add-on or the Helm chart](./install-CloudWatch-Observability-EKS-addon.html). + + 6. Choose **Next** , confirm the information on the screen, and choose **Create**. + + 7. In the next screen, choose **Enable CloudWatch Application Signals** to return to the CloudWatch console and finish the process. + + 6. There are two options for enabling your applications for Application Signals. For consistency, we recommend that you choose one option per cluster. + + * The **Console** option is simpler. Using this method causes your pods to restart immediately. + + * The **Annotate Manifest File** method gives you more control of when your pods restart, and can also help you manage your monitoring in a more decentralized way if you don’t want to centralize it. + +###### Note + +If you are enabling Application Signals for a Node.js application with ESM, skip to Setting up a Node.js application with the ESM module format instead. + +Console + + +The **Console** option uses the advanced configuration of the Amazon CloudWatch Observability EKS add-on to setup Application Signals for your services. For more information about the add-on, see [(Optional) Additional configuration](./install-CloudWatch-Observability-EKS-addon.html#install-CloudWatch-Observability-EKS-addon-configuration). + +If you don’t see a list of workloads and namespaces, ensure you have the right permissions to view them for this cluster. For more information, see [ Required permissions](https://docs.aws.amazon.com/eks/latest/userguide/view-kubernetes-resources.html#view-kubernetes-resources-permissions). + +You can monitor single workloads or entire namespaces. + +To monitor a single workload: + + 1. Select the check box by the workload that you want to monitor. + + 2. Use the **Select language(s)** dropdown list to select the language of the workload. Select the languages that you want to enable Application Signals for, and then choose the check mark icon (✓) to save this selection. + +For Python applications, ensure your application follows the required prerequisites before continuing. For more information, see [Python application doesn't start after Application Signals is enabled](./CloudWatch-Application-Signals-Enable-Troubleshoot.html#Application-Signals-troubleshoot-starting-Python). + + 3. Choose **Done**. The Amazon CloudWatch Observability EKS add-on will immediately inject AWS Distro for OpenTelemetry autoinstrumentation (ADOT) SDKs into your pods and trigger pod restarts to enable collection of application metrics and traces. + +To monitor an entire namespace: + + 1. Select the check box by the namespace that you want to monitor. + + 2. Use the **Select language(s)** dropdown list to select the language of the namespace. Select the languages that you want to enable Application Signals for, and then choose the check mark icon (✓) to save this selection. This applies it to all workloads in this namespace, whether they are currently deployed or will be deployed in the future. + +For Python applications, ensure your application follows the required prerequisites before continuing. For more information, see [Python application doesn't start after Application Signals is enabled](./CloudWatch-Application-Signals-Enable-Troubleshoot.html#Application-Signals-troubleshoot-starting-Python). + + 3. Choose **Done**. The Amazon CloudWatch Observability EKS add-on will immediately inject AWS Distro for OpenTelemetry autoinstrumentation (ADOT) SDKs into your pods and trigger pod restarts to enable collection of application metrics and traces. + +To enable Application Signals in another Amazon EKS cluster, choose **Enable Application Signals** from the **Services** screen. + +Annotate manifest file + + +In the CloudWatch console, the **Monitor Services** section explains that you must add an annotation to a manifest YAML in the cluster. Adding this annotation auto-instruments the application to send metrics, traces, and logs to Application Signals. + +You have two options for the annotation: + + * **Annotate Workload** auto-instruments a single workload in the cluster. + + * **Annotate Namespace** auto-instruments all workloads deployed in the selected namespace. + +Choose one of those options, and follow the appropriate steps: + + * To annotate a single workload: + + 1. Choose **Annotate Workload**. + + 2. Paste one of the following lines into the `PodTemplate` section of the workload manifest file. + + * **For Java workloads:** `annotations: instrumentation.opentelemetry.io/inject-java: "true"` + + * **For Python workloads:** `annotations: instrumentation.opentelemetry.io/inject-python: "true"` + +For Python applications, there are additional required configurations. For more information, see [Python application doesn't start after Application Signals is enabled](./CloudWatch-Application-Signals-Enable-Troubleshoot.html#Application-Signals-troubleshoot-starting-Python). + + * **For .NET workloads** `annotations: instrumentation.opentelemetry.io/inject-dotnet: "true"` + +###### Note + +To enable Application Signals for a .NET workload on Alpine Linux (`linux-musl-x64`) based images, add the following annotation. + + instrumentation.opentelemetry.io/otel-dotnet-auto-runtime: "linux-musl-x64" + + * **For Node.js workloads:** `annotations: instrumentation.opentelemetry.io/inject-nodejs: "true"` + + 3. In your terminal, enter `kubectl apply -f `your_deployment_yaml`` to apply the change. + + * To annotate all workloads in a namespace: + + 1. Choose **Annotate Namespace**. + + 2. Paste one of the following lines into the metadata section of the namespace manifest file. If the namespace includes Java, Python, and .NET workloads, paste all of the following lines into the namespace manifest file. + + * **If there are Java workloads in the namespace:** `annotations: instrumentation.opentelemetry.io/inject-java: "true"` + + * **If there are Python workloads in the namespace:** `annotations: instrumentation.opentelemetry.io/inject-python: "true"` + +For Python applications, there are additional required configurations. For more information, see [Python application doesn't start after Application Signals is enabled](./CloudWatch-Application-Signals-Enable-Troubleshoot.html#Application-Signals-troubleshoot-starting-Python). + + * **If there are .NET workloads in the namespace:** `annotations: instrumentation.opentelemetry.io/inject-dotnet: "true"` + + * **If there are Node.JS workloads in the namespace:** `annotations: instrumentation.opentelemetry.io/inject-nodejs: "true"` + + 3. In your terminal, enter `kubectl apply -f `your_namespace_yaml`` to apply the change. + + 4. In your terminal, enter a command to restart all pods in the namespace. An example command to restart deployment workloads is `kubectl rollout restart deployment -n `namespace_name`` + + 7. Choose **View Services when done**. This takes you to the Application Signals Services view, where you can see the data that Application Signals is collecting. It might take a few minutes for data to appear. + +To enable Application Signals in another Amazon EKS cluster, choose **Enable Application Signals** from the **Services** screen. + +For more information about the **Services** view, see [Monitor the operational health of your applications with Application Signals](./Services.html). + + + + +###### Note + +If you're using a WSGI server for your Python application, see [No Application Signals data for Python application that uses a WSGI server](./CloudWatch-Application-Signals-Enable-Troubleshoot.html#Application-Signals-troubleshoot-Python-WSGI) for information to make Application Signals work. + +We've also identified other considerations that you should keep in mind when enabling Python applications for Application Signals. For more information, see [Python application doesn't start after Application Signals is enabled](./CloudWatch-Application-Signals-Enable-Troubleshoot.html#Application-Signals-troubleshoot-starting-Python). + +### Setting up a Node.js application with the ESM module format + +We provide limited support for Node.js applications with the ESM module format. For details, see [Known limitations about Node.js with ESM](./CloudWatch-Application-Signals-supportmatrix.html#ESM-limitations). + +For the ESM module format, enabling Application Signals through the console or by annotating the manifest file doesn’t work. Skip step 8 of the previous procedure, and do the following instead. + +###### To enable Application Signals for a Node.js application with ESM + + 1. Install the relevant dependencies to your Node.js application for autoinstrumentation: + + npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation + npm install @opentelemetry/[email protected] + + 2. Add the following environmental variables to the Dockerfile for your application and build the image. + + ...