sidecar

Documentation

Overview

Package sidecar is a library that knows how to report on the output of a process that writes its output and exit code to disk

Index

• Constants
• func Encode(options Options) (string, error)
• func LogSetup() (*os.File, error)
• type CensoringOptions
• type Options
  • func NewOptions() *Options
  • func (o *Options) AddFlags(flags *flag.FlagSet)
  • func (o *Options) Complete(args []string)
  • func (o *Options) ConfigVar() string
  • func (o *Options) LoadConfig(config string) error
  • func (o Options) Run(ctx context.Context, logFile *os.File) (int, error)
  • func (o *Options) Validate() error

Constants

const (
	// JSONConfigEnvVar is the environment variable that
	// utilities expect to find a full JSON configuration
	// in when run.
	JSONConfigEnvVar = "SIDECAR_OPTIONS"
)

const LogFileName = "sidecar-logs.json"

Functions

func Encode

func Encode(options Options) (string, error)

Encode will encode the set of options in the format that is expected for the configuration environment variable

func LogSetup

func LogSetup() (*os.File, error)

Types

type CensoringOptions

type CensoringOptions struct {
	// SecretDirectories are paths to directories containing secret data. The contents
	// of these secret data files will be censored from the logs and artifacts uploaded
	// to the cloud.
	SecretDirectories []string `json:"secret_directories,omitempty"`
	// CensoringConcurrency is the maximum number of goroutines that should be censoring
	// artifacts and logs at any time. If unset, defaults to 10.
	CensoringConcurrency *int64 `json:"censoring_concurrency,omitempty"`
	// CensoringBufferSize is the size in bytes of the buffer allocated for every file
	// being censored. We want to keep as little of the file in memory as possible in
	// order for censoring to be reasonably performant in space. However, to guarantee
	// that we censor every instance of every secret, our buffer size must be at least
	// two times larger than the largest secret we are about to censor. While that size
	// is the smallest possible buffer we could use, if the secrets being censored are
	// small, censoring will not be performant as the number of I/O actions per file
	// would increase. If unset, defaults to 10MiB.
	CensoringBufferSize *int `json:"censoring_buffer_size,omitempty"`

	// IncludeDirectories are directories which should have their content censored, provided
	// as relative path globs from the base of the artifact directory for the test. If
	// present, only content in these directories will be censored. Entries in this list
	// are parsed with the go-zglob library, allowing for globbed matches.
	IncludeDirectories []string `json:"include_directories,omitempty"`

	// ExcludeDirectories are directories which should not have their content censored,
	// provided as relative path globs from the base of the artifact directory for the
	// test. If present, content in these directories will not be censored even if the
	// directory also matches a glob in IncludeDirectories. Entries in this list are
	// parsed with the go-zglob library, allowing for globbed matches.
	ExcludeDirectories []string `json:"exclude_directories,omitempty"`

	// IniFilenames are secret filenames that should be parsed as INI files in order to
	// censor the values in the key-value mapping as well as the full content of the file.
	IniFilenames []string `json:"ini_filenames,omitempty"`
}

type Options

type Options struct {
	GcsOptions               *gcsupload.Options `json:"gcs_options"`
	DeprecatedWrapperOptions *wrapper.Options   `json:"wrapper_options,omitempty"` // TODO(fejta): remove july 2019
	// Additional entries to wait for if set
	Entries []wrapper.Options `json:"entries,omitempty"`

	// EntryError requires all entries to pass in order to exit cleanly.
	EntryError bool `json:"entry_error,omitempty"`

	// IgnoreInterrupts instructs the waiting process to ignore interrupt
	// signals. An interrupt signal is sent to this process when the kubelet
	// decides to delete the test Pod. This may be as a result of:
	//  - the ProwJob exceeding the `default_job_timeout` as configured for Prow
	//  - the ProwJob exceeding the `timeout` as configured for the job itself
	//  - the Pod exceeding the `pod_running_timeout` as configured for Prow
	//  - cluster instability causing the Pod to be evicted
	//
	// When this happens, the `entrypoint` process also gets the signal, and
	// forwards it to the process under test. `entrypoint` will wait for the
	// test process to exit, either configured with:
	//  - `grace_period` in the default decoration configurations for Prow
	//  - `grace_period` in the job's specific configuration
	// After the grace period, `entrypoint` will forcefully terminate the test
	// process and signal to `sidecar` that the process has exited.
	//
	// In parallel, the kubelet will be waiting on the Pod's `terminationGracePeriod`
	// after sending the interrupt signal, at which point the kubelet will forcefully
	// terminate all containers in the Pod.
	//
	// If `ignore_interrupts` is set, `sidecar` will do nothing upon receipt of
	// the interrupt signal; this implicitly means that upload of logs and artifacts
	// will begin when the test process exits, which may be as long as the grace
	// period if the test process does not gracefully handle interrupts. This will
	// require that the user configures the Pod's termination grace period to be
	// longer than the `entrypoint` grace period for the test process and the time
	// taken by `sidecar` to upload all relevant artifacts.
	IgnoreInterrupts bool `json:"ignore_interrupts,omitempty"`

	// WriteMemoryProfile makes the program write a memory profile periodically while
	// it runs. Use the sigs.k8s.io/prow/hack/analyze-memory-profiles.py script to
	// load the data into time series and plot it for analysis.
	WriteMemoryProfile bool `json:"write_memory_profile,omitempty"`

	// CensoringOptions are options that pertain to censoring output before upload.
	CensoringOptions *CensoringOptions `json:"censoring_options,omitempty"`

	// SecretDirectories is deprecated, use censoring_options.secret_directories instead.
	SecretDirectories []string `json:"secret_directories,omitempty"`
	// CensoringConcurrency is deprecated, use censoring_options.censoring_concurrency instead.
	CensoringConcurrency *int64 `json:"censoring_concurrency,omitempty"`
	// CensoringBufferSize is deprecated, use censoring_options.censoring_buffer_size instead.
	CensoringBufferSize *int `json:"censoring_buffer_size,omitempty"`
}

Options exposes the configuration necessary for defining the process being watched and where in GCS an upload will land.

func NewOptions

func NewOptions() *Options

NewOptions returns an empty Options with no nil fields

func (*Options) AddFlags

func (o *Options) AddFlags(flags *flag.FlagSet)

AddFlags binds flags to options

func (*Options) Complete

func (o *Options) Complete(args []string)

Complete internalizes command line arguments

func (*Options) ConfigVar

func (o *Options) ConfigVar() string

ConfigVar exposese the environment variable used to store serialized configuration

func (*Options) LoadConfig

func (o *Options) LoadConfig(config string) error

LoadConfig loads options from serialized config

func (Options) Run

func (o Options) Run(ctx context.Context, logFile *os.File) (int, error)

Run will watch for the process being wrapped to exit and then post the status of that process and any artifacts to cloud storage.

func (*Options) Validate

func (o *Options) Validate() error

Validate ensures that the set of options are self-consistent and valid