Upload support packages to Central

Learn how to upload new kernel module or eBPF program packages to Central.

StackRox Collector monitors runtime activity on each node in your secured clusters. To monitor the activities, Collector requires probes. These probes are kernel modules or eBPF programs specific to the Linux kernel version installed on the host. The Collector image contains a set of built-in probes. When you update the kernel version on your host, Collector automatically downloads a new probe for the updated kernel version from a StackRox-operated server on the internet if the required probe isn’t built in.

Collector checks for the new probes in the following order. It checks:

  1. The existing Collector image.
  2. The kernel support package (if you’ve uploaded one to Central).
  3. A StackRox-operated server available on the internet. (Collector uses Central’s network connection to check and download the probes).

If Collector doesn’t get new probes after checking, it reports a CrashLoopBackoff event.

If your network configuration restricts outbound traffic, you can manually download packages containing probes for all recent and supported Linux kernel versions and upload them to Central. Collectors then download these probes from Central, thus avoiding any outbound internet access.

Mutable image tags

Starting with the StackRox Kubernetes Security Platform version 2.5.32.0, Collector uses a mutable image tag (<version>-latest) so you get support for newer Linux kernel versions more easily. We don’t change code, preexisting kernel modules, or eBPF programs in image updates. We only add a single image layer with support for new kernel versions published after the initial release.

You can recognize mutable tags by looking at the suffix -latest appended to the base image version. Collector images are now tagged with <version>-latest. For example, the Collector version for the StackRox Kubernetes Security Platform version 2.5.32.0 is 2.5.6, and its full image reference is collector.stackrox.io/collector:2.5.6-latest.

To identify the Collector version you are using, run the following command:

Copy
kubectl -n stackrox get ds -owide
Copy
oc -n stackrox get ds -owide
  • If you push the Collector image into a private registry, you must regularly download the Collector image or configure registry mirroring to take advantage of this feature.

  • We strongly recommend using mutable tags for Collector. However, you can switch to immutable tags by removing the -latest suffix from the Collector image tag. For example, you can patch the Collector DaemonSet or edit the sensor.yaml file for your cluster to change 2.5.6-latest to 2.5.6.

    • If you switch to an immutable image tag, the Collector image may no longer support your kernel version out-of-the-box. To collect runtime activity in this case, the Collector DaemonSet must have access to the internet to download missing modules/probes after it’s running.

Download support packages

To view a list of available support packages, go to https://install.stackrox.io/collector/support-packages/index.html. The list categorizes support packages based on the StackRox Kubernetes Security Platform versions.

Upload support packages to Central

Before you upload support packages to Central:

  1. Generate an authentication token and create the following environment variables:
    Copy
    export ROX_API_TOKEN=<api-token>
    export ROX_CENTRAL_ADDRESS=<address>:<port-number>
  2. Run the following command to upload the support package:
    Copy
    roxctl -e "$ROX_CENTRAL_ADDRESS" collector support-packages upload <package file>
  • When you upload a new support package which includes content uploaded to Central previously, only new files are uploaded.
  • When you upload a new support package which includes files with the same name but different contents than those present on the Central, roxctl shows a warning message and doesn’t overwrite files.
  • You can use the --overwrite flag with the upload command to overwrite the files.
  • When you upload a support package that contains a required probe, Central doesn’t make any outbound requests (to the internet) for downloading this probe. Central uses the probe from the support package.

Questions?

We're happy to help! Reach out to us to discuss questions, issues, or feature requests.

© 2021 StackRox Inc. All rights reserved.