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

This page 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 contains this directory structure:

cluster-agent 
├── cluster-agent-operator.yaml 
├── cluster-agent-operator-1.14-or-less.yaml
├── cluster-agent-operator-openshift-1.14-or-less.yaml
├── cluster-agent-operator-openshift.yaml 
├── cluster-agent.yaml 
├── README-alpine.md 
└── docker 
	├── cluster-agent.zip 
	├── Dockerfile
	├── LICENSE 
	└── start-appdynamics
└── helm-charts
	├── Chart.yaml
    ├── README.md
    ├── crds
    ├── templates
    └── values.yaml
TEXT 
cluster-agent 
├── cluster-agent-operator.yaml 
├── cluster-agent-operator-1.14-or-less.yaml
├── cluster-agent-operator-openshift-1.14-or-less.yaml
├── cluster-agent-operator-openshift.yaml 
├── cluster-agent.yaml 
├── README-rhel.md 
└── docker 
	├── cluster-agent.zip 
	├── Dockerfile-rhel 
	├── LICENSE 
	└── start-appdynamics
└── helm-charts
	├── Chart.yaml
    ├── README.md
    ├── crds
    ├── templates
    └── values.yaml
TEXT

Cluster Agent Directory Overview

This table provides a high-level overview of the Cluster Agent directory files and a description of their purpose:

File nameDescription

cluster-agent.yaml

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

cluster-agent-operator-1.14-or-less.yaml

These files are used to deploy the AppDynamics Operator

These files set all the default values for Kubernetes, Amazon EKS, and AKS, including a minimal set of RBAC permissions

cluster-agent-operator-openshift.yaml

cluster-agent-operator-openshift-1.14-or-less.yaml

These files are used to deploy the AppDynamics Operator on Red Hat OpenShift.

These files set the default values for Red Hat OpenShift, including a minimal set of RBAC permissions

docker

Docker directory contains all files needed to create the Cluster Agent image

Dockerfile

dockerfile used for creating the Alpine based Cluster Agent image
Dockerfile-rheldockerfile used for creating the Rhel based Cluster Agent image
LICENSEThe latest EULA file attached with Cluster Agent Image

cluster-agent.zip

Zip archive containing the Cluster Agent binaries and configuration files
helm-chartsThe folder that is used to build the charts for deploying the Cluster Agent using helm in Kubernetes

README-rhel.md

README-alpine.md

Contains instructions on how to start the Cluster Agent using your preferred operating system

start-appdynamics

Script used to run the Cluster Agent within Docker

