Installing the Sensor on CRI-O and Containerd

Configuration

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

There are three CRI-specific configuration values:

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:

crisensor:
    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:

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:

env:
 - name: GRPC_GO_REQUIRE_HANDSHAKE
   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.

Caveats

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.

/etc/capsule8/capsule8-analytics.yaml

event_reorder_window: 270ms