Configure the Cluster Agent

The Cluster Agent is designed to be run on Linux and deployed using the AppDynamics Operator. This page explains the Cluster Agent Directory and how to:

This document contains links to Kubernetes documentation. AppDynamics makes no representation as to the accuracy of Kubernetes documentation because Kubernetes controls its own documentation.

Cluster Agent Directory

An unzipped Cluster Agent has the following directory structure:

cluster-agent
├── cluster-agent-operator-openshift.yaml
├── cluster-agent-operator.yaml
├── cluster-agent.yaml
├── README-alpine.md
└── docker
    ├── cluster-agent.zip
    ├── Dockerfile
    └── start-appdynamics

TEXT

cluster-agent
├── cluster-agent-operator-openshift.yaml
├── cluster-agent-operator.yaml
├── cluster-agent.yaml
├── README-ubuntu.md
└── docker
    ├── cluster-agent.zip
    ├── Dockerfile
    └── start-appdynamics

TEXT

Cluster Agent Directory Explained

This table provides a high-level overview of each of the directory files and includes a description of its purpose.

File name	Description
cluster-agent.yaml	The file used to configure and deploy the Cluster Agent. The `cluster-agent.yaml` file provides your Controller details and starts the Cluster Agent. Where values are specified in the AppDynamics Operator configuration, these values will always take precedence over any internal configuration file.
cluster-agent-operator.yaml	The file used to deploy the AppDynamics Operator. The `cluster-agent-operator.yaml` sets all the default values for Kubernetes, Amazon EKS, and AKS including a minimal set of RBAC permissions.
cluster-agent-operator-openshift.yaml	The file used to deploy the AppDynamics Operator on Red Hat OpenShift. The `cluster-agent-operator-openshift.yaml` sets the default values for Red Hat OpenShift, including a minimal set of RBAC permissions.
docker	The docker directory contains all files needed to create the Cluster Agent image.
Dockerfile	The `dockerfile` used to create the Cluster Agent image.
cluster-agent.zip	The zip archive containing the Cluster Agent binaries and config files.
README-ubuntu.md README-alpine.md	Instructions on how to get started using the Cluster Agent using your preferred OS.
start-appdynamics	The script used to run the Cluster Agent within Docker.

Configure Proxy Support

Locate and edit the cluster-agent.yaml file.
Add a proxyUrl parameter in the cluster-agent.yaml file
```
proxyUrl: <protocol>://<host>:<port>
```
TEXT

(Optional) If the proxy server requires authentication:

Add a proxyUser:
```
proxyUser: <user>
```
CODE

Create a secret with a proxy-password:

kubectl -n appdynamics create secret generic cluster-agent-proxy-secret --from-literal=proxy-password='<password>'

CODE

(Optional) If you are using SSL only for your Proxy:
1. Create a secret from a .pem certificate file. The certificate file must be named proxy-ssl.pem
```
kubectl -n appdynamics create secret generic ssl-cert --from-file=proxy-ssl.pem
```
  TEXT
2. Set a secret filename in the cluster-agent.yaml file:
```
customSSLSecret: “ssl-cert”
```
  TEXT

If you want to use SSL with your proxy, and have SSL for your Controller: See Proxy and On-Premises Certificates Combined.

Configure the Cluster Agent to Use SSL for On-Premises Controllers

Cluster Agent SSL is automatically handled for SaaS Controllers: To configure the Cluster Agent to use SSL for On-Premises Controllers:

Controllers with Public and Self-Signed Certificates

To configure SSL with a public or self-signed certificate, use kubectl to generate a secret. Use the following kubectl command, and include the path to your public or self-signed certificate:

kubectl -n appdynamics create secret generic ssl-cert --from-file=<path-to-your-self-signed-certs>/custom-ssl.pem

CODE

The certificate file must be named: custom-ssl.pem.

After your secret is created you must add the customSSLSecret property with the secret name specified in the previous step to the cluster-agent.yaml file:

customSSLSecret: “ssl-cert”

CODE

Proxy and On-Premises Certificates Combined

If you have two different SSL certificates for Proxy Server and for On-Premises Controller, you can encapsulate both of them into a single secret as follows:

kubectl -n appdynamics create secret generic ssl-cert --from-file=proxy-ssl.pem --from-file=<path-to-your-self-signed-certs>/custom-ssl.pem

TEXT

The Cluster Agent will pull each certificate from the secret identified in the customSSLSecret attribute and use it appropriately.

Example

Example cluster-agent.yaml file with the customSSLSecret attribute defined:

apiVersion: appdynamics.com/v1alpha1
kind: Clusteragent
metadata:
  name: k8s-cluster-agent-manual
  namespace: appdynamics
spec:
  # init agent configuration
  appName: "test-k8s-cluster-agent"
  controllerUrl: "https://<controller-url>:443" # always schema and port
  account: "<account-name>" # account
  # agent related properties
  # custom SSL secret name
  customSSLSecret: "ssl-cert"
  # logging properties
  logLevel: INFO
  logFileSizeMb: 7
  logFileBackups: 6
  # docker image info
  image: "<image-url>"

CODE