Configure Proxy Support

  1. Locate and edit the cluster-agent.yaml file.

  2. Add a proxyUrl parameter in the cluster-agent.yaml file:

    proxyUrl: <protocol>://<host>:<port>
    TEXT

  3. (Optional) If the proxy server requires authentication:

    1. Add a proxyUser:

      proxyUser: <user>
      CODE

    2. Create a secret with a proxy-password:

      kubectl -n appdynamics create secret generic cluster-agent-proxy-secret --from-literal=proxy-password='<password>'
      CODE
  4. (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

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.

Controllers with Public and Self-Signed Certificates

To configure SSL with a public or self-signed certificate, use kubectl to generate a secret. Enter this 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 the Proxy server and for the 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 pulls each certificate from the secret identified in the customSSLSecret attribute and use it appropriately. 

Example

This example shows a 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 these parameters:

ParameterDescriptionExampleDefaultDynamically Configurable?TypeRequired?

account

AppDynamics account name
admin
N/A

 No

StringRequired

appName

Name of the cluster; displays in the Controller UI as your cluster name.
k8s-cluster
N/A

No

StringRequired

controllerUrl

Full AppDynamics Controller URL, including protocol and port.
HTTP: http://appd-controller.com:8090
HTTPS: https://appd-controller.com:443

N/A

No

StringRequired

customSSLSecret

Provides the self-signed or public certificates to the Cluster Agent.
"ssl-cert"
N/ANoStringOptional

eventUploadInterval

How often Kubernetes warning and state-change events are uploaded to the Controller in seconds. See Monitor Cluster Events
10
10NoIntegerOptional

httpClientTimeout

Number of seconds after which the server call is terminated if no response is received from the Controller.
30

30

NoIntegerOptional

image

Cluster Agent image
your-docker-registry/appdynamics/cluster-agent:latest
N/A

No

String

Required

imagePullSecret

The credential file used to authenticate when pulling images from your private Docker registry or repository. Based on your Docker registry configuration, you may need to create a secret file for the AppDynamics Operator to use when pulling the image for the Cluster Agent. See Create a Secret by providing credentials on the command line in the Kubernetes documentation
regcred
N/ANoStringOptional

logFileSizeMb

Maximum file size of the log in MB.
5
5

Yes

IntegerOptional

logFileBackups

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

IntegerOptional

logLevel

Number of log details. INFO, WARNING, DEBUG, OR TRACE.
"INFO"

INFO

YesStringOptional
maxPodLogsTailLinesCount

The number of lines to be tailed while collecting logs.

To use this parameter enable the log capturing feature. See Manage Logs for Pods.

500500YesIntegerOptional

nodeSelector

The Cluster Agent pod runs on the node that includes the specified key-value pair within its labels property. For information about the functionality of nodeSelector, see nodeSelector.
nodeSelector:
  kubernetes.io/e2e-az-name: az1
N/ANomap[string][string]Optional

nsToMonitor

The namespaces to be monitored in the cluster.
nsToMonitor:
  - "default"
  - "appdynamics"
default

No


String List (Sequence)Optional
nsToMonitorRegex

The regular expression for selecting the required namespaces to be monitored in the cluster.

This parameter supersedes nsToMonitor.If you do not specify any value for this parameter, Cluster Agent uses the default value of nsToMonitor.

This parameter works with the Cluster Agent version 20.9 or later and the Controller version 20.10 or later.

For more details, see Edit Namespaces.

nsToMonitoRegex:

.*

N/AYesRegular expressionOptional
nsToExcludeRegex

The regular expression for the namespaces that must be excluded from the selected namespaces that matches the regular expression mentioned for nsToMonitorRegex.

This parameter works with the Cluster Agent version 20.9 or later and the Controller version 20.10 or later.

This parameter can be used only if you have specified a value for nsToMonitorRegex parameter.

nsToExcludeRegex:

ns.*

N/AYesRegular expressionOptional

podFilter

blocklist or allowlist pods based on:
  • Regular expressions for pod names
  • Pod labels

Blocklisting or allowlisting by name will take preference over blocklisting or allowlisting by labels. For example, if you have the podFilter as :

 podFilter:
 blocklistedLabels:
 - release: v1
 allowlistedNames:
 - ^podname

This blocks all the pods which have the label 'release=v1' except for the ones which have the names starting with 'podname'.

  • When a pod is listed as allowed by name and blocked by name, it will be allowlisted.
  • When a pod is listed as allowed by a label and blocked by a label, it will be allowlisted.
podFilter:
    blocklistedLabels:
      - label1: value1
    allowlistedLabels:
      - label1: value1
      - label2: value2
    allowlistedNames:
      - name1
    blocklistedNames:
      - name2
N/AYesStringOptional

proxyUrl

Publicly accessible host name of the proxy

https://myproxy.example.com:8080
N/A

No

StringOptional

proxyUser

Username associated with the basic authentication credentials

"user1"
N/A

No

StringOptional
resourcesThe requests and limits of CPU and memory resources for the Cluster Agent. 
resources:
  limits:
    cpu: 300m
    memory: "200Mi"
  requests:
    cpu: 200m
    memory: "100Mi"
  • CPU
    • request: 750m
    • limit: 1250m
  • Memory
    • request: 150Mi
      limit: 300Mi
YesArrayOptional

stdoutLogging

By default, the Cluster Agent writes to a log file in the logs directory. Additionally, the stdoutLogging parameter is provided so you can send logs to the container stdout.

"true", "false"
true
YesString Optional

tolerations

An array of tolerations required for the pod. For more information about tolerations, see Taint and Tolerations in the Kubernetes documentation.

tolerations: 
- effect: NoSchedule

key: type
value: test

- effect: NoExecute

key: node.kubernetes.io/not-ready
operator: Exists
tolerationSeconds: 600

N/ANoArrayOptional

There are specific configurations for auto-instrumentation, see Enable Auto-Instrumentation of Supported Applications. Also the .yaml file includes the permissions for auto-instrumentation, which is enabled by default. If you do not want to use auto-instrumentation, you can remove the following text from the .yaml file:

kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
 name: appdynamics-cluster-agent-instrumentation
subjects:
 - kind: ServiceAccount
 name: appdynamics-cluster-agent
 namespace: appdynamics
roleRef:
 kind: ClusterRole
 name: appdynamics-cluster-agent-instrumentation
 apiGroup: rbac.authorization.k8s.io
CODE

Cluster Agent File Example

This example shows 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
  podFilter:
    # blocklistedLabels:
    #   - label1: value1
    # allowlistedLabels:
    #   - label1: value1
    #   - label2: value2
    # allowlistedNames:
    #   - name1
    # blocklistedNames:
    #   - name2
  logLevel: "INFO"
  logFileSizeMb: 5
  logFileBackups: 3
  stdoutLogging: "true"
  resources:
	limits:
		cpu: 300m
		memory: "200Mi"
	requests:
		cpu: 200m
		memory: "100Mi"
CODE

Dynamically Configure the Cluster Agent Using the AppDynamics Operator

You can dynamically update some of the attributes of the Cluster Agent without having 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:

  1. Open a command prompt and navigate to the cluster-agent.yaml file.
  2. Click Save to save the cluster-agent.yaml configuration file.
  3. To apply the configuration, from the command line, enter:  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 and confirm that the Cluster Agent is using the new values, review these locations:

  • AppDynamics Operator
  • Cluster Agent logs

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

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 enter:

kubectl -n appdynamics logs <pod-name>
CODE

If stdout logging is not enabled and to access the Container, open a command-line prompt and enter:

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


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