This page explains how to install the .NET Agent for Linux in a Docker or Kubernetes containerized environment. There are three ways to install the .NET Agent for Linux with containers:
This scenario applies to containers running in Kubernetes where the Cluster Agent is installed. |
This option uses the Auto-Instrumentation feature of the Cluster Agent. It is the recommended option because it offers the highest level of automation and the simplest operational experience for instrumenting .NET applications in a Kubernetes cluster.
To get started, see Auto-Instrument Applications with the Cluster Agent.
| Init container installation requires a Kubernetes environment. |
You can use Kubernetes init containers to instrument the .NET Agent. In this method, the init container copies the agent binaries into the application container at runtime. The deployment spec used by the application references two containers:
The deployment spec is updated to reference these two containers and copy the agent binaries from the init container to the application container at deployment time. Once the copy is performed, the init container terminates.
To use init containers to copy the .NET Agent for Linux binaries, perform these steps:
Build a .NET Core application image. Do not include the .NET Agent for Linux binaries.
Build the .NET Agent for Linux image separately from the application image. You can reuse this image across multiple .NET Core application deployments.
Alternatively, the init container can reference a pre-built image from on Docker Hub.
Edit the deployment spec to add the required sections that allow you to copy the agent binaries from the init container to the application image.
The following snippet from a deployment spec shows the required volumes, volumeMounts, and initContainer definitions. The code example assumes the .NET Core application image is published to dotnet-samples:aspnetapp and the init container image uses the pre-built image docker.io/appdynamics/dotnet-core-agent:<version> (where <version> is the .NET Agent version; for example, 21.5.0):
kind: Deployment
spec:
containers:
- name: dotnet-app
image: microsoft/dotnet-samples:aspnetapp
volumeMounts:
- mountPath: /opt/appdynamics
name: appd-agent-repo
initContainers:
- name: appd-agent
image: docker.io/appdynamics/dotnet-core-agent:<version>
volumeMounts:
- mountPath: /appdynamics
name: appd-agent-repo
volumes:
- name: appd-agent-repo
emptyDir: {} |
To set all of the required .NET Agent environment variables, you must follow the steps in Best Practices to Configure Agents in Kubernetes listed below:
Set Application-Specific Configuration in the Deployment Spec
Use a ConfigMap to set the .NET Agent for Linux environment variables that are shared across applications in a namespace:
apiVersion: v1
data:
CORECLR_PROFILER: "{57e1aa68-2229-41aa-9931-a6e93bbc64d8}"
CORECLR_ENABLE_PROFILING: "1"
CORECLR_PROFILER_PATH: "/opt/appdynamics/libappdprofiler.so"
APPDYNAMICS_AGENT_APPLICATION_NAME: "<value>"
APPDYNAMICS_AGENT_ACCOUNT_NAME: "<value>"
APPDYNAMICS_CONTROLLER_HOST_NAME: "<value>"
APPDYNAMICS_CONTROLLER_PORT: "<value>"
APPDYNAMICS_CONTROLLER_SSL_ENABLED: "<value>"
APPDYNAMICS_AGENT_REUSE_NODE_NAME: "true"
APPDYNAMICS_AGENT_REUSE_NODE_NAME_PREFIX: "<value>"
# variables required to send transaction analytics data
APPDYNAMICS_ANALYTICS_HOST_NAME: "<value>"
APPDYNAMICS_ANALYTICS_PORT: "<value>"
APPDYNAMICS_ANALYTICS_SSL_ENABLED: "<value>"
kind: ConfigMap
metadata:
name: appd-dotnet-config |
Note that the analytics host, port and ssl settings depend on how the Analytics Agent is deployed. See Deploy Analytics in Kubernetes for options.
(Optional) If you are running your .NET Core application in an Alpine Linux container, set LD_LIBRARY_PATH in the ConfigMap:
apiVersion: v1
data:
CORECLR_PROFILER: "{57e1aa68-2229-41aa-9931-a6e93bbc64d8}"
CORECLR_ENABLE_PROFILING: "1"
CORECLR_PROFILER_PATH: "/opt/appdynamics/libappdprofiler.so"
LD_LIBRARY_PATH: "/opt/appdynamics"
...
kind: ConfigMap
metadata:
name: appd-dotnet-config |
Apply the ConfigMap to the namespace:
kubectl -n dotnetapp apply -f appd-dotnet-config.yaml |
Update the deployment spec to reference the ConfigMap:
spec:
containers:
- name: dotnet-app
envFrom:
- configMapRef:
name: appd-dotnet-config
... |
Create a Secret using kubectl:
kubectl -n dotnetapp create secret generic appd-agent-secret --from-literal=access-key=<access-key> |
Update the deployment spec to reference the Secret:
spec:
containers:
- name: dotnet-app
env:
- name: APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY
valueFrom:
secretKeyRef:
name: appd-agent-secret
key: access-key
... |
Set the application-specific tier name environment variable APPDYNAMICS_AGENT_TIER_NAME in the deployment spec:
spec:
containers:
- name: dotnet-app
env:
- name: APPDYNAMICS_AGENT_TIER_NAME
value: dotnet-service |
APPDYNAMICS_AGENT_UNIQUE_HOST_ID Environment VariableThe |
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 the 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"]
... |
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 and viewing the logs using kubectl logs.
Create a ConfigMap based on the contents of AppDynamicsConfig.json:
$ kubectl -n dotnetapp create configmap appd-config --from-file=AppDynamicsConfig.json |
Update the deployment spec to add the AppDynamicsConfig.json file to the container file system. Use volumes and volumeMounts that reference the ConfigMap contents:
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"]
volumeMounts:
- name: appd-config
subPath: AppDynamicsConfig.json
mountPath: /opt/appdynamics/AppDynamicsConfig.json
volumes:
- name: appd-config
configMap:
name: appd-config |
If the .NET Agent for Linux communicates with an on-premises Controller, the Controller certs must be copied to the container. See Enable SSL for the .NET Agent.
Define a ConfigMap to reference the cert file. Use a volume mount in the deployment spec to mount the ConfigMap contents to the container:
$ kubectl create configmap appd-cert --from-file=cacerts |
Add the cert file to the container file system using volumes and volumeMounts as shown in the deployment spec snippet:
kind: Deployment
spec:
containers:
image: microsoft/dotnet-samples:aspnetapp
volumeMounts:
- name: appd-cert
subPath: cacerts
mountPath: /opt/appdynamics/cacerts
volumes:
- name: appd-cert
configMap:
name: appd-cert |
Set the APPDYNAMICS_CONTROLLER_SSL_ENABLED and APPDYNAMICS_CONTROLLER_SSL_CERTFILE environment variables in the ConfigMap. See .NET Agent for Linux Environment Variables.
apiVersion: v1
data:
CORECLR_PROFILER: "{57e1aa68-2229-41aa-9931-a6e93bbc64d8}"
CORECLR_ENABLE_PROFILING: "1"
CORECLR_PROFILER_PATH: "/opt/appdynamics/libappdprofiler.so"
APPDYNAMICS_CONTROLLER_SSL_ENABLED: true
APPDYNAMICS_CONTROLLER_SSL_CERTFILE: /opt/appdynamics/cacerts
...
kind: ConfigMap
metadata:
name: appd-dotnet-config |
This Dockerfile is an example of building the .NET Agent for Linux init container image using a multi-stage build. A complete example of a deployment spec that uses an init container to copy the agent binaries can be found on Github: dotnet-app.yaml.
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:
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 |
Edit the Dockerfile to copy the unpackaged agent binaries to the target folder:
COPY AppDynamics-DotNetCore-linux-x64/ /opt/appdynamics/ |
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.
APPDYNAMICS_AGENT_UNIQUE_HOST_ID Environment VariableThe |
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"]
... |
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 |
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.
Edit the Dockerfile to copy the file containing the on-premises certs to the image. For example:
COPY ./onprem-cacerts /opt/appdynamics/conf/cacerts |
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.
This Dockerfile builds a single image with the application and agent binaries included and this Kubernetes deployment spec references that Docker image.