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 Java, Python, and .NET applications.
Requirements
You have admininstrator permission on the Kubernetes cluster where you are enabling Application Signals.
You must have the AWS CLI installed on the environment where your Kubernetes cluster is running. For more information about installing the AWS CLI, see Install or update the latest version of the AWS 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
Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/
. In the navigation pane, choose Services.
Choose Start discovering your Services.
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 installs the operator, the CloudWatch agent, and other auto-instrumentation
into your cluster. To do so, enter the following command. Replace $REGION
with your AWS 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
Step 3: Set up AWS 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 AWS credentials to your Kubernetes environment.
To set up permissions for an on-premises Kubernetes cluster
Create the IAM user to be used to provide permissions to your on-premises host:
Open the IAM console at https://console.aws.amazon.com/iam/
. Choose Users, Create User.
In User details, for User name, enter a name for the new IAM user. This is the sign-in name for AWS that will be used to authenticate your host. Then choose Next
On the Set permissions page, under Permissions options, select Attach policies directly.
From the Permissions policies list, select the CloudWatchAgentServerPolicy policy to add to your user. Then choose Next.
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.
Choose Create user
Create and retrieve your AWS access key and secret key:
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.
On the user's page, choose the Security credentials tab. Then, in the Access keys section, choose Create access key.
For Create access key Step 1, choose Command Line Interface (CLI).
For Create access key Step 2, optionally enter a tag and then choose Next.
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.
Choose Done.
Configure your AWS credentials in your on-premises host by entering the following command. Replace
ACCESS_KEY_ID
andSECRET_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]: jsonEdit the custom resource that the CloudWatch agent installed using the Helm chart to add the newly created AWS credentials secret.
kubectl edit amazoncloudwatchagent cloudwatch-agent -n amazon-cloudwatch
While your file editor is open mount the AWS credentials into the CloudWatch agent container by adding the following configuration to the top of the deployment. Replace the path
/home/
with the location of your local AWS credentials file.user
/.aws/credentialsapiVersion: 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 add the annotations for Application Signals
-
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.
To annotate a single workload, enter one of the following commands. Replace
$WORKLOAD_TYPE
and$WORKLOAD_NAME
with the 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.
For .NET workloads:
kubectl patch
$WORKLOAD_TYPE
$WORKLOAD_NAME
-p '{"spec": {"template": {"metadata": {"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 additional annotation.instrumentation.opentelemetry.io/otel-dotnet-auto-runtime: "linux-musl-x64"
-
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 Java, Python, and .NET workloads, add all annotations to the namespace.
For Java workloads in the namespace:
kubectl annotate ns
$NAMESPACE
instrumentation.opentelemetry.io/inject-java=trueFor Python workloads in the namespace:
kubectl annotate ns
$NAMESPACE
instrumentation.opentelemetry.io/inject-python=trueFor Python applications, there are additional required configurations. For more information, see Python application doesn't start after Application Signals is enabled.
-
For .NET workloads in the namespace:
kubectl annotate ns
$NAMESPACE
instrumentation.opentelemetry.io/inject-dotnet=true
After adding the annotations, restart all pods in the namespace by entering the following command:
kubectl rollout restart
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.