Install the Cluster Agent with Helm Charts

This page describes how to use Helm Charts to deploy the Cluster Agent.

Helm is a package manager for Kubernetes. Helm charts are a collection of files that describe a set of Kubernetes resources. The Cluster Agent Helm chart is a convenient method to deploy the Cluster Agent Operator and Cluster Agent. You can also use the Cluster Agent Helm chart to deploy multiple Cluster Agents in a single cluster. This may be necessary for larger clusters that exceed the pod monitoring limit for a single Cluster Agent. See Cluster Agent Requirements and Supported Environments.

Requirements

• Cluster Agent version >= 20.6
• Controller version >= 20.6

• Cluster Agent Helm charts are compatible with Helm 3.0

Install a Single Cluster Agent in a Cluster

1. Add the chart repository to Helm:

   helm repo add appdynamics-charts https://ciscodevnet.github.io/appdynamics-charts

   BASH

2. Create a namespace for appdynamics in your cluster:

   kubectl create namespace appdynamics

   BASH

3. Create a Helm values file, in the example called values-ca1.yaml. 
   Update the controllerInfo properties with the credentials from your Controller. 
   Update the clusterAgent properties to set the namespace and pods to monitor. See Configure the Cluster Agent for information about the available properties nsToMonitor, nsToMonitorRegex, nsToExcludeRegex and podFilter.

   values-ca1.yaml

   # AppDynamics controller info
   controllerInfo:
     url: https://<controller-url>:443
     account: <appdynamics-controller-account>                   
     username: <appdynamics-controller-username>                          
     password: <appdynamics-controller-password>                                 
     accessKey: <appdynamics-controller-access-key>  
   
   # Cluster agent config
   clusterAgent:
     nsToMonitorRegex: dev-.*

   YML

   See Configuration Options for values.yaml for more information regarding the available options. Also, you can download a copy of values.yaml from the Helm Chart repository using this command:
   

   helm show values appdynamics-charts/cluster-agent

   BASH

4. If you have not installed the Kubernetes metrics-server in the cluster (usually located in the kube-system namespace), then set install.metrics-server to true in the values file to invoke the subchart to install it.

   install:
     metrics-server: true

   BASH
   

   Setting install.metrics-server installs metrics-server in the namespace with the --namespace flag which is located in the same namespace as the Cluster Agent.

5. Deploy the Cluster Agent to the appdynamics namespace:

   helm install -f ./values-ca1.yaml "<my-cluster-agent-helm-release>" appdynamics-charts/cluster-agent --namespace=appdynamics

   BASH

Enable Auto-Instrumentation

Once you have validated that the Cluster Agent was successfully installed, you can add additional configuration to the instrumentationConfig section of the values YAML file to enable auto-instrumentation. In this example, instrumentationConfig.enabled has been set to true, and multiple instrumentationRules have been defined. See Auto-Instrument Applications with the Cluster Agent.

# AppDynamics controller info
controllerInfo:
  url: https://<controller-url>:443
  account: <appdynamics-controller-account>                   
  username: <appdynamics-controller-username>                          
  password: <appdynamics-controller-password>                                 
  accessKey: <appdynamics-controller-access-key>  

# Cluster agent config
clusterAgent:
  nsToMonitorRegex: ecom|books|groceries

instrumentationConfig:
  enabled: true
  instrumentationMethod: Env
  nsToInstrumentRegex: ecom|books|groceries
  defaultAppName: Ecommerce
  appNameStrategy: namespace
  imageInfo:
    java:
      image: "docker.io/appdynamics/java-agent:latest"
      agentMountPath: /opt/appdynamics
      imagePullPolicy: Always
  instrumentationRules:
    - namespaceRegex: groceries
      language: dotnetcore
      imageInfo:
        image: "docker.io/appdynamics/dotnet-core-agent:latest"
        agentMountPath: /opt/appdynamics
        imagePullPolicy: Always
    - namespaceRegex: books
      matchString: openmct
      language: nodejs
      imageInfo:
        image: "docker.io/appdynamics/nodejs-agent:20.5.0-alpinev10"
        agentMountPath: /opt/appdynamics
        imagePullPolicy: Always
      analyticsHost: <hostname of the Analytics Agent>
      analyticsPort: 443
      analyticsSslEnabled: true

After saving the values-ca1.yaml file with the added auto-instrumentation configuration, you must upgrade the Helm Chart:

helm upgrade -f ./ca1-values.yaml "<my-cluster-agent-helm-release>" appdynamics-charts/cluster-agent --namespace appdynamics

Configuration Options

Install Additional Cluster Agents in a Cluster

The Cluster Agent Helm Chart supports multiple Cluster Agents installation in a cluster. This may be necessary for larger clusters that exceed the pod monitoring limit for a single Cluster Agent. See Cluster Agent Requirements and Supported Environments.

Each additional Cluster Agents that is deployed must have different configuration from any previously deployed Cluster Agents. This is achieved by limiting the monitoring to a distinct set of namespaces and pods using the nsToMonitor, nsToMonitorRegex, nsToMonitorExcludeRegex and podFilter properties. See Configure the Cluster Agent.

The first Cluster Agent must be installed using the steps above where the default value of the deploymentMode property is not overridden and set to PRIMARY. Additional Cluster Agents must set deploymentMode to NAMESPACED.

To install additional Cluster Agents: 

