Use Docker Visibility with Red Hat OpenShift

This page describes how to set 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 Splunk 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 Monitor 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)
We recommend that you use Docker CE/EE v17.03 or Docker Engine >= v1.13 with this product. Some data may be unavailable if you are using previous versions of Docker.

Set the Java Options

By default, the MaxMetaspaceSize 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. We recommend 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:

Get the container ID from the cgroup.

cat /proc/self/cgroup | awk -F '/' '{print $NF}'  | head -n 1

CODE

Register the App Server Agents.

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

CODE

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:

Verify that the current project is machine-agent.
```
oc status
```
CODE
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.
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.

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:

Permission	Description
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`

Modify the sample DaemonSet to point to your Controller:

Select the worker node.

nodeSelector:
        node-role.kubernetes.io/compute: "true"

CODE

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

Specify the Docker image.
```
image: "<your image>"
```
CODE
Enable the Machine Agent to run as the privileged user.
```
securityContext:
          privileged: true
```
CODE
If you have a different service account name, replace it with the existing one.
```
serviceAccount: ma
      serviceAccountName: ma
```
CODE

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:

Check the machine-agent DaemonSet.
```
oc get ds
```
CODE
Check the machine-agent pod.
```
oc get pod
```
CODE
The pod name is machine-agent-daemonset-<XXXX>.
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 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 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 Machine Agent
CMD "./start-appdynamics"

CODE

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

Before You Begin

Set the Java Options

Register the Container ID as the Host ID

Create Project and Service Account

Secure the Machine Agent

Run the Machine Agent Without cluster-reader Role

Run the Machine Agent Without Privileged Container Mode

Security Permissions for the Service Account

Create a Docker Image of the Machine Agent

Deploy the Machine Agent as DaemonSet

Verify Machine Agent Status

Sample Machine Agent Deployment Files

Sample DaemonSet

Sample Dockerfile

Sample start Script

Deploy the Machine Agent as `DaemonSet`

Sample `DaemonSet`