promotion

Documentation

Index

• func ConfigToStruct[T any](c Config) (T, error)
• func IsTerminal(err error) bool
• type Config
  • func (c Config) DeepCopy() Config
  • func (c Config) ToJSON() []byte
• type MockStepRunner
  • func (m *MockStepRunner) Run(ctx context.Context, stepCtx *StepContext) (StepResult, error)
• type State
  • func (s *State) DeepCopy() State
  • func (s State) Get(key string) (any, bool)
  • func (s State) Set(key string, value any)
  • func (s State) ToJSON() []byte
• type StepContext
• type StepResult
• type StepRunner
• type StepRunnerCapabilities
• type StepRunnerCapability
• type StepRunnerMetadata
• type StepRunnerRegistration
• type TerminalError
  • func (e *TerminalError) Error() string

Functions

func ConfigToStruct

func ConfigToStruct[T any](c Config) (T, error)

ConfigToStruct converts a Config to a (typed) configuration struct.

func IsTerminal

func IsTerminal(err error) bool

IsTerminal returns true if the error is a terminal error or wraps one and false otherwise.

Types

type Config

type Config map[string]any

Config is an opaque map of configuration values for a Step. The keys and values are arbitrary and implementations of StepRunner are responsible for interpreting them.

func (Config) DeepCopy

func (c Config) DeepCopy() Config

DeepCopy returns a deep copy of the configuration.

func (Config) ToJSON

func (c Config) ToJSON() []byte

ToJSON marshals the configuration to JSON.

type MockStepRunner

type MockStepRunner struct {
	// RunFunc is the function that this MockStepRunner should call when Run is
	// called. If set, this function will be called instead of returning RunResult
	// and RunErr.
	RunFunc func(context.Context, *StepContext) (StepResult, error)
	// RunResult is the result that this MockStepRunner should return when Run is
	// called.
	RunResult StepResult
	// RunErr is the error that this MockStepRunner should return when Run is
	// called.
	RunErr error
}

MockStepRunner is a mock implementation of the StepRunner interface, which can be used for testing.

func (*MockStepRunner) Run

func (m *MockStepRunner) Run(
	ctx context.Context,
	stepCtx *StepContext,
) (StepResult, error)

Run implements the StepRunner interface.

type State

type State map[string]any

State is a type that represents state shared by Steps in a user-defined promotion process. It is not safe for concurrent use at present, as we expect Steps to be executed sequentially.

func (*State) DeepCopy

func (s *State) DeepCopy() State

DeepCopy returns a deep copy of the state.

func (State) Get

func (s State) Get(key string) (any, bool)

Get retrieves a value from the shared state.

func (State) Set

func (s State) Set(key string, value any)

Set stores a value in the shared state.

func (State) ToJSON

func (s State) ToJSON() []byte

ToJSON marshals the State to JSON.

type StepContext

type StepContext struct {
	// UIBaseURL may be used to construct deeper URLs for interacting with the
	// Kargo UI.
	UIBaseURL string
	// WorkDir is the root directory for the execution of a step.
	WorkDir string
	// SharedState is the state shared between steps.
	SharedState State
	// Alias is the alias of the step that is currently being executed.
	Alias string
	// Config is the configuration of the step that is currently being
	// executed.
	Config Config
	// Project is the Project that the Promotion is associated with.
	Project string
	// Stage is the Stage that the Promotion is targeting.
	Stage string
	// Promotion is the name of the Promotion.
	Promotion string
	// PromotionActor is the name of the actor triggering the Promotion.
	PromotionActor string
	// FreightRequests is the list of Freight from various origins that is
	// requested by the Stage targeted by the Promotion. This information is
	// sometimes useful to Step that reference a particular artifact and, in the
	// absence of any explicit information about the origin of that artifact, may
	// need to examine FreightRequests to determine whether there exists any
	// ambiguity as to its origin, which a user may then need to resolve.
	//
	// TODO: krancour: Longer term, if we can standardize the way that Steps
	// express the artifacts they need to work with, we can make the Engine
	// responsible for finding them and furnishing them directly to each
	// StepRunner.
	FreightRequests []kargoapi.FreightRequest
	// Freight is the collection of all Freight referenced by the Promotion. This
	// collection contains both the Freight that is actively being promoted as
	// well as any Freight that has been inherited from the target Stage's current
	// state.
	//
	// TODO: krancour: Longer term, if we can standardize the way that Steps
	// express the artifacts they need to work with, we can make the Engine
	// responsible for finding them and furnishing them directly to each
	// StepRunner.
	Freight kargoapi.FreightCollection
	// TargetFreightRef is the actual Freight that triggered this Promotion.
	TargetFreightRef kargoapi.FreightReference
}

StepContext is a type that represents the context in which a single promotion step is executed by a StepRunner.

type StepResult

