payload

Documentation

Index

• Constants
• func ByNumberAndComponent(tasks []*Task) [][]*TaskNode
• func FlattenByNumberAndComponent(tasks []*Task) [][]*TaskNode
• func ImageForShortName(name string) (string, error)
• func Render(outputDir, releaseImage string) error
• func RunGraph(ctx context.Context, graph *TaskGraph, maxParallelism int, ...) []error
• func SplitOnJobs(task *Task) bool
• func SummaryForReason(reason, name string) string
• func ValidateDirectory(dir string) error
• type BreakFunc
  • func PermuteOrder(breakFn BreakFunc, r *rand.Rand) BreakFunc
  • func ShiftOrder(breakFn BreakFunc, step, stride int) BreakFunc
• type ResourceBuilder
• type State
  • func (s State) Initializing() bool
  • func (s State) Reconciling() bool
  • func (s State) String() string
• type Task
  • func (st *Task) Copy() *Task
  • func (st *Task) Run(ctx context.Context, version string, builder ResourceBuilder, state State) error
  • func (st *Task) String() string
• type TaskGraph
  • func NewTaskGraph(tasks []*Task) *TaskGraph
  • func (g *TaskGraph) Parallelize(breakFn BreakFunc)
  • func (g *TaskGraph) Roots() []int
  • func (g *TaskGraph) Split(onFn func(task *Task) bool)
  • func (g *TaskGraph) Tree() string
• type TaskNode
  • func (n TaskNode) String() string
• type Update
  • func LoadUpdate(dir, releaseImage string) (*Update, error)
• type UpdateError
  • func (e *UpdateError) Cause() error
  • func (e *UpdateError) Error() string

Constants

const (
	DefaultPayloadDir = "/"

	CVOManifestDir     = "manifests"
	ReleaseManifestDir = "release-manifests"
)

Functions

func ByNumberAndComponent

func ByNumberAndComponent(tasks []*Task) [][]*TaskNode

ByNumberAndComponent creates parallelization for tasks whose original filenames are of the form 0000_NN_NAME_* - files that share 0000_NN_NAME_ are run in serial, but chunks of files that have the same 0000_NN but different NAME can be run in parallel. If the input is not sorted in an order such that 0000_NN_NAME elements are next to each other, the splitter will treat those as unsplittable elements.

func FlattenByNumberAndComponent

func FlattenByNumberAndComponent(tasks []*Task) [][]*TaskNode

FlattenByNumberAndComponent creates parallelization for tasks whose original filenames are of the form 0000_NN_NAME_* - files that share 0000_NN_NAME_ are run in serial, but chunks of files that have different 0000_NN_NAME can be run in parallel. This splitter does *not* preserve ordering within run levels and is intended only for use cases where order is not important.

func ImageForShortName

func ImageForShortName(name string) (string, error)

ImageForShortName returns the image using the updatepayload embedded in the Operator.

func Render

func Render(outputDir, releaseImage string) error

Render renders all the manifests from /manifests to outputDir.

func RunGraph

func RunGraph(ctx context.Context, graph *TaskGraph, maxParallelism int, fn func(ctx context.Context, tasks []*Task) error) []error

RunGraph executes the provided graph in order and in parallel up to maxParallelism. It will not start a new TaskNode until all of the prerequisites have completed. If fn returns an error, no dependencies of that node will be executed, but other indepedent edges will continue executing.

func SplitOnJobs

func SplitOnJobs(task *Task) bool

SplitOnJobs enforces the rule that any Job in the payload prevents reordering or parallelism (either before or after)

func SummaryForReason

func SummaryForReason(reason, name string) string

func ValidateDirectory

func ValidateDirectory(dir string) error

ValidateDirectory checks if a directory can be a candidate update by looking for known files. It returns an error if the directory cannot be an update.

Types

type BreakFunc

type BreakFunc func([]*Task) [][]*TaskNode

BreakFunc returns the input tasks in order of dependencies with explicit parallelizm allowed per task in an array of task nodes.

func PermuteOrder

func PermuteOrder(breakFn BreakFunc, r *rand.Rand) BreakFunc

PermuteOrder returns a split function that ensures the order of each step is shuffled based on r.

func ShiftOrder

func ShiftOrder(breakFn BreakFunc, step, stride int) BreakFunc

