Installing the Sensor on Kubernetes

Prerequisites

In order to use this guide you will need to have kubectl installed and a Google Cloud Platform service account key file which will be provided to you by Capsule8. Save the key file locally to ~/.capsule8/service-account.json and make a note of the email address in the file. You will also receive a Kubernetes manifest from Capsule8 containing a ConfigMap and a DaemonSet for the Capsule8 Sensor and along with the associated Capsule8 Analytics config file.

Installation

1. Initial Setup Verification

Before starting, verify that kubectl is configured to point to your target installation cluster:

$ kubectl config current-context

If you do not already have a test cluster already Capsule8 recommends using eksctl to spin up an EKS cluster which can be as simple as running the following command: $ eksctl create cluster

For more information on eksctl, see the official AWS documentation.

2. Create Kubernetes Secret

Set an environment variable in the terminal that you plan on using:

$ export CAPSULE8_SERVICE_ACCOUNT_EMAIL=${SERVICE_ACCOUNT_EMAIL}

Replace ${SERVICE_ACCOUNT_EMAIL} with the email from your service account key file before running the following kubectl command to create a new Kubernetes Secret. This secret will be used to authenticate your kubelet so that it can pull from our private container registry.

$ kubectl create secret docker-registry capsule8-registry-secret  \
  --docker-username=_json_key                                     \
  --docker-server=https://us.gcr.io                               \
  --docker-email=$CAPSULE8_SERVICE_ACCOUNT_EMAIL                  \
  --docker-password="$(cat ~/.capsule8/service-account.json)"
$ kubectl get secrets

You should now see your new Secret. This secret will be used to authenticate your kubelet so that it can pull from our private container registry although other registries can be used.

3. Apply the Manifest

Download a copy of the manifest provided by Capsule8 and apply it:

$ kubectl apply -f https://capsule8-assets.s3.amazonaws.com/latest/capsule8-sensor-manifest.yaml
$ kubectl get pods -l app=capsule8-sensor

The manifest should create a capsule8-sensor DaemonSet and capsule8-sensor-config ConfigMap.

You should now see Capsule8 Sensor pods starting up. If you do not see them be sure to check your cluster’s pod security policy and, if necessary, grant exceptions for the capabilities required by the sensor. For a full list of these capabilities, please see the DaemonSet or reach out to Capsule8.

4. Generate an Alert

The logs for the sensor pods should list all the configured policies:

$ kubectl logs $SENSOR_POD_NAME

To generate a quick test alert, exec into one of the sensor pods:

$ kubectl exec -it $SENSOR_POD_NAME -- /bin/sh

Starting an interactive shell not spawned by sshd or screen violates the interactiveShell policy, which will trigger an alert. Currently, the sensor is configured to print alerts out to standard out, which can be seen if you view the logs from the pod that generated the alert:

$ kubectl logs $SENSOR_POD_NAME

Alerts can also be sent out to webhooks, written directly to cloud blob storage buckets, written to local files on the file system with log rotation, and sent to syslog. See the Alert Dispatcher Guide for documentation on the various other ways the sensor can send alerts.