Capsule8 Docs
Capsule8 Docs

Installation on CRI-O and Containerd

The Capsule8 sensor can be installed on any system where the container runtime is CRI-compatible, such as CRI-O and Containerd. After you install the Capsule8 sensor, you can deploy a sensor configuration, which sets the sensor’s functionality. However, there are some CRI-specific configuration settings that we will discuss in this doc.


The CRI sensor configuration values reside in the sensor configuration file - (/etc/capsule8/capsule8-sensor.yaml).

There are three CRI-specific configuration values:

Value Meaning Default Example
enabled Boolean indicating if the sensor is enabled or not false crisensor.enabled: true
addr String path to the CRI Container Runtime API “” crisensor.addr: unix://var/run/crio/crio.sock
poll_interval Duration indicating how often the CRI interface should be checked for changes to container state 250ms crisensor.poll_interval: 150ms

The addr value must be prefixed with unix://, and will error if this is not the case.

For example, if you wanted to connect to the CRI-O unix socket, you would specify addr as addr: unix://var/run/crio/crio.sock

In YAML, this takes the following form:

    enabled: true
    addr: unix://var/run/crio/crio.sock
    poll_interval: 250ms

Default Unix Socket Paths For Supported Runtimes

The default paths for supported runtimes are shown in the table below:

Runtime Socket Path Example Config Option
CRI-O /var/run/crio/crio.sock crisensor.addr: unix://var/run/crio/crio.sock
Containerd /var/run/containerd/containerd.sock crisensor.addr: unix://var/run/containerd/containerd.sock
Container deployment

If you are deploying the Capsule8 sensor in a container, the path specified in crisensor.addr must match the path of the unix socket as mounted into the container.

If you are using CRI-O as your container runtime, you will need to set the environment variable GRPC_GO_REQUIRE_HANDSHAKE to off when running the sensor. This can be added to the env section of your Kubernetes daemonset manifests, as shown below:

   value: "off"

This environment variable is required due to a GRPC protocol change between versions 1.17 and newer. Many versions of CRI-O are built with the older version of GRPC and require the environment variable for compatibility.

If you do not set the GRPC_GO_REQUIRE_HANDSHAKE environment variable, you may encounter the following error when the sensor is unable to connect to the CRI socket:

ERRO[0004] crisensor: connection error context deadline exceeded 

This indicates that the capsule8-sensor was unable to connect to the CRI-compatible container runtime’s unix socket.

Setting the environment variable solves the issue.


The CRI-based sensor is polling by design and not event-driven. As a result of this, it is possible that container events or state transitions may occur between polls, resulting in reduced visibility of events. This is due to limitations of the CRI API as of 2019-08-30, as the API does not provide any mechanisms to notify a caller when a state transition occurs.

To partially work around the above limitation, the sensor will issue synthentic events when it notices that it has missed a state transition. For example, if a container has exited and is not present at the next poll, the sensor will forge a container exit event and a container destroyed event.

This issue can be reduced by setting the event_reorder_window value to a longer duration (default is 25ms) in the capsule8-analytics.yaml config. The example below shows an event_reorder_window of 270ms, which will improve the ability of the analytics engine to appropriately enrich events with correct container data.


event_reorder_window: 270ms
Reordering & Performance

Increasing the reorder window will also have the effect of making response actions slower.