This document describes how to install a Sysdig agent container in a Kubernetes environment. It is relevant for any platform where Kubernetes is deployed, including Google Kubernetes Engine (GKE) and Red Hat Open Shift.

You will use DaemonSets to deploy agents on every node in your Kubernetes environment. Once deployed, Sysdig Monitor automatically begins monitoring all of your hosts, apps, pods, and services, and automatically connects to the Kubernetes API server to pull relevant metadata about the environment. If licensed, Sysdig Secure will be launched with default policies that you can view and configure to suit your needs. You can access the front-end web interfaces for Sysdig Monitor and Sysdig Secure immediately.

 Prerequisites

• A supported distribution. See Host Requirements for Agent Installation for details.
  Note that GKE supports only Ubuntu. 
• Kubernetes v 1.2+: The agent installation on Kubernetes requires using DaemonSets, which were not available in early versions of K8s. 
• Sysdig account and access key: Request a trial or full account at Sysdig.com and click the Activate Account button. The Welcome wizard will provide an access key.

Setup Steps (Conditional)

The setup steps are required for some environments and not others, as noted. 

Kernel Headers

The Sysdig agent requires kernel header files in order to install successfully on a host, and the agent is delivered with precompiled headers. 
If the hosts in your environment match the kernel versions included with the agent, no special action is needed. 
In GKE and CoreOs environments, the agent auto-bootstraps the headers, and again no special action is needed.

In some cases, the host(s) in your environment may use Unix versions that do not match the provided headers, and the agent may fail to install correctly. In those cases, you must install the kernel headers manually.  
To do so: 

For Debian-syle distributions, run the command: apt-get -y install linux-headers-$(uname -r)

For RHEL-style distributions, run the command: yum -y install kernel-devel-$(uname -r)

See also Host Requirements for Agent Installation. 

Configure for Role-Based Access Control (RBAC) 

If you are using role-based access control (RBAC) in your Kubernetes environment, this step is required.

The Sysdig agent must be granted read-only access to certain Kubernetes APIs, which the agent uses to populate metadata and provide component metrics. 
Sysdig provides a config file  in GitHub. Deploying this file creates a cluster role and service account in Kubernetes, and defines cluster role binding that grants the Sysdig agent rules in the cluster role.

To enable: 

1. Download sysdig-agent-clusterrole.yaml from GitHub.
   
   

Run the following commands:

Configure for GKE 

NOTE: Ubuntu is the only supported Linux distribution for the Sysdig agent in GKE.
(See also Host Requirements for Agent Installation.)  

If you are using Google Kubernetes Engine, this step is required. 
As described in the Google Container Engine documentation, 

"Because of the way Container Engine checks permissions when you create a Role or ClusterRole, you must first create a RoleBinding that grants you all of the permissions included in the role you want to create. An example workaround is to create a RoleBinding that gives your Google identity a cluster-admin role before attempting to create additional Role or ClusterRole permissions. This is a known issue in the Beta release of Role-Based Access Control in Kubernetes and Container Engine version 1.6. So in order to proceed without error, cluster-admin role should be added to current executing user." 

Run the command: 

kubectl create clusterrolebinding your-user-cluster-admin-binding --clusterrole=cluster-admin [email protected]example.org

Configure for OpenShift 

If you are using Red Hat OpenShift, these steps are required. 

1. Create a new OpenShift project for the Sysdig agent deployment. 
   Run the command:
   $oc new-project sysdig-agent


2. Create a service account for the project and associate it with the Sysdig DaemonSet.
   Run the command:
   oc create serviceaccount sysdig-agent
   
   
3. Add the sysdig-agent service account to privileged SecurityContextConstraints.
   Run the command:
   oc adm policy add-scc-to-user privileged system:serviceaccount:<namespace>:sysdig-agent 
   
   

4. Add the sysdig-agent service account to cluster-reader ClusterRole. 
   Run the command: 
   oc adm policy add-cluster-role-to-user cluster-reader system:serviceaccount:<project>:sysdig-agent

   
   Replace <project> with your OpenShift project name.
   
   

Choose an Installation Method

To deploy agents using Kubernetes DaemonSets, you will download one or more configuration files, edit them as required, and deploy them.

There are two different options: V1 and V2.

*R = Required; C = Conditional (depending on environment); O = Optional.

Option 1: Install Using V1

1. Download the sample file sysdig-agent-daemonset-v1.yaml.
2. Edit the file as needed.  See Table 1: Environment Variables. 
   See also: Understanding the Agent Config Files
3. Apply the file using command 
   kubectl apply -f sysdig-agent-daemonset.yaml. 

The agents will be deployed. 

Access the Sysdig Monitor and/or Sysdig Secure web interfaces. 

Option 2: Install Using V2

1. Download the sample files sysdig-agent-daemonset-v2.yaml and sysdig-agent-configmap.yaml. 
   
   

2. Create a secret key using the command: 

   kubectl create secret generic sysdig-agent --from-literal=access-key=<your sysdig access key>

    

3.  If using RBAC or OpenShift: 
   Edit sysdig-agent-daemonset-v2.yaml to uncomment the serviceAccount:sysdig-agent. See Table 1:Environment Variables. 
   
   
4. Optional: Edit sysdig-agent-configmap.yaml to add tags, backend endpoints, and/or optional parameters, as needed. See Table 1:Environment Variables. 
   Note that optional parameters can be added directly in YAML, without using the #ADDITIONAL_CONF variable, due to the underlying logic of the configmap. 
   See also: Understanding the Agent Config Files
   
   
5. Apply the configmap changes using the command: 
   kubectl apply -f sysdig-agent-configmap.yaml
   
   
6. Apply the daemonset-v2.yaml file using the command: 
   kubectl apply -f sysdig-agent-daemonset-v2.yaml

The agents will be deployed. 

Access the Sysdig Monitor and/or Sysdig Secure web interfaces.

Name	Value	Description
ACCESS_KEY	Sysdig access key	Required
TAGS	Meaningful tags you want applied to your instances	Optional. These are displayed in Sysdig Monitor for ease of use.
COLLECTOR	<collector-hostname.com> or 111.222.333.400	On-prem only. Enter the host name or IP address of the Sysdig collector service.
COLLECTOR_PORT	6443	On-prem only. The port used by the Sysdig collector service; default 6443.
SECURE	true	On-prem only. If using SSL to connect to collector service value = "true" otherwise "false."
CHECK_CERTIFICATE	false	On-prem only. Set to "true" when using SSL/TLS to connect to the collector service and should check for valid TLS certificate.
ADDITIONAL_CONF		Optional.  A place to provide custom configuration values to the agent.

Additional Options

Update a Config File after Agent Installation 

There are two ways to update the agent configuration: edit the file locally and apply it, or use the edit command in K8s. 

Option 1a. Edit the configmap locally and apply the changes with kubectl apply -f:
kubectl apply -f sysdig-agent-configmap.yaml

Option 1b: Edit the daemonset yaml and apply the changes: 
kubectl apply -f sysdig-agent-daemonset.yaml

Option 2: Use  kubectl edit to edit files on the fly:
kubectl edit configmap sysdig-agent 
kubectl edit daemonset sysdig-agent

Running agents will automatically pick the new configuration after Kubernetes pushes the changes across all the nodes in the cluster.