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

Manual installation is no longer supported in a Kubernetes environment. Please contact Sysdig support if you need assistance with manual steps.

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)

Configure for Role-Based Access Control (RBAC)

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

All GKE environments have RBAC enabled by default and therefore require this step.

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:

Download sysdig-agent-clusterrole.yaml from GitHub.

Run the following commands:

kubectl apply -f sysdig-agent-clusterrole.yaml
kubectl create serviceaccount sysdig-agent
kubectl create clusterrolebinding sysdig-agent --clusterrole=sysdig-agent --serviceaccount=<namespace>:sysdig-agent  

Configure for OpenShift

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

Create a new OpenShift project for the Sysdig agent deployment.
Run the command:
$oc new-project sysdig-agent
Create a service account for the project and associate it with the Sysdig DaemonSet.
Run the command:
oc create serviceaccount sysdig-agent
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
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.

	V1 Preferred	V2 Preferred
Advantages of this method	A single file to edit and manage	Leverage Kubernetes Secrets to keep access key masked Leverage Kubernetes ConfigMaps and use a separate file to collect all environment variable information (optional)
Files to use	sysdig-agent-daemonset-v1.yaml	sysdig-agent-daemonset-v2.yaml sysdig-agent-configmap.yaml
Minimum edits needed*	R: Access key C: Service account (RBAC or OpenShift) C: Backend on-premise endpoints O: Any custom agent configurations (e.g. Prometheus, custom app checks, etc.)	R: Create a Kubernetes secret from literal access key C: Service account (RBAC or OpenShift) (configmap.yaml) C: Backend endpoints (configmap.yaml) (on-premise ) O. Any custom agent configurations (configmap.yaml)
For on-prem installations	In on-premise installations, you must enter HTTP, port, SSL, and certificate information (backend CONNECTOR endpoints). This is not required in SaaS environments.	In on-premise installations, you must enter HTTP, port, SSL, and certificate information (backend endpoints). This is not required in SaaS environments.

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

Option 1: Install Using V1

Download the sample file sysdig-agent-daemonset-v1.yaml.
Edit the file as needed. See Table 1: Environment Variables.
See also: Understanding the Agent Config Files
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

Download the sample files sysdig-agent-daemonset-v2.yaml and sysdig-agent-configmap.yaml.
Create a secret key using the command:

kubectl create secret generic sysdig-agent --from-literal=access-key=<your sysdig access key>
If using RBAC or OpenShift:
Edit sysdig-agent-daemonset-v2.yaml to uncomment the serviceAccount:sysdig-agent. See Table 1:Environment Variables.
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
Apply the configmap changes using the command:
kubectl apply -f sysdig-agent-configmap.yaml
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.