plugin

README

Sonobuoy Plugins

See the plugin reference.

Documentation

Index

• Constants
• type AggregationConfig
• type Definition
• type ExpectedResult
  • func (er *ExpectedResult) ID() string
• type Interface
• type ProgressUpdate
  • func CombineUpdates(p1, p2 ProgressUpdate) ProgressUpdate
  • func (s *ProgressUpdate) FormatPluginProgress() (output string)
  • func (p *ProgressUpdate) IsAppending() bool
  • func (p *ProgressUpdate) IsEmpty() bool
  • func (s ProgressUpdate) Key() string
• type Result
  • func (r *Result) IsSuccess() bool
  • func (r *Result) IsTimeout() bool
  • func (r *Result) Key() string
  • func (r *Result) Path() string
• type Selection
• type WorkerConfig

Constants

const (
	// GracefulShutdownPeriod is how long plugins have to cleanly finish before they are terminated.
	GracefulShutdownPeriod = 60

	// ResultsDir is the directory where results will be available in Sonobuoy plugin containers.
	ResultsDir = "/tmp/sonobuoy/results"

	// TimeoutErrMsg is the message used when Sonobuoy experiences a timeout while waiting for results.
	TimeoutErrMsg = "" /* 151-byte string literal not displayed */
)

const (
	// GlobalResult is used in place of a node name when the results apply
	// to the entire cluster as opposed to a single node (e.g. when running
	// a job and not a daemonset).
	GlobalResult = "global"
)

Types

type AggregationConfig

type AggregationConfig struct {
	BindAddress      string `json:"bindaddress"`
	BindPort         int    `json:"bindport"`
	AdvertiseAddress string `json:"advertiseaddress"`
	TimeoutSeconds   int    `json:"timeoutseconds"`
}

AggregationConfig are the config settings for the server that aggregates plugin results

type Definition

type Definition struct {
	Name         string
	ResultType   string
	Spec         manifest.Container
	ExtraVolumes []manifest.Volume
}

Definition defines a plugin's features, method of launch, and other metadata about it.

type ExpectedResult

type ExpectedResult struct {
	NodeName   string
	ResultType string
	Order      int
}

ExpectedResult is an expected result that a plugin will submit. This is so the aggregation server can know when it all results have been received.

func (*ExpectedResult) ID

func (er *ExpectedResult) ID() string

ID returns a unique identifier for this expected result to distinguish it from the rest of the results that may be seen by the aggregation server.

type Interface

type Interface interface {
	// Run runs a plugin, declaring all resources it needs, and then
	// returns.  It does not block and wait until the plugin has finished.
	Run(kubeClient kubernetes.Interface, hostname string, cert *tls.Certificate, ownerPod *v1.Pod, progressPort, resultDir string) error

	// Cleanup cleans up all resources created by the plugin
	Cleanup(kubeClient kubernetes.Interface)

	// Monitor continually checks for problems in the resources created by a
	// plugin (either because it won't schedule, or the image won't
	// download, too many failed executions, etc) and sends the errors as
	// Result objects through the provided channel. It should return once the context
	// is cancelled.
	Monitor(ctx context.Context, kubeClient kubernetes.Interface, availableNodes []v1.Node, resultsCh chan<- *Result)

	// ExpectedResults is an array of Result objects that a plugin should
	// expect to submit.
	ExpectedResults(nodes []v1.Node) []ExpectedResult

	// GetName returns the name of this plugin
	GetName() string

	// SkipCleanup returns whether cleanup for this plugin should be skipped or not.
	SkipCleanup() bool

	// GetResultFormat states the type of results this plugin generates and facilates post-processing
	// those results.
	GetResultFormat() string

	// GetResultFiles returns the specific files to target for post-processing. If empty, each
	// result format specifies its own heuristic for determining those files.
	GetResultFiles() []string

	// GetDescription returns the human-readable description of the plugin.
	GetDescription() string

	// GetSourceURL returns the URL where the plugin came from and where updates to it will be located.
	GetSourceURL() string

	// GetOrder returns the order in which the plugin is run. Plugins will wait until all other plugins with lower order are done before being launched.
	GetOrder() int
}

Interface represents what all plugins must implement to be run and have results be aggregated.

