Deploy OneAgent on AWS Fargate and AWS App Runner

For AWS Fargate and App Runner, monitoring consumption is based on host units. See Serverless monitoring for details.

To deploy OneAgent on AWS Fargate or App Runner, read the instructions provided below.

Prerequisites

Create a PaaS Token.
Review the list of supported applications and versions.

Integrate OneAgent into your application image

There are three ways to integrate OneAgent with AWS Fargate applications.

Note: For AWS App Runner, you can only use the build-time injection.

Automatic injection (for EKS only) manages upgrades and lifecycle.

Automatic injection

To use this option you need:

Kubernetes version 1.14+
OneAgent Operator v0.8.0+

Create an AWS Fargate pod execution role and a Fargate profile for your cluster by following the instructions in Getting started with AWS Fargate using Amazon EKS.
optional If you want the Kubernetes scheduler to run OneAgent in Fargate, add the dynatrace namespace to your Fargate profile in the AWS console.
Create a Dynatrace namespace.

bash
kubectl create namespace dynatrace

Install OneAgent Operator.
OneAgent Operator acts on its dynatrace namespace. You can also observe the logs of OneAgent Operator.

bash
kubectl apply -f https://github.com/Dynatrace/dynatrace-oneagent-operator/releases/latest/download/kubernetes.yaml
kubectl -n dynatrace logs -f deployment/dynatrace-oneagent-operator

Create the secret holding the PaaS token for authentication to the Dynatrace cluster.

bash
kubectl -n dynatrace create secret generic oneagent --from-literal="paasToken=PAAS_TOKEN"

Save the OneAgent custom resource definition. The rollout of Dynatrace OneAgent for application-only installations is governed by the custom resource type OneAgentAPM. Retrieve the cr-apm.yaml file from the GitHub repository.

bash
curl -o cr-apm.yaml https://raw.githubusercontent.com/Dynatrace/dynatrace-oneagent-operator/master/deploy/cr-apm.yaml

Adapt the values of the custom resource as follows:

required Specify the spec.apiUrl parameter, which is the URL of your Dynatrace environment, for your SaaS, Managed, or ActiveGate instance.
optional Configure spec.useImmutableImage to true to pull a OneAgent docker image from your Dynatrace environment. Use this parameter together with the agentVersion parameter to control the version of OneAgent.
optional Configure spec.agentVersion using semantic versioning (major.minor.patch - example: 1.203.0). If no version is specified, the OneAgent defaults to the latest version available.
optional Configure network zones by setting the spec.networkZone parameter to your network zone.

yaml
spec:
  networkZone: <your_network_zone>

See network zones for more information.

Label your namespaces.
OneAgent Operator injects into all pods that belong to namespaces labeled oneagent.dynatrace.com/instance. The value for this label must be the name of the OneAgentAPM instance that you want to use to configure the corresponding namespaces. You must label all namespaces you want to monitor. Note that the namespaces can point to different OneAgentAPM instances.

bash
kubectl label namespace default oneagent.dynatrace.com/instance=oneagentapm

Configure the injection.
You can configure the injection through Kubernetes annotations.

Note: These settings apply to all containers running on the corresponding pods.

Namespace annotationsPod annotations

oneagent.dynatrace.com/inject: <"true"> or <"false">. Sets the default injection for pods on the namespace. Can be overridden by adding the annotation to the pods themselves. It defaults to true.

Example

bash
kubectl annotate namespace default oneagent.dynatrace.com/inject=false
namespace/default annotated

oneagent.dynatrace.com/inject: <"true"> or <"false">. If set to false, no modifications will be applied to the pod. If not set, the default on the namespace is used.
oneagent.dynatrace.com/flavor: <"default"> or <"musl">. If set, it indicates whether binaries for glibc or musl are to be downloaded. It defaults to glibc.
Note: If your container uses musl (for example, Alpine base image), you must add the flavor annotation in order to monitor it.
oneagent.dynatrace.com/technologies: <"comma-separated technologies list">. If set, it filters which code modules are to be downloaded. It defaults to "all".
oneagent.dynatrace.com/install-path: <"path">. If set, it indicates the path where the unpacked OneAgent directory will be mounted. It defaults to "/opt/dynatrace/oneagent-paas".
oneagent.dynatrace.com/installer-url: <"url">. If set, it indicates the URL from where the OneAgent app-only package will be downloaded. It defaults to the Dynatrace environment API configured on the API URL of OneAgentAPM.

