Configure the Cluster Agent

This page describes the contents of the Cluster Agent bundle downloaded from the Download portal, and how to perform common configuration tasks:

Configure Proxy Support
Configure the Cluster Agent to use SSL for on-premises Controllers
Configure a Pull Secret

See Cluster Agent YAML File Configuration Reference for configuration option details.

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

Directory Structure of the Cluster Agent Bundle

An unzipped Cluster Agent bundle contains this directory structure:

cluster-agent 
├── cluster-agent-operator.yaml 
├── appdynamics-operator-alpine-linux-amd64-21.12.0-88
├── cluster-agent-operator-openshift-1.15-or-less.yaml
├── cluster-agent-operator-openshift.yaml 
├── cluster-agent.yaml 
├── infraviz.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 
├── appdynamics-operator-rhel-linux-amd64-21.12.0-88
├── cluster-agent-operator-openshift-1.15-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 Bundle Files

This table describes the Cluster Agent directory files:

File Name	Description
`appdynamics-operator-alpine-linux-amd64-21.12.0-88`	The AppDynamics Operator artifacts contain Dockerfile, operator binary, licenses and scripts, which are used to build Alpine-based Operator Images.
`appdynamics-operator-rhel-linux-amd64-21.12.0-88`	The AppDynamics Operator artifacts contain Dockerfile-rhel, operator binary, licenses and scripts, which are used to build Rhel-based Operator Images.
`cluster-agent.yaml`	File used to configure and deploy the Cluster Agent. The `cluster-agent.yaml` file provides Controller details and starts the Cluster Agent. Where values are specified in the AppDynamics Operator configuration, these values always take precedence over any internal configuration file.
`cluster-agent-operator.yaml`	Files used to deploy the Cluster Agent Operator. These files set 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.15-or-less.yaml`	Files used to deploy the Cluster Agent 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 required to create the Cluster Agent image.
`Dockerfile`	`dockerfile` used to create the Alpine-based Cluster Agent image.
`Dockerfile-rhel`	`dockerfile` used to create the Rhel-based Cluster Agent image.
`infraviz.yaml`	File used to configure and deploy the InfraViz. The `infrviz.yaml` file provides Controller details and starts the Infrastructure Visibility Agent and Network Visibility Agents. Here, values are specified in the AppDynamics Operator configuration, these values always take precedence over any internal configuration file.
`LICENSE`	Latest EULA file attached with the Cluster Agent image.
`cluster-agent.zip`	Zip archive containing the Cluster Agent binaries and configuration files.
`helm-charts`	Folder 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

To understand proxy in Kubernetes, see the Kubernetes documentation (Proxies in Kubernetes).

Locate and edit the cluster-agent.yaml file.
Add a proxyUrl parameter to 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

To use SSL with your proxy and 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 (one for the proxy server, and a different one for the on-premises Controller), then you can encapsulate both of them into a single secret:

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 uses it appropriately.

This example shows a cluster-agent.yaml file with the customSSLSecret attribute defined:

apiVersion: cluster.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

Pull Secret

If the Cluster Agent requires a secret to pull images from a container registry, use the Kubernetes API to create the secret and reference it in cluster-agent.yaml.

$ kubectl -n appdynamics create secret docker-registry myregcred --docker-server=https://index.docker.io/v1 --docker-username=<docker-username> --docker-password=<docker-password> --docker-email=unused

CODE

$ oc -n appdynamics create secret docker-registry myregcred --docker-server=https://index.docker.io/v1 --docker-username=<docker-username> --docker-password=<docker-password> --docker-email=unused 
$ oc -n appdynamics secrets link appdynamics-operator regcred --for=pull

CODE

Set the imagePullSecret property in cluster-agent.yaml to the name of the secret created above (myregcred):

kind: Clusteragent
metadata:
  name: k8s-cluster-agent
  namespace: appdynamics
spec:
  appName: "mycluster"
  controllerUrl: "http://<appdynamics-controller-host>:8080"
  account: "<account-name>"
  image: "<your-docker-registry>/appdynamics/cluster-agent:tag"
  serviceAccountName: appdynamics-cluster-agent
  imagePullSecret: "myregcred"

CODE

Cluster Agent `YAML` File Configuration Reference

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

Parameter	Description	Example	Default	Dynamically Configurable?	Type	Required?
`account`	AppDynamics account name.	admin	N/A	No	String	Required
`appName`	Name of the cluster; displays in the Controller UI as your cluster name.	k8s-cluster	N/A	No	String	Required
`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 Kubernetes Events.	10	10	No	Integer	Optional
`httpClientTimeout`	If no response is received from the Controller, number of seconds after which the server call is terminated.	30	30	No	Integer	Optional
`image`	Cluster Agent image.	your-docker-registry/appdynamics/cluster-agent:latest	N/A	No	String	Required
`imagePullSecret`	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.	regcred	N/A	No	String	Optional
`instrumentationMaxPollingAttempts`	The maximum number of times Cluster Agent checks for the successful rollout of instrumentation before marking it as failed.	`instrumentationMaxPollingAttempts: 15`	10	Yes	integer	Optional
`labels`	Adds any required pod labels to the Cluster Agent pod.	labels: key1: value1 key2: value2	The following labels are created by default and cannot be modified: `name`:`clusterAgent` `clusterAgent_cr`:<name of agent> `pod-template-hash`:<assigned by Kubernetes> The key value pairs that you specify for this parameter gets added to the Cluster Agent pod along with the default value.	No	map[string]string	Optional
`logFileSizeMb`	Maximum file size of the log in MB.	5	5	Yes	Integer	Optional
`logFileBackups`	Maximum number of backups saved in the log. 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`	Number of log details. `INFO`, `WARNING`, `DEBUG`, or `TRACE`.	"INFO"	`INFO`	Yes	String	Optional
`maxPodLogsTailLinesCount`	Number of lines to be tailed while collecting logs. To use this parameter, enable the log capturing feature. See Enable Log Collection for Failing Pods.	`500`	`500`	Yes	Integer	Optional
`nodeSelector`	The Cluster Agent pod runs on the node that includes the specified `key-value` pair within its labels property. See nodeSelector.	nodeSelector: kubernetes.io/e2e-az-name: az1	N/A	No	map[string]string	Optional
`nsToMonitor`	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. If you require to monitor multiple namespaces, separate the namespaces using the pipe symbol (`\|)` without spaces. This parameter supersedes `nsToMonitor`. If you do not specify a value for this parameter, then the Cluster Agent uses the default value of `nsToMonitor`. This parameter is supported in Cluster Agent >= 20.9, and Controller >= 20.10. See Edit Namespaces.	nsToMonitorRegex: .* `nsToMonitorRegex: namespace1\|namespace2`	N/A	Yes	Regular expression	Optional
`nsToExcludeRegex`	The regular expression for the namespaces that must be excluded from the selected namespaces that match the regular expression mentioned for `nsToMonitorRegex`. This parameter is supported in Cluster Agent >= 20.9, and Controller >= 20.10. This parameter can be used only if you have specified a value for the `nsToMonitorRegex` parameter.	nsToExcludeRegex: ns.*	N/A	Yes	Regular expression	Optional
`podFilter`	Blocklist or allowlist pods based on: Regular expressions for pod names Pod labels Blocklisting or allowlisting by name takes 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/A	Yes	String	Optional
`proxyUrl`	Publicly accessible host name of the proxy.	https://myproxy.example.com:8080	N/A	No	String	Optional
`proxyUser`	Username associated with the basic authentication credentials.	"user1"	N/A	No	String	Optional
`resources`	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`	Yes	Array	Optional
`stdoutLogging`	By default, the Cluster Agent writes to a log file in the `logs` directory. Additionally, the `stdoutLogging` parameter is provided to send logs to the container `stdout`.	"true", "false"	true	Yes	String	Optional
`tolerations`	An array of tolerations required for the pod. See Taint and Tolerations.	tolerations: - effect: NoSchedule key: type value: test - effect: NoExecute key: node.kubernetes.io/not-ready operator: Exists tolerationSeconds: 600	N/A	No	Array	Optional

For specific auto-instrumentation configurations, see Auto-Instrument Applications with the Cluster Agent. 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: cluster.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"
  labels:
	 key1: value1
     key2: value2

CODE