Configure the Cluster Agent YAML File

To configure the Cluster Agent, use the cluster-agent.yaml file included with the download package as a template. You can modify the following parameters:

Parameter	Description	Example	Default	Dynamically Configurable?	Type	Required?
account	AppDynamics Account Name	admin	N/A	No	String	Required
appName	The name of the cluster. Displayed in the Controller UI as your cluster name.	k8s-cluster	N/A	No	String	Required
clusterMetricsSyncInterval	How often the Cluster Agent reports cluster-level metrics to the Controller in seconds. Don't set this value to less than 30 seconds.	60	60	No	Integer	Optional
containerBatchSize	The `containerRegistrationInterval` is the interval at which the Cluster Agent checks for containers and registers them with the Controller. This process is known as a container registration cycle. The containers are sent to the Controller in batches. The `containerBatchSize` is the maximum number of containers per batch in one cycle. The maximum number of containers, per Cluster Agent, that can be registered concurrently. The recommended value is 5	5	5	Yes	Integer	Optional
containerFilter	(Optional) Blacklist or whitelist containers based on the container names.	blacklistedLabels: appdynamics.exclude: "true"	blacklistedLabels: appdynamics.exclude: "true"	Yes	String	Optional
containerParallelRequestLimit	The maximum number of parallel requests to the Controller for container registration. The maximum number of container registration batches that can be executed concurrently per cluster agent. The recommended value is 1.	1	1	Yes	Integer	Optional
containerRegistrationInterval	The containerRegistrationInterval is the interval at which the Cluster Agent checks for containers and registers them with the Controller. You should only modify the default value if you want to discover running containers more frequently. The default value should be used in most environments.	120	120	No	Integer	Optional
controllerUrl	Full AppDynamics Controller URL including protocol and port.	HTTP: http://appd-controller.com:8090 HTTPS: https://appd-controller.com:443	N/A	No	String	Required
customSSLSecret	Provides the self-signed or public certificates to the Cluster Agent.	"ssl-cert"	N/A	No	String	Optional
eventUploadInterval	How often Kubernetes warning and state-change events are uploaded to the Controller in seconds. See Monitor Cluster Events.	10	10	No	Integer	Optional
httpClientTimeout	Number of seconds after which server call is terminated if no response is received from the Controller.	30	30	No	Integer	Optional
image	The Cluster Agent image.	your-docker-registry/appdynamics/cluster-agent:latest	N/A	No	String	Required
imagePullSecrets	The credential file used to authenticate when pulling images from your private Docker registry or repository. Depending on how your Docker registry is configured, you may need to create a secret file that the AppDynamics Operator uses when pulling the image for the Cluster Agent. For full details of how to create and use this file, see Create a Secret by providing credentials on the command line in the Kubernetes documentation.	regcred	N/A	No	String	Optional
logFileSizeMb	The maximum file size of the log in MB.	5	5	Yes	Integer	Optional
logFileBackups	The maximum number of backups the log saves. When the maximum number of backups is reached, the oldest log file after the initial log file is deleted.	3	3	Yes	Integer	Optional
logLevel	The number of log details. `INFO`, `WARNING`, `DEBUG, OR TRACE.`	"INFO"	`INFO`	Yes	String	Optional
metadataSyncInterval	Defines how often metadata is collected for containers and pods.	60	60	Yes	Integer	Optional
metricsSyncInterval	The interval in seconds sending container metrics to the Controller.	30	30	No	Integer	Optional
metricUploadRetryCount	The number of times the metric upload action will be retried.	2	2	Yes	Integer	Optional
metricUploadRetryIntervalMilliSeconds	The interval between consecutive metric upload retries, in milliseconds	5	5	Yes	Integer	Optional
nsToMonitor	Namespaces to be monitored in the cluster.	nsToMonitor: - "default" - "appdynamics"	`default`	No	String List (Sequence)	Optional
podBatchSize	The Cluster Agent checks for pods and registers them with the Controller. This process is known as a pod registration cycle. The pods are sent to the Controller in batches. The `podBatchSize` is the maximum number of pods per batch in one registration cycle.	6	30	Yes	Integer	Optional
podFilter	Blacklist or whitelist pods based on: regular expressions for pod names pod labels Blacklisting/Whitelisting by name will take preference over blacklisting/whitelisting by labels. For example, if you have the `podFilter` as : podFilter: blacklistedLabels: - release: v1 whitelistedNames: - ^podname This will blacklist all the pods which have the label - "`release=v1`" except the ones which have their names starting with "`podname`" In case a pod is whitelisted by name and also blacklisted by name, it will be whitelisted In case a pod is whitelisted by label and also blacklisted by label, it will be whitelisted	podFilter: blacklistedLabels: - label1: value1 whitelistedLabels: - label1: value1 - label2: value2 whitelistedNames: - name1 blacklistedNames: - name2	N/A	Yes	String	Optional
proxyUrl	The publicly accessible hostname of the proxy.	https://myproxy.example.com:8080	N/A	No	String	Optional
proxyUser	The username associated with the basic authentication credentials.	"user1"	N/A	No	String	Optional
stdoutLogging	By default, the Cluster Agent writes to a log file in the logs directory. The `stdoutLogging` parameter is provided so you can send logs to the container `stdout` as well.	"true", "false"	true	Yes	String	Optional