type ProgressUpdate

type ProgressUpdate struct {
	PluginName string    `json:"name"`
	Node       string    `json:"node"`
	Timestamp  time.Time `json:"timestamp"`

	Message string `json:"msg"`

	Total     int64 `json:"total"`
	Completed int64 `json:"completed"`

	Errors   []string `json:"errors,omitempty"`
	Failures []string `json:"failures,omitempty"`

	AppendTotals    bool     `json:"appendtotals,omitempty"`
	AppendCompleted int64    `json:"appendcompleted,omitempty"`
	AppendFailing   []string `json:"appendfailing,omitempty"`
}

ProgressUpdate is the structure that the Sonobuoy worker sends to the aggregator to inform it of plugin progress. More TBD.

func CombineUpdates

func CombineUpdates(p1, p2 ProgressUpdate) ProgressUpdate

CombineUpdates applies a second progress update onto the first. Latest message node and plugin name are always used.

func (*ProgressUpdate) FormatPluginProgress

func (s *ProgressUpdate) FormatPluginProgress() (output string)

FormatPluginProgress returns a string that represents the current progress The string can then be used for printing updates. The format of the output is the following: Passed:S, Failed: F, Remaining: R Where S, F and R are numbers, Corresponding to S = ProgressUpdate.Completed, F = len(ProgressUpdate.Failures), and ProgressUpdate.Total - S - F respectively and the ", Remaining: R" part is printed only if R is not negative

func (*ProgressUpdate) IsAppending

func (p *ProgressUpdate) IsAppending() bool

func (*ProgressUpdate) IsEmpty

func (p *ProgressUpdate) IsEmpty() bool

func (ProgressUpdate) Key

func (s ProgressUpdate) Key() string

Key returns a unique identifier for this ProgressUpdate to match it up against an known plugins running.

type Result

type Result struct {
	NodeName   string
	ResultType string
	MimeType   string
	Filename   string
	Body       io.Reader
	Error      string
}

Result represents a result we got from a dispatched plugin, returned to the aggregation server over HTTP. Errors running a plugin are also considered a Result, if they have an Error property set.

func (*Result) IsSuccess

func (r *Result) IsSuccess() bool

IsSuccess returns whether the Result represents a successful plugin result, versus one that was unsuccessful (for instance, from a dispatched plugin not being able to launch.)

func (*Result) IsTimeout

func (r *Result) IsTimeout() bool

IsTimeout returns whether or not the Result represents the error case when Sonobuoy experiences a timeout waiting for results.

func (*Result) Key

func (r *Result) Key() string

Key returns a unique identifier for this result to match it up against an expected result.

func (*Result) Path

func (r *Result) Path() string

Path is the path within the "plugins" section of the results tarball where this Result should be stored, not including a file extension.

type Selection

type Selection struct {
	Name string `json:"name"`
}

Selection is the user specified input to load and initialize plugins

type WorkerConfig

type WorkerConfig struct {
	// AggregatorURL is the URL we talk to the aggregator pod on for submitting results
	AggregatorURL string `json:"aggregatorurl,omitempty" mapstructure:"aggregatorurl"`

	// NodeName is the node name we should call ourselves when sending results
	NodeName string `json:"nodename,omitempty" mapstructure:"nodename"`

	// ResultsDir is the directory that's expected to contain the host's root filesystem
	ResultsDir string `json:"resultsdir,omitempty" mapstructure:"resultsdir"`

	// ResultType is the type of result (to be put in the HTTP URL's path) to be
	// sent back to sonobuoy.
	ResultType string `json:"resulttype,omitempty" mapstructure:"resulttype"`

	// ProgressUpdatesPort is the port on which the Sonobuoy worker will listen for progress
	// updates from the plugin.
	ProgressUpdatesPort string `json:"progressport"  mapstructure:"progressport"`

	CACert     string `json:"cacert,omitempty" mapstructure:"cacert"`
	ClientCert string `json:"clientcert,omitempty" mapstructure:"clientcert"`
	ClientKey  string `json:"clientkey,omitempty" mapstructure:"clientkey"`
}

WorkerConfig is the file given to the sonobuoy worker to configure it to phone home.