This page provides instructions on setting up the Machine Agent with Docker Visibility enabled to run as a DaemonSet on an OpenShift cluster.

Docker Visibility supports OpenShift Version 3. With the Machine Agent, you can collect performance data from OpenShift clusters. By installing the agent as a DaemonSet on each host in the OpenShift cluster, the DaemonSet monitors each host on the OpenShift cluster and the corresponding containers that have an AppDynamics App Agent running. This process is similar to that of monitoring the Kubernetes cluster.

Using Docker Visibility to monitor OpenShift containers is no longer the preferred option and will eventually be deprecated. Use the Cluster Agent instead as described in Monitoring Kubernetes with the Cluster Agent. The Cluster Agent supports OpenShift container visibility, as well as visibility into cluster health and capacity.

Before You Begin

This functionality requires a Server Visibility license.

  • You must have an OpenShift user account with a cluster-admin role, such as system:admin.
  • Install the OpenShift command line tool (oc)
  • AppDynamics recommends that you use Docker CE/EE v17.03 or Docker Engine v1.13 or later with this product. Some data may be unavailable if you are using previous versions of Docker.

Machine Agent Installation and Configuration

The process includes:

Set the Java Options

By default, the metaspace max is set to 100 MB in OpenShift. If your application operates within a small margin of its existing memory resource allocation, increase the allocation for the application. AppDynamics recommends allocating additional Metaspace Size space to accommodate the machine agent. Directly configure the environment variable GC_MAX_METASPACE_SIZE to set the MaxMetaspaceSize parameter in the deployment through a config map.

Register the Container ID as the Host ID

Install an App Server Agent in each container in a Kubernetes pod to collect application metrics. If multiple App Server agents are running in the same pod (for example, in the RedHat OpenShift platform), you must register the container ID as the unique host ID on both the App Server Agent and the Machine Agent to collect container-specific metrics from the pod. Kubernetes pods can contain multiple containers and they share the same host ID. The Machine Agent cannot identify different containers running in a pod unless each container ID is registered as the host ID. 

To register the container ID as the host ID:

  1. Get the container ID from the cgroup.

    cat /proc/self/cgroup | awk -F '/' '{print $NF}'  | head -n 1
    CODE
  2. Register the App Server Agents.

    -Dappdynamics.agent.uniqueHostId=$(sed -rn '1s#.*/##; 1s/docker-(.{12}).*/\1/p' /proc/self/cgroup) 
    CODE
  3. Register the Machine Agent.

    -Dappdynamics.docker.container.containerIdAsHostId.enabled=true
    CODE

Create Project and Service Account

In OpenShift terminology, a project is a mechanism to isolate a group of users and their resources. An administrator can provide individual users or groups with permission to create projects and/or manage specific projects.

To isolate the Machine Agent from other projects, create a machine agent project:

oc new-project machine-agent
CODE

To create a service account, ma, with necessary privileges for the Machine Agent to obtain metrics:

  1. Verify that the current project is machine-agent.

    oc status
    CODE
  2. Create a service account.

    oc create serviceaccount ma
    CODE

    Service accounts provide a secure way to control OpenShift API access without sharing a regular user’s credentials.

  3. Assign the privileged security context constraints (SCC) to the service account. SCC determines the permissions and abilities of pods. 

    oc adm policy add-scc-to-user privileged -z ma
    CODE

    See Security Permissions for the Service Account for the detailed list of permissions for the service account.

  4. Add the cluster-reader role to the service account.

    oc adm policy add-cluster-role-to-user cluster-reader -z ma
    CODE

Secure the Machine Agent

You can deploy the Machine Agent with tighter security. Determine the level of security for the project and leverage security permissions to secure the Machine Agent.

Run the Machine Agent Without cluster-reader Role

Without the cluster-reader role, the Machine Agent cannot read information such as Pod and ReplicaSet from the OpenShift cluster. The agent can, however, collect other metrics except for the tags in the app server agent container.

Run the Machine Agent Without Privileged Container Mode

To disable this privilege, remove the section below from the DaemonSet YAML file.

securityContext:
          privileged: true  
CODE

Without the Privileged Container mode, the Machine Agent cannot read files like /hostroot/etc/passwd and /hostroot/proc/<pid>/etc. Therefore, it cannot collect metrics such as processes and network.

Disabling this privilege has no effect on collecting the App Server Agent container metrics.

Security Permissions for the Service Account

The Service Account requires the following security permissions to provide maximum isolation to the project under which the Machine Agent is running:

PermissionDescription
The cluster-reader role

This cluster-reader role allows the Machine Agent to read tags from the OpenShift cluster.

For example:

oc adm policy add-cluster-role-to-user cluster-reader -z ma
CODE
The privileged SCC

The privileged SCC allows the Machine Agent to be run as the root user.

For example:

oc adm policy add-scc-to-user privileged -z ma
CODE
Run as privileged container

Running as the privileged container allows the Machine Agent to perform operations such as reading files from /etc and reading process information from /proc.

This privilege is configured in the DaemonSet YAML file as follows.

securityContext:
          privileged: true
CODE

Create a Docker Image of the Machine Agent

Copy the following files to a directory on a machine that can build the Docker image.

  • Machine Agent Bundle - 64-bit Linux (zip)
    Download this bundle and rename it to machine-agent.zip.

  • Dockerfile
    See the sample Docker file below. 

  • start-appdynamics script
    See the sample script below.  