1. Create a new values file, called values-ca2.yaml as the example, that uses the same controllerInfo properties as the first Cluster Agent.
   Set deploymentMode to NAMESPACED. 
   Add additional properties, such as nsToMonitorRegex and podFilter, to set the monitoring scope for this Cluster Agent.


   values-ca2.yaml

   deploymentMode: NAMESPACED
   
   # AppDynamics controller info
   controllerInfo:
     url: https://<controller-url>:443
     account: <appdynamics-controller-account>                   
     username: <appdynamics-controller-username>                          
     password: <appdynamics-controller-password>                                 
     accessKey: <appdynamics-controller-access-key>  
   
   # Cluster agent config
   clusterAgent:
     nsToMonitorRegex: stage.*
   
   podFilter:   
     allowlistedLabels:
       - label1: value1
       - label2: value2   
     blocklistedLabels: []
     allowlistedNames: []   
     blocklistedNames: []

   YML

2. Create a namespace distinct from the previous namespace used for the first installation:

   kubectl create ns appdynamics-ca2

   BASH

3. Install the additional Cluster Agent:

   helm install -f ./values-ca2.yaml "<my-2nd-cluster-agent-helm-release>" appdynamics-charts/cluster-agent --namespace=appdynamics-ca2

   BASH

You can enable auto-instrumentation only in the first Cluster Agent using PRIMARY mode. The Helm Chart generates an error if auto-instrumentation was enabled by additional Cluster Agents using that Namespaced mode.

Cluster Agent Helm Chart Configuration Examples

These examples display various configurations for the Cluster Agent Helm chart:

Use the Cluster Agent Helm Chart to Enable Custom SSL

controllerInfo:
  url: https://<controller-url>:443
  account: <appdynamics-controller-account>                   
  username: <appdynamics-controller-username>                          
  password: <appdynamics-controller-password>                                 
  accessKey: <appdynamics-controller-access-key>

  #=====
  customSSLCert: "<base64 of PEM formatted cert>"
  #=====
 
agentServiceAccount: appdynamics-cluster-agent-ssl     # Can be any valid name
operatorServiceAccount: appdynamics-operator-ssl       # Can be any valid name 

Use the Cluster Agent Helm Chart to Enable the Proxy Controller

Without authentication:

controllerInfo:
  url: https://<controller-url>:443
  account: <appdynamics-controller-account>                   
  username: <appdynamics-controller-username>                          
  password: <appdynamics-controller-password>                                 
  accessKey: <appdynamics-controller-access-key>
  
  #=====
  proxyUrl: http://proxy-url.appd-controller.com
  #=====
 
agentServiceAccount: appdynamics-cluster-agent-ssl     # Can be any valid name
operatorServiceAccount: appdynamics-operator-ssl       # Can be any valid name   

With authentication:

controllerInfo:
  url: https://<controller-url>:443
  account: <appdynamics-controller-account>                   
  username: <appdynamics-controller-username>                          
  password: <appdynamics-controller-password>                                 
  accessKey: <appdynamics-controller-access-key>
  
  #=====
  authenticateProxy: true 
  proxyUrl: http://proxy-url.appd-controller.com
  proxyUser: hello
  proxyPassword: world
  #=====

agentServiceAccount: appdynamics-cluster-agent-ssl     # Can be any valid name
operatorServiceAccount: appdynamics-operator-ssl       # Can be any valid name  

Use the Cluster Agent Helm Chart to add nodeSelector and tolerations

agentPod:
  nodeSelector:
    nodeLabelKey: nodeLabelValue
  tolerations:
    - effect: NoExecute
      operator: Equal
      key: key1
      value: val1
      tolerationSeconds: 11

operatorPod:
  nodeSelector:
    nodeLabelKey: nodeLabelValue
    anotherNodeLabel: anotherNodeLabel
  tolerations:
    - operator: Exists
      key: key1

Best Practices for Sensitive Data

We recommend using multiple values.yaml files to separate sensitive data in separate values.yaml files. Examples of these values are:

• controllerInfo.password
• controllerInfo.accessKey
• controllerInfo.customSSLCert
• controllerInfo.proxyPassword

Each values file follows the structure of the default values.yaml enabling you to easily share files with non-sensitive configuration properties yet keep sensitive values safe.

Default user-values.yaml File Example

deploymentMode: PRIMARY
 
imageInfo:
  agentImage: docker.io/appdynamics/cluster-agent
  agentTag: latest
  operatorImage: docker.io/appdynamics/cluster-agent-operator
  operatorTag: latest
  imagePullPolicy: Always                            
 
controllerInfo:
  url: https://<controller-url>:443
  account: <appdynamics-controller-account>                   
  username: <appdynamics-controller-username>                          
  password: <appdynamics-controller-password>                                 
  accessKey: <appdynamics-controller-access-key>
 
agentServiceAccount: appdynamics-cluster-agent-ssl     # Can be any valid name
operatorServiceAccount: appdynamics-operator-ssl       # Can be any valid name

controllerInfo:
  password: welcome
  accessKey: abc-def-ghi-1516

When installing the Helm Chart, use multiple -f parameters to reference the files:

helm install -f ./user-values.yaml -f ./user-values-sensitive.yaml "<my-cluster-agent-helm-release>" appdynamics-charts/cluster-agent --namespace ca-appdynamics