Cluster Agent File Example

The example below demonstrates a cluster-agent.yaml configuration file:

apiVersion: appdynamics.com/v1alpha1
kind: Clusteragent
metadata:
  name: k8s-cluster-agent
  namespace: appdynamics
spec:
  appName: "<app-name>"
  controllerUrl: "<protocol>://<appdynamics-controller-host>:8080"
  account: "<account-name>"
  # docker image info
  image: "<your-docker-registry>/appdynamics/cluster-agent:tag"
  nsToMonitor:
    - "default"
  eventUploadInterval: 10
  containerRegistrationInterval: 120
  httpClientTimeout: 30
  customSSLSecret: "<secret-name>"
  proxyUrl: "<protocol>://<domain>:<port>"
  proxyUser: "<proxy-user>"
  metricsSyncInterval: 30
  clusterMetricsSyncInterval: 60
  metadataSyncInterval: 60
  containerBatchSize: 25
  containerParallelRequestLimit: 3
  podBatchSize: 30
  metricUploadRetryCount: 3
  metricUploadRetryIntervalMilliSeconds: 5
  containerFilter:
    blacklistedLabels:
      appdynamics.exclude:
        "true"
    # blacklistedNames:
    #   podName1:
    #     - "containerName1"
    #     - "containerName2"
    #   podName2:
    #     - "containerName1"
    #     - "containerName2"
    # whitelistedNames:
    #   podName1:
    #     - "containerName1"
    #     - "containerName2"
  logLevel: "INFO"
  logFileSizeMb: 5
  logFileBackups: 3
  stdoutLogging: "true"

CODE

Dynamically Configure the Cluster Agent using the AppDynamics Operator

Some of the attributes of the Cluster Agent can be dynamically updated without the need to restart the Cluster Agent container. See Configure the Cluster Agent YAML File.

You can make changes to these properties in the cluster-agent.yaml spec and apply:

kubectl -n appdynamics apply -f cluster-agent.yaml

CODE

To dynamically update the files:

Open a command prompt and navigate to the cluster-agent.yaml file.
Click Save, to save the cluster-agent.yaml configuration file.
To apply the configuration, from the command line, run: kubectl apply -f cluster-agent.yaml

Verify Cluster Agent Configuration

The Cluster Agent checks for configuration changes once a minute. To ensure that your configurations have been applied, check the following locations to confirm that the Cluster Agent is using the new values:

AppDynamics Operator
The Cluster Agent logs

To verify that the AppDynamics Operator processed the configuration changes, open a command prompt and run:

kubectl -n appdynamics describe cm cluster-agent-mon cluster-agent-log

CODE

To verify that the Cluster Agent processed the configuration changes. See View Cluster Agent Logs.

View Cluster Agent Logs

If stdout logging is enabled, open a command prompt, and run:

kubectl -n appdynamics logs <pod-name>

CODE

If stdout logging is not enabled, to get into the Container, open a command-line prompt and run:

kubectl -n appdynamics exec -it <pod-name> -- <shell-type>

CODE

Expected output:

$ kubectl -n appdynamics exec -it k8s-cluster-agent-77f99774bc-pd2vr -- /bin/bash 
appdynamics@k8s-cluster-agent-77f99774bc-pd2vr:/opt/appdynamics/cluster-agent$

CODE

The Cluster Agent directory contents:

appdynamics@k8s-cluster-agent-77f99774bc-pd2vr:/opt/appdynamics/cluster-agent$ ll 
total 49296 
drwxr-xr-x 1 appdynamics appdynamics 4096 Dec 4 14:04 ./ 
drwxr-xr-x 1 appdynamics appdynamics 4096 Dec 4 14:04 ../ 
-rwxr-xr-x 1 appdynamics appdynamics 50443680 Dec 4 14:03 cluster-agent* 
-rw-r--r-- 1 appdynamics appdynamics 198 Dec 4 14:03 cluster-agent.asc 
drwxr-xr-x 1 appdynamics appdynamics 4096 Dec 10 18:15 config/ 
drwxrwxr-- 1 appdynamics appdynamics 4096 Dec 10 18:15 logs/ 
-rwxr--r-- 1 appdynamics appdynamics 2624 Dec 4 14:04 start-appdynamics*

CODE

Once in the Container, cd to the logs directory, and view the cluster-agent.log file.

appdynamics@k8s-cluster-agent-77f99774bc-pd2vr:/opt/appdynamics/cluster-agent$ cd logs/
appdynamics@k8s-cluster-agent-77f99774bc-pd2vr:/opt/appdynamics/cluster-agent/logs$ ll
total 480
drwxrwxr-- 1 appdynamics appdynamics   4096 Dec 10 18:15 ./
drwxr-xr-x 1 appdynamics appdynamics   4096 Dec  4 14:04 ../
-rw-r--r-- 1 appdynamics appdynamics 471339 Dec 11 21:46 cluster-agent.log

CODE