AppDynamics switched from Semantic Versioning to Calendar Versioning starting in February 2020 for some agents and March 2020 for the entire product suite.


    Skip to end of metadata
    Go to start of metadata

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

    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>
    3. (Optional) If the proxy server requires authentication:

      1. Add a proxyUser:

        proxyUser: <user>
      2. Create a secret with a proxy-password:

        kubectl -n appdynamics create secret generic cluster-agent-proxy-secret --from-literal=proxy-password='<password>'
    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
      2. Set a secret filename in the cluster-agent.yaml file:

        customSSLSecret: “ssl-cert”

    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

    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”

    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

    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>" 

    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

    imagePullSecrets

    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. INFOWARNING, 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

    Blacklist or whitelist pods based on:
    • Regular expressions for pod names
    • Pod labels

    Blacklisting or whitelisting by name will take preference over blacklisting or 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 for the ones which have the names starting with 'podname'.

    • When a pod is whitelisted by name and also blacklisted by name, it will be whitelisted.
    • When a pod is whitelisted by a label and also blacklisted by a label, it will be whitelisted.
    podFilter:
    blacklistedLabels:
    - label1: value1
    whitelistedLabels:
    - label1: value1
    - label2: value2
    whitelistedNames:
    - name1
    blacklistedNames:
    - 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

    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

    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:
        # blacklistedLabels:
        #   - label1: value1
        # whitelistedLabels:
        #   - label1: value1
        #   - label2: value2
        # whitelistedNames:
        #   - name1
        # blacklistedNames:
        #   - name2
      logLevel: "INFO"
      logFileSizeMb: 5
      logFileBackups: 3
      stdoutLogging: "true"

    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

    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

    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>

    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>


    Expected output: 

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


    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*

     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
    • No labels