type StepResult struct {
	// Status is the high-level outcome of a Step executed by a StepRunner.
	Status kargoapi.PromotionStepStatus
	// Message is an optional message that provides additional context about the
	// outcome of a Step executed by a StepRunner.
	Message string
	// Output is the opaque output of a Step executed by a StepRunner. The Engine
	// will update the shared state with this output, making it available to the
	// StepRunners executing subsequent Steps.
	Output map[string]any
	// HealthCheck identifies criteria for a health check process. This is
	// returned by some StepRunner upon successful execution of a Step. These
	// criteria can be used later as input to a health.Checker.
	HealthCheck *health.Criteria
}

StepResult represents the results of a single Step of a user-defined promotion process executed by a StepRunner.

type StepRunner

type StepRunner interface {
	// Run executes an individual Step from a user-defined promotion process using
	// the provided StepContext. Implementations may indirectly modify that
	// context through the returned StepResult to allow StepRunners for subsequent
	// Steps to access the results of this execution.
	Run(context.Context, *StepContext) (StepResult, error)
}

StepRunner is an interface for components that implement the logic for execution of an individual Step in a user-defined promotion process.

type StepRunnerCapabilities

type StepRunnerCapabilities struct {
	KargoClient  client.Client
	ArgoCDClient client.Client
	CredsDB      credentials.Database
}

StepRunnerCapabilities is a bundle of any special dependencies that may be injected into StepRunner implementations to grant them specific capabilities they may otherwise lack.

type StepRunnerCapability

type StepRunnerCapability string

StepRunnerCapability is a type representing special capabilities that may be required by a StepRunner in order to execute a step successfully. The engine executing a StepRunner is responsible for injecting corresponding dependencies into it when invoking its factory function.

const (
	// StepCapabilityAccessArgoCD represents the capability of interacting with
	// an Argo CD control plane via a Kubernetes client.
	StepCapabilityAccessArgoCD StepRunnerCapability = "access-argocd"
	// StepCapabilityAccessControlPlane represents the capability of interacting
	// with the Kargo control plane via a Kubernetes client.
	StepCapabilityAccessControlPlane StepRunnerCapability = "access-control-plane"
	// StepCapabilityAccessCredentials represents the capability to obtain
	// repository credentials through a lookup by credential type and repository
	// URL.
	StepCapabilityAccessCredentials StepRunnerCapability = "access-credentials"
	// StepCapabilityTaskOutputPropagation represents the capability of a step,
	// when executed as part of a task, to propagate its output directly to the
	// Promotion's shared state, in addition to the task's own state.
	StepCapabilityTaskOutputPropagation StepRunnerCapability = "task-output-propagation"
)

type StepRunnerMetadata

type StepRunnerMetadata struct {
	// DefaultTimeout is the default soft maximum interval in which a StepRunner
	// that returns a Running status (which typically indicates it's waiting for
	// something to happen) may be retried.
	//
	// The maximum is a soft one because the check for whether the interval has
	// elapsed occurs AFTER the step has run. This effectively means a step may
	// run ONCE beyond the close of the interval.
	//
	// A value of 0 will cause the step to be retried indefinitely unless the
	// ErrorThreshold is reached.
	//
	// This default can be overridden by step-level configuration.
	DefaultTimeout time.Duration
	// DefaultErrorThreshold is the number of consecutive times the step must fail
	// (for any reason) before retries are abandoned and the entire Promotion is
	// marked as failed.
	//
	// If this field is set to a non-positive value, it will be changed to the
	// system-wide default of 1 at registration time.
	//
	// A value of 1 will cause the Promotion to be marked as failed after just
	// a single failure; i.e. no retries will be attempted.
	//
	// This default can be overridden by step-level configuration.
	DefaultErrorThreshold uint32
	// RequiredCapabilities is a list of constants representing special
	// capabilities required by the StepRunner in order to execute a step
	// successfully. The engine executing the StepRunner is responsible for
	// injecting necessary dependencies into the StepRunner when invoking its
	// factory function. By default, StepRunners are not granted any special
	// capabilities.
	RequiredCapabilities []StepRunnerCapability
}

StepRunnerMetadata contains metadata about a StepRunner.

type StepRunnerRegistration

type StepRunnerRegistration struct {
	// Metadata is metadata about StepRunners for the kind of step specified by
	// StepKind.
	Metadata StepRunnerMetadata
	// Factory is a function for instantiating a StepRunner capable of executing
	// the kind of step specified by StepKind.
	Factory func(StepRunnerCapabilities) StepRunner
}

StepRunnerRegistration associates a kind of promotion step with optional metadata and a factory function for instantiating a StepRunner capable of executing that kind of step.

type TerminalError

type TerminalError struct {
	Err error
}

TerminalError wraps another error to indicate to the step execution engine that the step that produced the error should not be retried.

func (*TerminalError) Error

func (e *TerminalError) Error() string

Error implements the error interface.