Sonobuoy Documentation

Sonobuoy uses two types of plugins to execute tasks in a cluster:

• Job plugins: Designed to run once. Sonobuoy creates a single pod for these. The Kubernetes end-to-end (e2e) plugin is a job-type plugin.
• Daemonset plugins: Designed to run on every node in the cluster, including control-plane nodes. The systemd-logs gatherer is a daemonset-type plugin.

The sonobuoy plugin command serves as the base command for managing installed plugins. It allows you to perform operations such as installing, listing, showing definitions, and uninstalling plugins.

Note that sonobuoy plugin is a parent command; specific actions are performed using subcommands like install, list, show, and uninstall.

The Reliability Scanner plugin assesses cluster reliability using several key concepts:

• Probes: Checks for the presence of livenessProbe and readinessProbe on containers to ensure Kubernetes can manage Pod health and traffic correctly.
• Owner Annotations: Validates that Services have the appropriate user-provided annotations and allowed domains to support incident management and multi-tenancy.
• Quality of Service (QoS): Verifies that Pods meet a minimum desired QoS class (BestEffort, Burstable, or Guaranteed) to ensure predictable resource scheduling and eviction behavior.

Sonobuoy is a diagnostic tool used to understand the state of a Kubernetes cluster by running upstream Kubernetes tests. It consists of three main components:

1. Command-line utility: Used to trigger conformance tests, check status, view activity logs, and retrieve/analyze test results.
2. Aggregator: Runs in a Kubernetes pod to start plugins and aggregate their test results.
3. Plugins: Execute in ephemeral namespaces with a Sonobuoy sidecar to run specific tests or conformance frameworks.

The Sonobuoy website is built using Hugo. To build and serve the site locally for development or previewing, ensure Hugo is installed and run the Hugo server command with the --disableFastRender flag. The site will be available at http://localhost:1313.

hugo server --disableFastRender

Some E2E plugin tests require SSH access to cluster nodes. To enable this, provide the following flags during sonobuoy run:

• --ssh-key yamlFile: Path to the private key enabling SSH to cluster nodes.
• --ssh-user envModifier: The SSH user associated with the provided key.

You can install Sonobuoy by downloading the binary or using Homebrew on macOS.

Binary Installation:

1. Download the latest release for your platform.
2. Extract the tarball:

   tar -xvf <RELEASE_TARBALL_NAME>.tar.gz

3. Move the sonobuoy executable to a directory on your PATH.

Homebrew (macOS):

brew install sonobuoy

You can control which Kubernetes end-to-end tests are executed by using regular expressions to include (E2E_FOCUS) or exclude (E2E_SKIP) specific tests. The E2E_FOCUS value is applied first, and E2E_SKIP further restricts that list.

You can set these using dedicated Sonobuoy flags or via the general --plugin-env flag.

Use the sonobuoy gen plugin command to generate the YAML required for a plugin definition. To ensure you have the correct base configuration, use the --show-default-podspec flag to include the default Kubernetes PodSpec used by Sonobuoy.

Note: Always provide the --type flag (e.g., for Job or DaemonSet) when generating to ensure you receive the appropriate default podSpec.

# Generate a plugin definition with default PodSpec
sonobuoy gen plugin --show-default-podspec -n my-plugin -i my-plugin:latest

# Run your custom plugin
sonobuoy run --plugin myPlugin.yaml

Sonobuoy allows you to customize the Kubernetes PodSpec used when creating Pods or DaemonSets for your plug-ins. By adding a podSpec object to your plug-in definition, you can configure settings such as additional containers, volumes, security contexts, or host namespaces (hostPID, hostNetwork, hostIPC).

Sonobuoy will merge your custom podSpec with the necessary resources it requires (like the Sonobuoy worker container) without removing or changing your existing configurations.

To test your E2E_FOCUS and E2E_SKIP logic without actually executing the test code, run Sonobuoy with the E2E_DRYRUN environment variable set to true. In this mode, the run will execute and report all selected tests as passing, allowing you to fine-tune selection without wasting time on actual execution.

sonobuoy run \
  --plugin-env e2e.E2E_FOCUS=pods \
  --plugin-env e2e.E2E_DRYRUN=true