Example

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sample-app
spec:
  selector:
    matchLabels:
      app: sample-app
  strategy:
    type: Recreate
  template:
    metadata:
      annotations:
        # The configuration for app-only injection should be set here.
        oneagent.dynatrace.com/technologies: "java,nginx"
        oneagent.dynatrace.com/flavor: "musl"
        oneagent.dynatrace.com/inject: "true"
        oneagent.dynatrace.com/install-path: "/dynatrace"
        oneagent.dynatrace.com/installer-url: "https://my-custom-url/route/file.zip"
      labels:
        app: sample-app
    spec:
      containers:
      - command: [ "java", "-jar", "/app/app.jar" ]
        image: "my-image"
        # ...

Create the custom resource

bash
kubectl apply -f cr-apm.yaml

Deploy your applications.
All deployed pods will then be monitored.

Note: By default, OneAgent logs are located in /opt/dynatrace/oneagent-paas/log inside the instrumented containers. For guidance on troubleshooting possible issues, see Troubleshoot deployment and connectivity errors on Kubernetes.

Build-time injection (for ECS, EKS, and App Runner) embeds OneAgent into your container image.

Build-time injection

Docker multi-stage image buildsClassic integration

To use this option you need:

Docker version 17.05+.
OneAgent version 1.155+.

Sign in to Docker with your Dynatrace environment ID as username and PaaS token as password.
```
bash
docker login -u <your-environment-id> <your-environment-url>
```

Add two additional lines of code to the application image, after the last FROM command:

bash
COPY --from=<your-environment-url>/linux/oneagent-codemodules:<technology> / /
ENV LD_PRELOAD /opt/dynatrace/oneagent/agent/lib64/liboneagentproc.so

Note:

Replace <your-environment-url> with the URL or IP address of your environment or of your ActiveGate.
- SaaS {your-environment-id}.live.dynatrace.com¹
- Managed {your-domain}/e/{your-environment-id}¹
  
  ¹
  If you use your own environment ActiveGate, use the <ip-address>:9999 or <hostname>:9999 format.
Replace <technology> with the code module required for your application. Valid options are all, java, apache, nginx, nodejs, dotnet, php, sdk, and go. You can specify several code modules, separated by hyphen (-), for example java-go. Including specific technology-support options, rather than support for all technology options, results in a smaller OneAgent package.

What if my Docker image is based on Alpine Linux?

Dynatrace OneAgent supports Alpine Linux based environments. Use this syntax:

bash
COPY --from=<your-activegate>/linux/oneagent-codemodules-musl:<technology> / /
ENV LD_PRELOAD /opt/dynatrace/oneagent/agent/lib64/liboneagentproc.so

Valid options here are all, go, java, apache, nginx, and nodejs.

Build your application image.

Build the Docker image from your dockerfile to use it in your Kubernetes environment:

bash
docker build -t yourapp .

Note: You can monitor your application containers with a different Dynatrace environment. To do this, read the instructions below:

For OneAgent version 1.139+, if you have an existing application image where you've already added the OneAgent code modules for a specific Dynatrace environment, you can have the OneAgent report to another Dynatrace environment without rebuilding your application image.

For this you need to make a call to the REST endpoint of your second Dynatrace environment. Make sure to adapt the respective placeholders <your-environment-id> and <your-paas-token>.

bash
curl "https://<your-environment-id>.live.dynatrace.com/api/v1/deployment/installer/agent/connectioninfo?Api-Token=<your-paas-token>"

In return, you get a JSON object that covers the required information that needs to be passed as an environment variable to the application container. Make sure you set the environment variables of the application container as described below:

DT_TENANT: equals tenantUUID
DT_TENANTTOKEN: equals tenantToken
DT_CONNECTION_POINT: semi-colon separated list of communicationEndpoints

Add the following commands to your current Dockerfile to integrate OneAgent and activate instrumentation of your application. Define variables with optional default values using ARG instructions.

bash
ARG DT_API_URL="https://<your-environment-id>.live.dynatrace.com/api"
ARG DT_API_TOKEN="<your-paas-token>"
ARG DT_ONEAGENT_OPTIONS="flavor=default&include=<technology1>&include=<technology2>"
ENV DT_HOME="/opt/dynatrace/oneagent"
RUN mkdir -p "$DT_HOME" && \
    wget -O "$DT_HOME/oneagent.zip" "$DT_API_URL/v1/deployment/installer/agent/unix/paas/latest?Api-Token=$DT_API_TOKEN&$DT_ONEAGENT_OPTIONS" && \
    unzip -d "$DT_HOME" "$DT_HOME/oneagent.zip" && \
    rm "$DT_HOME/oneagent.zip"
ENTRYPOINT [ "/opt/dynatrace/oneagent/dynatrace-agent64.sh" ]
CMD [ "executable", "param1", "param2" ] # the command of your application, for example, Java

Notes:

