Sonobuoy Plugins

Table of Contents

• Sonobuoy Plugins
  • Overview
  • Plugin Definition
    • Writing your own plugin
      • The plugin definition file
      • Contract
  • Available Plugins

Overview

In addition to querying API objects, Sonobuoy also supports a plugin model. In this model, worker pods are dispatched into the cluster to collect data from each node, and use an aggregation URL to submit their results back to a waiting aggregation pod. See the diagram below:

Two main components specify plugin behavior:

1. Plugin Selection: A section in the main config (config.json) that declares which plugins to use in the Sonobuoy run. This can be generated or passed in with the --config flag to sonobuoy run or sonobuoy gen.

   These configs are defined by the end user.

2. Plugin Definition: A YAML document that defines metadata and a pod to produce a result.

   This YAML is defined by the plugin developer, and can be taken as a given by the end user.

Plugin Definition

• /etc/sonobuoy/plugins.d
• $HOME/.sonobuoy/plugins.d
• ./plugins.d

This search path can be overridden by the PluginSearchPath value of the Sonobuoy config.

Writing your own plugin

The plugin definition file

---
sonobuoy-config:
  driver: Job        # Job or DaemonSet. Job runs once per run, Daemonset runs on every node per run.
  plugin-name: e2e   # The name of the plugin
  result-type: e2e   # The name of the "result type." Usually the name of the plugin.
spec:                # A kubernetes container spec
  env:
  - name: E2E_FOCUS
    value: Pods should be submitted and removed
  image: gcr.io/heptio-images/kube-conformance:latest
  imagePullPolicy: Always
  name: e2e
  volumeMounts:
  - mountPath: /tmp/results
    name: results
    readOnly: false
  - mountPath: /var/log/test
    name: test-volume
extra-volumes:
- name: test-volume
  hostPath:
    # directory location on host
    path: /data

Contract

A definition file defines a container that runs the tests. This container can be anything you want, but must fulfil a contract.

After your container completes its work, it needs to signal to Sonobuoy that it’s done. This is done by writing out a filename to a results file. The default value is /tmp/results/done, which you can configure with the ResultsDir value in the Sonobuoy config.

Sonobuoy waits for the done file to be present, then transmits the indicated file back to the aggregator. The results file is opaque to Sonobuoy, and is made available in the Sonobuoy results tarball in its original form.

If you need additional mounts besides the default results mount that Sonobuoy always provides, you can define them in the extra-volumes field.

Available Plugins

The default Sonobuoy plugins are available in the examples/plugins.d directory in this repository. Here’s the current list: