Configuring Agents in Kubernetes

This page describes best practices for configuring agents in a Kubernetes environment. See Container Installation Options to understand your options.

This page does not apply to Java applications that use the Cluster Agent auto-instrumentation option. See Enable Auto-Instrumentation of Supported Applications

You can configure agents in Kubernetes using environment variables. We leverage three options for setting environment variables depending on the use case:

• Use ConfgMaps to Configure the App Server Agent

• Use Secrets for the Controller Access Key

• Set Application-Specific Configuration in the Deployment Spec

Gather Login Credentials

To access AppDynamics, you must know your login credentials and the URL where you can access your organization's AppDynamics Controller(s). If you do not have this information, contact your AppDynamics administrator. 

Use ConfigMaps to Configure the App Server Agent

When instrumenting a container running in Kubernetes, each App Server Agent requires that you set environment variables to configure:

• Connection parameters
• Application metadata
• Agent behavior

You can use ConfigMaps to store an application's environment variables in a Kubernetes object within the scope of a namespace. ConfigMaps are an optimal twelve-factor method used to manage agent configuration shared across multiple Kubernetes applications within a namespace. 

Controller credentials configuration is stored in a single ConfigMap and shared with each application in the namespace that reports to that Controller. If you use multiple Controllers across different environments, such as development, test, and production, you can store different ConfigMaps in the namespaces associated with those environments.

To configure the App Server Agent using ConfigMaps:

1. Edit the ConfigMap
2. Apply the ConfigMap to a Namespace
3. Edit the Deployment Spec
4. Apply the Updated Deployment Spec
5. Verify the Environment Variables

Edit the ConfigMap

Edit the Kubernetes ConfigMap to define the environment variables for the application you are instrumenting. You can then include those environment variables in an application's environment by referencing them in the deployment spec. 

For example, the ConfigMap file, ecommerce-java-config.yaml, defines the Java Agent configuration for one or more Kubernetes applications running in a single namespace which reports to the eCommerce application in the AppDynamics Controller.

apiVersion: v1
data:
  APPDYNAMICS_AGENT_APPLICATION_NAME: "eCommerce"
  APPDYNAMICS_AGENT_ACCOUNT_NAME: "<value>"
  APPDYNAMICS_CONTROLLER_HOST_NAME: "<value>"
  APPDYNAMICS_CONTROLLER_PORT: "<value>"
  APPDYNAMICS_CONTROLLER_SSL_ENABLED: "<value>"
  APPDYNAMICS_JAVA_AGENT_REUSE_NODE_NAME: "true"
  APPDYNAMICS_JAVA_AGENT_REUSE_NODE_NAME_PREFIX: "<value>"
kind: ConfigMap
metadata:
  name: ecommerce-java-config 

Apply the ConfigMap to a Namespace

Apply the ConfigMap to a namespace using the kubectl apply command. The example shows applying the ecommerce-java-config.yaml ConfigMap to the ecommerce namespace:

kubectl -n ecommerce apply -f ecommerce-java-config.yaml

Edit the Deployment Spec

To set these environment variables in a particular application, edit the deployment spec to include the ConfigMap by using the envFrom and configMapRef commands. 

For this deployment spec example, ecommerce-deployment.yaml, the environment variables from the ecommerce-java-config ConfigMap are added to the application:

spec:
  containers:
  - name: java-app
    envFrom:
    - configMapRef:
      name: ecommerce-java-config
 ...

Apply the Updated Deployment Spec

Apply the updated deployment spec to restart the application and add environment variables:

kubectl -n ecommerce apply -f ecommerce-deployment.yaml

Use Secrets for the Controller Access Key

The Controller access key is another example of a configuration that you can pass to App Server Agents as an environment variable. Sensitive data is stored in a Kubernetes namespace using a Secret, rather than a ConfigMap. You can use Kubernetes Secrets to obfuscate values rather than manipulate them in plain text.

To configure the App Server Agent access key using a Secret:

1. Use kubectl to Create a Secret 

2. Edit the Deployment Spec
3. Apply the Updated Deployment Spec
4. Verify the Environment Variables

Use kubectl to Create a Secret

Using kubectl or a YAML file, you can create a Secret based on the Controller access key in the application namespace. For example, you can use kubectl to create a Secret that can be referenced by applications in the ecommerce namespace:

kubectl -n ecommerce create secret generic appd-agent-secret --from-literal=access-key=<access-key>

Edit the Deployment Spec

Edit the Kubernetes deployment spec to reference the Secret. For example, to set the APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY environment variable to the access key from the Secret, update the application's deployment spec, ecommerce-deployment.yaml file, using valueFrom and secretKeyRef:

spec:
  containers:
  - name: java-app
    env:
    - name: APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY
      valueFrom:
      secretKeyRef:
        name: appd-agent-secret
        key: access-key
 ...

Apply the Updated Deployment Spec

Apply the updated deployment spec to restart the application and add the environment variables to the application:

kubectl -n ecommerce apply -f ecommerce-deployment.yaml

Set Application-Specific Configuration in the Deployment Spec

The AppDynamics Controller application tier name is used to identify a service that reports under a particular AppDynamics application. An application tier name is an example of agent configuration that is different for each Kubernetes application but typically does not vary across environments and namespaces. Application-specific configuration, like the tier name, is simpler to define in the Kubernetes deployment spec directly.

To configure the App Server Agent tier name in the deployment spec:

1. Edit the Deployment Spec

2. Apply the Updated Deployment Spec
3. Verify the Environment Variables

Edit the Deployment Spec

Edit your Kubernetes deployment spec to define the tier environment variable using name and value. In the ecommerce-deployment.yaml example file, the APPDYNAMICS_AGENT_TIER_NAME is set to shopping-cart-service.

spec:
  containers:
  - name: java-app
    env:
    - name: APPDYNAMICS_AGENT_TIER_NAME
      value: shopping-cart-service

Apply the Updated Deployment Spec

Apply the updated deployment spec to restart the application and add the environment variable to the application:

kubectl -n ecommerce apply -f ecommerce-deployment.yaml

Verify the Environment Variables

Verify the environment variables were added to your application, once you have performed the task to set the agent environment variables:

• Create a ConfgMap

• Create a Secret

• Create an environment variable in the deployment spec

• Restarted the application container

You can log in to the container using kubectl exec:

kubectl -n ecommerce exec -it <pod name> /bin/sh

List the AppDynamics environment variables available in the container to confirm they are defined and have the correct values:

$ env | grep APPD
APPDYNAMICS_AGENT_APPLICATION_NAME=eCommerce
APPDYNAMICS_AGENT_ACCOUNT_NAME=<value>
APPDYNAMICS_CONTROLLER_HOST_NAME=<value>
...