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 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
- You must have an OpenShift user account with a
cluster-admin
role, such assystem
:admin
. - Install the OpenShift command line tool (
oc
) AppDynamics recommends 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. 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:
Get the container ID from the
cgroup
.cat /proc/self/cgroup | awk -F '/' '{print $NF}' | head -n 1
Register the App Server Agents.
-Dappdynamics.agent.uniqueHostId=$(sed -rn '1s#.*/##; 1s/docker-(.{12}).*/\1/p' /proc/self/cgroup)
Register the Machine Agent.
-Dappdynamics.docker.container.containerIdAsHostId.enabled=true
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
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
Create a service account.
oc create serviceaccount ma
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
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
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
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 |
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 |
Run as privileged container | Running as the privileged container allows the Machine Agent to perform operations such as reading files from This privilege is configured in the DaemonSet YAML file as follows. securityContext: privileged: true |
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 tomachine-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"
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"
Specify the Docker image.
image: "<your image>"
Enable the Machine Agent to run as the privileged user.
securityContext: privileged: true
If you have a different service account name, replace it with the existing one.
serviceAccount: ma serviceAccountName: ma
- Create
DaemonSet
below:Verify that the current project is machine-agent.
oc status
Create the machine-agent
DaemonSet
.oc create -f machine-agent-daemonset.yaml
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
Check the machine-agent pod.
oc get pod
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>>
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
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"
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/
Add Comment