ShiftOrder rotates each TaskNode by step*len/stride when stride > len, or by step when stride < len, to ensure a different order within the task node list is tried.

type ResourceBuilder

type ResourceBuilder interface {
	Apply(context.Context, *lib.Manifest, State) error
}

ResourceBuilder abstracts how a manifest is created on the server. Introduced for testing.

type State

type State int

State describes the state of the payload and alters how a payload is applied.

const (
	// UpdatingPayload indicates we are moving from one state to
	// another.
	//
	// When we are moving to a different payload version, we want to
	// be as conservative as possible about ordering of the payload
	// and the errors we might encounter. An error in one operator
	// should prevent dependent operators from changing. We are
	// willing to take longer to roll out an update if it reduces
	// the possibility of error.
	UpdatingPayload State = iota
	// ReconcilingPayload indicates we are attempting to maintain
	// our current state.
	//
	// When the payload has already been applied to the cluster, we
	// prioritize ensuring resources are recreated and don't need to
	// progress in strict order. We also attempt to reset as many
	// resources as possible back to their desired state and report
	// errors after the fact.
	ReconcilingPayload
	// InitializingPayload indicates we are establishing our first
	// state.
	//
	// When we are deploying a payload for the first time we want
	// to make progress quickly but in a predictable order to
	// minimize retries and crash-loops. We wait for operators
	// to report level but tolerate degraded and transient errors.
	// Our goal is to get the entire payload created, even if some
	// operators are still converging.
	InitializingPayload
)

func (State) Initializing

func (s State) Initializing() bool

Initializing is true if the state is InitializingPayload.

func (State) Reconciling

func (s State) Reconciling() bool

Reconciling is true if the state is ReconcilingPayload.

func (State) String

func (s State) String() string

type Task

type Task struct {
	Index    int
	Total    int
	Manifest *lib.Manifest
	Requeued int
	Backoff  wait.Backoff
}

func (*Task) Copy

func (st *Task) Copy() *Task

func (*Task) Run

func (st *Task) Run(ctx context.Context, version string, builder ResourceBuilder, state State) error

Run attempts to create the provided object until it succeeds or context is cancelled. It returns the last error if context is cancelled.

func (*Task) String

func (st *Task) String() string

type TaskGraph

type TaskGraph struct {
	Nodes []*TaskNode
}

TaskGraph provides methods for parallelizing a linear sequence of Tasks based on Split or Parallelize functions.

func NewTaskGraph

func NewTaskGraph(tasks []*Task) *TaskGraph

NewTaskGraph creates a graph with a single node containing the supplied tasks.

func (*TaskGraph) Parallelize

func (g *TaskGraph) Parallelize(breakFn BreakFunc)

Parallelize takes the given breakFn and splits any TaskNode's tasks up into parallel groups. If breakFn returns an empty array or a single array item with a single task node, that is considered a no-op.

func (*TaskGraph) Roots

func (g *TaskGraph) Roots() []int

func (*TaskGraph) Split

func (g *TaskGraph) Split(onFn func(task *Task) bool)

Split breaks a graph node with a task that onFn returns true into one, two, or three separate nodes, preserving the order of tasks. E.g. a node with [a,b,c,d] where onFn returns true of b will result in a graph with [a] -> [b] -> [c,d].

func (*TaskGraph) Tree

func (g *TaskGraph) Tree() string

Tree renders the task graph in Graphviz DOT.

type TaskNode

type TaskNode struct {
	In    []int
	Tasks []*Task
	Out   []int
}

func (TaskNode) String

func (n TaskNode) String() string

type Update

type Update struct {
	ReleaseImage   string
	ReleaseVersion string

	VerifiedImage bool
	LoadedAt      time.Time

	ImageRef *imagev1.ImageStream

	// manifestHash is a hash of the manifests included in this payload
	ManifestHash string
	Manifests    []lib.Manifest
}

func LoadUpdate

func LoadUpdate(dir, releaseImage string) (*Update, error)

type UpdateError

type UpdateError struct {
	Nested  error
	Reason  string
	Message string
	Name    string

	Task *Task
}

UpdateError is a wrapper for errors that occur during a payload sync.

func (*UpdateError) Cause

func (e *UpdateError) Cause() error

func (*UpdateError) Error

func (e *UpdateError) Error() string