Enable Application Signals on Kubernetes platforms - Amazon CloudWatch
Step 1: Enable Application Signals in your accountStep 2: Install the CloudWatch agent operator in your clusterStep 3: Set up Amazon credentials for your Kubernetes clustersStep 4: Add annotations
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Enable Application Signals on Kubernetes platforms

To enable applications running on Kubernetes systems other than Amazon EKS, follow the instructions in this section. Application Signals supports both Java applications and Python applications.

Requirements

  • You have admin permission on the Kubernetes cluster where you are enabling Application Signals.

  • You must have the Amazon CLI installed on the environment where your Kubernetes cluster is running. For more information about installing the Amazon CLI, see Install or update the latest version of the Amazon CLI.

  • You have kubectl and helm installed on your local terminal. For more information, see the kubectl and Helm documentation.

Step 1: Enable Application Signals in your account

If you haven't enabled Application Signals in this account yet, you must grant Application Signals the permissions it needs to discover your services. To do so, do the following. You need to do this only once for your account.

To enable Application Signals for your applications

  1. Open the CloudWatch console at https://console.amazonaws.cn/cloudwatch/.

  2. In the navigation pane, choose Services.

  3. Choose Start discovering your Services.

  4. Select the check box and choose Start discovering your Services.

    When you complete this step for the first time in your account, Application Signals creates the AWSServiceRoleForCloudWatchApplicationSignals service-linked role. This role 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.

Step 2: Install the CloudWatch agent operator in your cluster

Installing the CloudWatch agent operator will install the operator, the CloudWatch agent, and other auto-instrumentation into your cluster. To do so, enter the following command. Replace $REGION with your Amazon Region. Replace $YOUR_CLUSTER_NAME with the name that you want to appear for your cluster in Application Signals dashboards.

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

For more information, see amazon-cloudwatch-observability on GitHub.

Step 3: Set up Amazon credentials for your Kubernetes clusters

Important

If your Kubernetes cluster is hosted on Amazon EC2, you can skip this section and proceed to Step 4: Add annotations.

If your Kubernetes cluster is hosted on-premises, you must use the instructions in this section to add Amazon credentials to your Kubernetes environment.

To set up permissions for an on-premises Kubernetes cluster

  1. Create the IAM user to be used to provide permissions to your on-premises host:

    1. Open the IAM console at https://console.amazonaws.cn/iam/.

    2. Choose Users, Create User.

    3. In User details, for User name, enter a name for the new IAM user. This is the sign-in name for Amazon that will be used to authenticate your host. Then choose Next

    4. On the Set permissions page, under Permissions options, select Attach policies directly.

    5. From the Permissions policies list, select the CloudWatchAgentServerPolicy policy to add to your user. Then choose Next.

    6. On the Review and create page, ensure that you are satisfied with the user name and that the CloudWatchAgentServerPolicy policy is in the Permissions summary.

    7. Choose Create user

  2. Create and retrieve your Amazon access key and secret key:

    1. In the navigation pane in the IAM console, choose Users and then select the user name of the user that you created in the previous step.

    2. On the user's page, choose the Security credentials tab. Then, in the Access keys section, choose Create access key.

    3. For Create access key Step 1, choose Command Line Interface (CLI).

    4. For Create access key Step 2, optionally enter a tag and then choose Next.

    5. For Create access key Step 3, select Download .csv file to save a .csv file with your IAM user's access key and secret access key. You need this information for the next steps.

    6. Choose Done.

  3. Configure your Amazon credentials in your on-premises host by entering the following command. Replace ACCESS_KEY_ID and SECRET_ACCESS_ID with your newly generated access key and secret access key from the .csv file that you downloaded in the previous step. By default, the credential file is saved in /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

  4. Edit the custom resource that the CloudWatch agent installed using the Helm chart to add the newly created Amazon credentials secret.

    kubectl edit amazoncloudwatchagent cloudwatch-agent -n amazon-cloudwatch

  5. While your file editor is open mount the Amazon credentials into the CloudWatch agent container by adding the following configuration to the top of the deployment. Replace the path /home/user/.aws/credentials with the location of your local Amazon credentials file.

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

Step 4: Add annotations

The next step is to instrument your application for CloudWatch Application Signals by adding a language-specific annotation to your Kubernetes workload or namespace. This annotation auto-instruments your application to send metrics, traces, and logs to Application Signals.

To add the annotations for Application Signals

  1. You have two options for the annotation:

    • Annotate Workload auto-instruments a single workload in a cluster.

    • Annotate Namespace auto-instruments all workloads deployed in the selected namespace.

    Choose one of those options, and follow the appropriate steps.

  2. To annotate a single workload, enter one of the following commansd. Replace $WORKLOAD_TYPE and $WORKLOAD_NAME with the actual values for your workload.

    • For Java workloads:

      kubectl patch $WORKLOAD_TYPE $WORKLOAD_NAME -p '{"spec": {"template": {"metadata": {"annotations": {"instrumentation.opentelemetry.io/inject-java": "true"}}}}}'

    • For Python workloads:

      kubectl patch $WORKLOAD_TYPE $WORKLOAD_NAME -p '{"spec": {"template": {"metadata": {"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.

  3. To annotate all workloads in a namespace, enter enter one of the following commands. Replace $NAMESPACE with the name of your namespace.

    If the namespace includes both Java and Python workloads, add both annotations to the namespace.

    • For Java workloads in the namespace:

      kubectl annotate ns $NAMESPACE instrumentation.opentelemetry.io/inject-java=true

    • For Python workloads in the namespace:

      kubectl annotate ns $NAMESPACE 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.

    After adding the annotations, restart all pods in the namespace by entering the following command:

    kubectl rollout restart

  4. When the previous steps are completed, in the CloudWatch console, choose Application Signals, Services. This opens the dashboards where you can see the data that Application Signals collects. It might take a few minutes for data to appear.

    For more information about the Services view, see Monitor the operational health of your applications with Application Signals.