Use a Dockerfile

Note: This scenario applies to containers running in Docker and Kubernetes.

You can use a Dockerfile to copy the .NET Agent for Linux to the Docker image at build time. To use the option, create a single image that contains both the application and .NET Agent for Linux binaries.

To copy the agent into the application image during the Docker image build:

  1. Download and Unzip the .NET Agent for Linux
  2. Copy the Agent Binaries to the Image
  3. Set the .NET Agent for Linux Environment Variables
  4. Set the APPDYNAMICS_AGENT_UNIQUE_HOST_ID Environment Variable
  5. Copy the AppDynamicsConfig.json File to the Image
  6. (On-Premises Controller only) Copy the Controller Certs to the Image
  7. Example Configuration for Using a Dockerfile

Download and Unzip the .NET Agent for Linux

Download the .NET Agent for Linux programmatically or from the downloads portal. The agent is packaged as a zip file. In a shell, unzip it to the AppDynamics-DotNetCore-linux-x64 folder: 

$ unzip AppDynamics-DotNetCore-linux-x64-<version>.zip -d AppDynamics-DotNetCore-linux-x64

Copy the Agent Binaries to the Image

Edit the Dockerfile to copy the unpackaged agent binaries to the target folder:

COPY AppDynamics-DotNetCore-linux-x64/ /opt/appdynamics/

Set the .NET Agent for Linux Environment Variables

If your application runs in a non-Kubernetes environment (for example, using dockerrun), set the agent environment variables in the Dockerfile. For example:

ENV CORECLR_PROFILER="{57e1aa68-2229-41aa-9931-a6e93bbc64d8}"
ENV CORECLR_ENABLE_PROFILING=1
ENV CORECLR_PROFILER_PATH="/opt/appdynamics/libappdprofiler.so"
ENV APPDYNAMICS_AGENT_APPLICATION_NAME=<value>
ENV APPDYNAMICS_AGENT_TIER_NAME=<value>
ENV APPDYNAMICS_AGENT_ACCOUNT_NAME=<value>
ENV APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY=<value>
ENV APPDYNAMICS_CONTROLLER_HOST_NAME=<value>
ENV APPDYNAMICS_CONTROLLER_PORT=<value>
ENV APPDYNAMICS_CONTROLLER_SSL_ENABLED=<value>
ENV APPDYNAMICS_AGENT_REUSE_NODE_NAME=true
ENV APPDYNAMICS_AGENT_REUSE_NODE_NAME_PREFIX=<value>
# variables required to send transaction analytics data
ENV APPDYNAMICS_ANALYTICS_HOST_NAME=<value>
ENV APPDYNAMICS_ANALYTICS_PORT=<value>
ENV APPDYNAMICS_ANALYTICS_SSL_ENABLED=<value>

For Kubernetes applications, omit these environment variables from the Dockerfile and set them using ConfigMaps and Secrets.

The reuse node name and prefix environment variables are required to support unique node naming for multiple container instances for the same application image. See .NET Agent for Linux Environment Variables. The analytics host, port and ssl settings depend on how the Analytics Agent is deployed. See Deploy Analytics in Kubernetes for options.

If you are running your .NET Core application in an Alpine Linux container, set LD_LIBRARY_PATH to the location of the agent binaries. For a Docker application, set LD_LIBRARY_PATH in the Dockerfile:

ENV CORECLR_PROFILER="{57e1aa68-2229-41aa-9931-a6e93bbc64d8}"
ENV CORECLR_ENABLE_PROFILING=1
ENV CORECLR_PROFILER_PATH="/opt/appdynamics/libappdprofiler.so"
ENV LD_LIBRARY_PATH="/opt/appdynamics"
...

For a Kubernetes application, set LD_LIBRARY_PATH in the ConfigMap.

Set the APPDYNAMICS_AGENT_UNIQUE_HOST_ID Environment Variable

Note: The APPDYNAMICS_AGENT_UNIQUE_HOST_ID environment variable is supported in version 20.7.0+ of the .NET Agent for Linux. For earlier version, a property must be set in AppDynamicsConfig.json based on a runtime value. This must be performed in the container startup script.

For Kubernetes applications, set the APPDYNAMICS_AGENT_UNIQUE_HOST_ID environment variable to enable APM correlation with the Cluster Agent. Since the value depends on a runtime value, set this environment variable in the container startup command using the values documented in Manually Configure App Agents to Correlate with the Cluster Agent. For example, for a Kubernetes environment with a Docker runtime, set the environment variable as shown (export is required):

kind: Deployment
spec:
  containers:
    image: microsoft/dotnet-samples:aspnetapp
    command: ["/bin/sh"]
    args: ["-c", "export APPDYNAMICS_AGENT_UNIQUE_HOST_ID=$(sed -rn '1s#.*/##; 1s/(.{12}).*/\\1/p' /proc/self/cgroup) && dotnet aspnetapp.dll"]
...

Copy the AppDynamicsConfig.json File to the Image

Some .NET Agent for Linux options must be set in the AppDynamicsConfig.json file. This includes setting the outputtype to console, which facilitates sending the agent logs to log aggregation tools. Create the AppDynamicsConfig.json file with the required configuration.

Edit the Dockerfile to copy AppDynamicsConfig.json to the image:
COPY ./AppDynamicsConfig.json /opt/appdynamics/AppDynamicsConfig.json

(On-Premises Controller only) Copy the Controller Certs to the Image

For .NET Agent for Linux agents communicating with an on-premises Controller, the Controller certs must be copied to the image. See Enable SSL for the .NET Agent.

  1. Edit the Dockerfile to copy the file containing the on-premises certs to the image. For example:
    COPY ./onprem-cacerts /opt/appdynamics/conf/cacerts
  2. Set the APPDYNAMICS_CONTROLLER_SSL_ENABLED and APPDYNAMICS_CONTROLLER_SSL_CERTFILE environment variables. See .NET Agent for Linux Environment Variables. For a Docker application, set these environment variables in the Dockerfile: 
    ENV APPDYNAMICS_CONTROLLER_SSL_ENABLED="true"
ENV APPDYNAMICS_CONTROLLER_SSL_CERTFILE="/opt/appdynamics/cacerts"
    For a Kubernetes application, set these environment variables in the ConfigMap.

Example Configuration for Using a Dockerfile

This Dockerfile builds a single image with the application and agent binaries included and this Kubernetes deployment spec references that Docker image.