Enable your applications on Amazon EKS clusters

To enable Application Signals for your applications on an existing Amazon EKS cluster

1. Open the CloudWatch console at https://console.amazonaws.cn/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.

   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.

   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.

   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.

   You can either monitor all service workloads by selecting the Auto monitor check box or selectively choose specific workloads and namespaces to monitor.

   To monitor all service workload(s) with Auto monitor:

   1. Select the Auto monitor check box to automatically select all service workload(s) in a cluster.

   2. Choose Auto restart to restart all workload pods to enable Application Signals immediately with Amazon Distro for OpenTelemetry auto-instrumentation (ADOT) SDKs injected into your pods.

   3. Choose Done . When Auto restart is selected, CloudWatch Observability EKS add-on will enable Application Signals immediately. Otherwise, Application Signals will be enabled during the next deployment of each workload.

   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.

   3. Choose Done. The Amazon CloudWatch Observability EKS add-on will immediately inject Amazon 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.

   3. Choose Done. The Amazon CloudWatch Observability EKS add-on will immediately inject Amazon 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.

        • 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.

        • 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.

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/instrumentation@0.54.0

2. Add the following environmental variables to the Dockerfile for your application and build the image.

   ...
   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"]

3. Add the environmental variables OTEL_RESOURCE_ATTRIBUTES_POD_NAME, OTEL_RESOURCE_ATTRIBUTES_NODE_NAME, OTEL_RESOURCE_ATTRIBUTES_DEPLOYMENT_NAME, POD_NAMESPACE and OTEL_RESOURCE_ATTRIBUTES to the deployment yaml file for the application. For example:

   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 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)"

4. Deploy the Node.js application to the cluster.

1. Enable Application Signals for your applications.

   import { aws_applicationsignals as applicationsignals } from 'aws-cdk-lib';
   
   const cfnDiscovery = new applicationsignals.CfnDiscovery(this,
     'ApplicationSignalsServiceRole', { }
   );

   The Discovery CloudFormation resource grants Application Signals the following permissions:

   • xray:GetServiceGraph

   • logs:StartQuery

   • logs:GetQueryResults

   • cloudwatch:GetMetricData

   • cloudwatch:ListMetrics

   • tag:GetResources

   For more information about this role, see Service-linked role permissions for CloudWatch Application Signals.

2. Install the amazon-cloudwatch-observability add-on.

   1. Create an IAM role with the CloudWatchAgentServerPolicy and the OIDC associated with the cluster.

      const cloudwatchRole = new Role(this, 'CloudWatchAgentAddOnRole', {
          assumedBy: new OpenIdConnectPrincipal(cluster.openIdConnectProvider),
          managedPolicies: [ManagedPolicy.fromAwsManagedPolicyName('CloudWatchAgentServerPolicy')],
      });

3. Install the add-on with the IAM role created above.

   new CfnAddon(this, 'CloudWatchAddon', {
       addonName: 'amazon-cloudwatch-observability',
       clusterName: cluster.clusterName,
       serviceAccountRoleArn: cloudwatchRole.roleArn
   });

4. Add one of the following into the PodTemplate section of your workload manifest file.

   Language	File
   Java	instrumentation.opentelemetry.io/inject-java: "true"
   Python	instrumentation.opentelemetry.io/inject-python: "true"
   .Net	instrumentation.opentelemetry.io/inject-dotnet: "true"
   Node.js	instrumentation.opentelemetry.io/inject-nodejs: "true"

   const deployment = {
     apiVersion: "apps/v1",
     kind: "Deployment",
     metadata: { name: "sample-app" },
     spec: {
       replicas: 3,
       selector: {
         matchLabels: {
           "app": "sample-app"
         }
       },
       template: {
         metadata: {
           labels: {
             "app": "sample-app"
           },
           annotations: {
             "instrumentation.opentelemetry.io/inject-$LANG": "true"
           }
         },
         spec: {...},
       },
     },
   };
   
   cluster.addManifest('sample-app', deployment)