Build the image with your desired method and make it available in your image registry.

Deploy the Machine Agent as DaemonSet

  1. Modify the sample DaemonSet to point to your Controller:
    1. Select the worker node.

      nodeSelector:
              node-role.kubernetes.io/compute: "true"
      CODE
    2. Change the following Controller information in the sample DaemonSet.

      containers:
           - env:
              - name: APPDYNAMICS_CONTROLLER_HOST_NAME
                value: "<controller-host-name>"
              - name: APPDYNAMICS_CONTROLLER_PORT
                value: "<controller-port>"
              - name: APPDYNAMICS_CONTROLLER_SSL_ENABLED
                value: "true"
              - name: APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY
                value: "<account-access-key>"
              - name: APPDYNAMICS_AGENT_ACCOUNT_NAME
                value: "<your-account>" 
              - name: APPDYNAMICS_SIM_ENABLED
                value: "true" 
              - name: APPDYNAMICS_DOCKER_ENABLED
                value: "true"  
      CODE
    3. Specify the Docker image.

      image: "<your image>"
      CODE
    4. Enable the Machine Agent to run as the privileged user.

      securityContext:
                privileged: true
      CODE
    5. If you have a different service account name, replace it with the existing one.

      serviceAccount: ma
            serviceAccountName: ma
      CODE
  2. Create DaemonSet below:
    1. Verify that the current project is machine-agent.

      oc status
      CODE
    2. Create the machine-agent DaemonSet.

      oc create -f machine-agent-daemonset.yaml
      CODE

      The Machine Agent appears in the UI. 

Verify Machine Agent Status

If the Machine Agent does not appear in the UI, check the status as follows:

  1. Check the machine-agent DaemonSet.

    oc get ds
    CODE
  2. Check the machine-agent pod. 

    oc get pod
    CODE

    The pod name is machine-agent-daemonset-<XXXX>.

  3. Check logs whether the last line is "Started AppDynamics Machine Agent Successfully."

    oc get logs -f <machine-agent-daemonset-<XXXX>>
    CODE

Sample Machine Agent Deployment Files

Below are sample DaemonSet, Dockerfile and Start Script that you can use as a reference for deploying the Machine Agent.

Sample DaemonSet

Modify the sample DaemonSet to suit your deployment scenario.

apiVersion: extensions/v1beta1
kind: DaemonSet
metadata:
  name: machine-agent-daemonset 
  namespace: machine-agent 
spec:
  selector:
    matchLabels:
      name: appdynamics-machine-agent
  template:
    metadata:
      labels:
        name: appdynamics-machine-agent
    spec:
      nodeSelector:
        node-role.kubernetes.io/compute: "true"
      containers:
      - env:
        - name: APPDYNAMICS_CONTROLLER_HOST_NAME
          value: "<your-hostname>"
        - name: APPDYNAMICS_CONTROLLER_PORT
          value: "<your-port>"
        - name: APPDYNAMICS_CONTROLLER_SSL_ENABLED
          value: "true"
        - name: APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEY
          value: "<your-access-key>"
        - name: APPDYNAMICS_AGENT_ACCOUNT_NAME
          value: "<your-account>" 
        - name: APPDYNAMICS_SIM_ENABLED
          value: "true" 
        - name: APPDYNAMICS_DOCKER_ENABLED
          value: "true" 
        image: <your-image>
        name: machine-agent 
        securityContext:
          privileged: true
        volumeMounts:
        - mountPath: /hostroot
          name: hostroot
          readOnly: true
        - mountPath: /var/run/docker.sock
          name: docker-sock
      restartPolicy: Always
      imagePullPolicy: Always
      serviceAccount: ma
      serviceAccountName: ma
      volumes:
      - name: hostroot
        hostPath:
          path: /
      - name: docker-sock
        hostPath:
          path: /var/run/docker.sock
CODE

Sample Dockerfile

You can use this Dockerfile sample or the one in OpenShift Visibility Manifests.

# Sample Dockerfile for the AppDynamics Machine Agent
# This is provided for illustration purposes only

FROM ubuntu:16.04
# Install required packages
RUN apt-get update && \
    apt-get install -y unzip && \
    apt-get clean
# Install AppDynamics Machine Agent
ENV MACHINE_AGENT_HOME /opt/appdynamics/machine-agent/
ADD machine-agent.zip /tmp/machine-agent.zip
RUN mkdir -p ${MACHINE_AGENT_HOME} 
# Include start script to configure and start MA at runtime
ADD start-appdynamics ${MACHINE_AGENT_HOME}
RUN chmod 774 ${MACHINE_AGENT_HOME}/start-appdynamics
# change files and directories to be owned by root so MA container user in root 
group can access
RUN chgrp -R 0 /opt && \
    chmod -R g=u /opt
RUN chgrp -R 0 /tmp/machine-agent.zip && \
    chmod g=u /tmp/machine-agent.zip 
# Changing directory to MACHINE AGENT HOME
WORKDIR ${MACHINE_AGENT_HOME}
# Configure and Run AppDynamics Machine Agent
CMD "./start-appdynamics"
CODE

Sample start-appdynamics Script

#!/bin/bash
unzip -oq /tmp/machine-agent.zip -d ${MACHINE_AGENT_HOME} && \
    rm /tmp/machine-agent.zip
# Start Machine Agent
./bin/machine-agent -j jre/
CODE