The commands above that use wget and unzip might fail if they aren't provided by the base image.
Replace <your-environment-id> with your Dynatrace environment ID. If you're using Dynatrace Managed, you need to provide your Dynatrace Cluster URL (https://<YourDynatraceServerURL>/e/<your-environment-id>/api).
Replace <your-paas-token> with your PaaS token.
DT_ONEAGENT_OPTIONS - this is the flavor (valid options are default or musl for Alpine images) and the technology (code module).
- Syntax for default is flavor=default&include=all.
- Syntax for musl is flavor=musl&include=all.

What if my Docker image is based on Alpine Linux?

Dynatrace OneAgent supports the flavor musl for Alpine Linux based environments. Valid options for flavor=musl are all, go, java, apache, nginx, and nodejs.

Build your application image.

Build the Docker image from your dockerfile to use it in your Kubernetes environment:

bash
docker build -t yourapp .

Note: You can monitor your application containers with a different Dynatrace environment. To do this, read the instructions below:

For this you need to make a call to the REST endpoint of your second Dynatrace environment. Make sure to adapt the respective placeholders <your-environment-id> and <your-paas-token>.

bash
curl "https://<your-environment-id>.live.dynatrace.com/api/v1/deployment/installer/agent/connectioninfo?Api-Token=<your-paas-token>"

DT_TENANT: equals tenantUUID
DT_TENANTTOKEN: equals tenantToken
DT_CONNECTION_POINT: semi-colon separated list of communicationEndpoints

Runtime injection (for ECS only) pulls OneAgent when the container starts.

Runtime injection

To install Dynatrace OneAgent at runtime, you must deploy your application using a task with two container definitions. One is for downloading and unzipping the OneAgent to a shared volume, the other is your application container, which must mount the same volume.

For the runtime injection, follow the steps below.

Go to Fargate Task Definition > Create New Task Definition > select Fargate > click Next Step.
Name the task, optionally set roles and sizes, then scroll down to Volumes > Add volume. Add a volume of type Bind Mount named oneagent.

Note: You must create a volume before creating container definitions in order to set the shared volume in each container.

Scroll up to Container Definition > choose Add container, and in the Standard subsection, add a container named install-oneagent, set the image to Alpine versions 3.8+ ("alpine:3"), and select the memory limits.

Note: There are two types of memory limits: soft and hard. ECS requires that you define the limit for at least one type of memory. We recommend using the default setting (soft limit of 128 MiBs), as it's less restrictive, but you can adjust it as needed.

Scroll to Environment and do the following:

Uncheck the Essential parameter.
In the Entry point field, enter /bin/sh,-c.
In the Command field, enter ARCHIVE=$(mktemp) && wget -O $ARCHIVE "$DT_API_URL/v1/deployment/installer/agent/unix/paas/latest?Api-Token=$DT_PAAS_TOKEN&$DT_ONEAGENT_OPTIONS" && unzip -o -d /opt/dynatrace/oneagent $ARCHIVE && rm -f $ARCHIVE.

In the Environment variables subsection, define:

DT_API_URL - this is the API URL for your Dynatrace environment.
- For SaaS: https://<your-environment-id>.live.dynatrace.com/api
- For Managed: https://<cluster>/e/<your-environment-id>/api
- For ActiveGate: https://<your-active-gate-IP-or-hostname>:9999/e/<your-environment-id>/api.
DT_ONEAGENT_OPTIONS- this is the flavor (valid options are default or musl for Alpine images) and the technology (code module).
- Syntax for default is flavor=default&include=all.
- Syntax for musl is flavor=musl&include=all.
DT_PAAS_TOKEN - this is your PaaS token to download the OneAgent code modules.

Scroll to Storage and logging to define the mount point with the source volume oneagent and the container path /opt/dynatrace/oneagent.
Click Add to create the container definition.
Choose Add container again, this time to define your application, and complete the fields in the Standard subsection according to your application requirements.
Scroll to Environment, and in Environment variable, define LD_PRELOAD with the value /opt/dynatrace/oneagent/agent/lib64/liboneagentproc.so.
Scroll to Startup Dependency Ordering and enter the container name install-oneagent and the condition Complete.
Scroll to Storage and logging to define the mount point with the source volume oneagent and the container path /opt/dynatrace/oneagent.
Select Update to update your container definition.
Deploy the new version of your task definition on your ECS cluster.

Note:

On the Logs tab for the install-oneagent container, you can see the code modules' ZIP file being downloaded by wget and being unzipped.
On the Logs tab for your application workload container, you can see the code module being loaded by the process.

In the Dynatrace web UI, your Fargate application workload container will show up in the Hosts section. The instrumented process will show up in Processes as a typical Docker container.

Note: The runtime approach requires Fargate versions 1.3+. For earlier versions, select the build-time approach.

Configure network zones optional

You can configure network zones as an environment variable:

DT_NETWORK_ZONE: equals your.network.zone

See network zones for more information.