operation

Documentation

Index

• Variables
• type Callbacks
• type CommandArgs
• type CommandResponseFunc
• type Executor
  • func NewExecutor(stateFilePath string, getInstallCharm func() (*corecharm.URL, error)) (Executor, error)
• type Factory
  • func NewFactory(deployer charm.Deployer, runnerFactory runner.Factory, callbacks Callbacks, ...) Factory
• type Kind
• type Operation
• type State
  • func (st State) CollectedMetricsAt() time.Time
• type StateFile
  • func NewStateFile(path string) *StateFile
  • func (f *StateFile) Read() (*State, error)
  • func (f *StateFile) Write(st *State) error
• type Step

Variables

var (
	ErrNoStateFile = errors.New("uniter state file does not exist")
	ErrSkipExecute = errors.New("operation already executed")
	ErrNeedsReboot = errors.New("reboot request issued")
	ErrHookFailed  = errors.New("hook failed")
)

Types

type Callbacks

type Callbacks interface {

	// AcquireExecutionLock acquires the machine-level execution lock, and
	// returns a func that must be called to unlock it. It's used by all the
	// operations that execute external code.
	AcquireExecutionLock(message string) (unlock func(), err error)

	// PrepareHook and CommitHook exist so that we can defer worrying about how
	// to untangle Uniter.relationers from everything else. They're only used by
	// RunHook operations.
	PrepareHook(info hook.Info) (name string, err error)
	CommitHook(info hook.Info) error

	// UpdateRelations exists so that we can encapsulate it in an operation.
	UpdateRelations(ids []int) error

	// NotifyHook* exist so that we can defer worrying about how to untangle the
	// callbacks inserted for uniter_test. They're only used by RunHook operations.
	NotifyHookCompleted(string, runner.Context)
	NotifyHookFailed(string, runner.Context)

	// InitializeMetricsCollector ensures that the collect-metrics hook timer is
	// up to date given the current deployed charm. It's only used in deploy
	// operations.
	InitializeMetricsCollector() error

	// FailAction marks the supplied action failed. It's only used by
	// RunActions operations.
	FailAction(actionId, message string) error

	// GetArchiveInfo is used to find out how to download a charm archive. It's
	// only used by Deploy operations.
	GetArchiveInfo(charmURL *corecharm.URL) (charm.BundleInfo, error)

	// SetCurrentCharm records intent to deploy a given charm. It must be called
	// *before* recording local state referencing that charm, to ensure there's
	// no path by which the state server can legitimately garbage collect that
	// charm or the service's settings for it. It's only used by Deploy operations.
	SetCurrentCharm(charmURL *corecharm.URL) error

	// ClearResolvedFlag notifies the state server that the uniter has accepted
	// the resolved attempt and is trying to progress. It's only used by Resolved
	// operations (which we generally expect to wrap other operations).
	ClearResolvedFlag() error
}

Callbacks exposes all the uniter code that's required by the various operations. It's far from cohesive, and fundamentally represents inappropriate coupling, so it's a prime candidate for future refactoring.

type CommandArgs

type CommandArgs struct {
	// Commands is the arbitrary commands to execute on the unit
	Commands string
	// RelationId is the relation context to execute the commands in.
	RelationId int
	// RemoteUnitName is the remote unit for the relation context.
	RemoteUnitName string
	// ForceRemoteUnit skips unit inference and existence validation.
	ForceRemoteUnit bool
}

CommandArgs stores the arguments for a Command operation.

type CommandResponseFunc

type CommandResponseFunc func(*utilexec.ExecResponse, error)

CommandResponseFunc is for marshalling command responses back to the source of the original request.

type Executor

type Executor interface {

	// State returns a copy of the executor's current operation state.
	State() State

	// Run will Prepare, Execute, and Commit the supplied operation, writing
	// indicated state changes between steps. If any step returns an unknown
	// error, the run will be aborted and an error will be returned.
	Run(Operation) error

	// Skip will Commit the supplied operation, and write any state change
	// indicated. If Commit returns an error, so will Skip.
	Skip(Operation) error
}

Executor records and exposes uniter state, and applies suitable changes as operations are run or skipped.

func NewExecutor

func NewExecutor(stateFilePath string, getInstallCharm func() (*corecharm.URL, error)) (Executor, error)

NewExecutor returns an Executor which takes its starting state from the supplied path, and records state changes there. If no state file exists, the executor's starting state will include a queued Install hook, for the charm identified by the supplied func.

type Factory

type Factory interface {

	// NewInstall creates an install operation for the supplied charm.
	NewInstall(charmURL *corecharm.URL) (Operation, error)

	// NewUpgrade creates an upgrade operation for the supplied charm.
	NewUpgrade(charmURL *corecharm.URL) (Operation, error)

	// NewRevertUpgrade creates an operation to clear the unit's resolved flag,
	// and execute an upgrade to the supplied charm that is careful to excise
	// remnants of a previously failed upgrade to a different charm.
	NewRevertUpgrade(charmURL *corecharm.URL) (Operation, error)

	// NewResolvedUpgrade creates an operation to clear the unit's resolved flag,
	// and execute an upgrade to the supplied charm that is careful to preserve
	// non-overlapping remnants of a previously failed upgrade to the same charm.
	NewResolvedUpgrade(charmURL *corecharm.URL) (Operation, error)

	// NewRunHook creates an operation to execute the supplied hook.
	NewRunHook(hookInfo hook.Info) (Operation, error)

	// NewRetryHook creates an operation to clear the unit's resolved flag, and
	// re-execute the supplied hook.
	NewRetryHook(hookInfo hook.Info) (Operation, error)

	// NewSkipHook creates an operation to clear the unit's resolved flag, and
	// mark the supplied hook as completed successfully.
	NewSkipHook(hookInfo hook.Info) (Operation, error)

	// NewAction creates an operation to execute the supplied action.
	NewAction(actionId string) (Operation, error)

	// NewCommands creates an operation to execute the supplied script in the
	// indicated relation context, and pass the results back over the supplied
	// func.
	NewCommands(args CommandArgs, sendResponse CommandResponseFunc) (Operation, error)

	// NewUpdateRelations creates an operation to ensure the supplied relation
	// ids are known and tracked.
	NewUpdateRelations(ids []int) (Operation, error)
}

Factory creates operations.

func NewFactory

func NewFactory(
	deployer charm.Deployer,
	runnerFactory runner.Factory,
	callbacks Callbacks,
	abort <-chan struct{},
) Factory

NewFactory returns a Factory that creates Operations backed by the supplied parameters.

type Kind

type Kind string

Kind enumerates the operations the uniter can perform.

const (
	// Install indicates that the uniter is installing the charm.
	Install Kind = "install"

	// RunHook indicates that the uniter is running a hook.
	RunHook Kind = "run-hook"

	// RunAction indicates that the uniter is running an action.
	RunAction Kind = "run-action"

	// Upgrade indicates that the uniter is upgrading the charm.
	Upgrade Kind = "upgrade"

	// Continue indicates that the uniter should run ModeContinue
	// to determine the next operation.
	Continue Kind = "continue"
)

type Operation

type Operation interface {

	// String returns a short representation of the operation.
	String() string

	// Prepare ensures that the operation is valid and ready to be executed.
	// If it returns a non-nil state, that state will be validated and recorded.
	// If it returns ErrSkipExecute, it indicates that the operation can be
	// committed directly.
	Prepare(state State) (*State, error)

	// Execute carries out the operation. It must not be called without having
	// called Prepare first. If it returns a non-nil state, that state will be
	// validated and recorded.
	Execute(state State) (*State, error)

	// Commit ensures that the operation's completion is recorded. If it returns
	// a non-nil state, that state will be validated and recorded.
	Commit(state State) (*State, error)
}

Operation encapsulates the stages of the various things the uniter can do, and the state changes that need to be recorded as they happen. Operations are designed to be Run (or Skipped) by an Executor, which supplies starting state and records the changes returned.

type State

type State struct {
	// Started indicates whether the start hook has run.
	Started bool `yaml:"started"`

	// Kind indicates the current operation.
	Kind Kind `yaml:"op"`

	// Step indicates the current operation's progression.
	Step Step `yaml:"opstep"`

	// Hook holds hook information relevant to the current operation. If Kind
	// is Continue, it holds the last hook that was executed; if Kind is RunHook,
	// it holds the running hook; if Kind is Upgrade, a non-nil hook indicates
	// that the uniter should return to that hook's Pending state after the
	// upgrade is complete (instead of running an upgrade-charm hook).
	Hook *hook.Info `yaml:"hook,omitempty"`

	// ActionId holds action information relevant to the current operation. If
	// Kind is Continue, it holds the last action that was executed; if Kind is
	// RunAction, it holds the running action.
	ActionId *string `yaml:"action-id,omitempty"`

	// Charm describes the charm being deployed by an Install or Upgrade
	// operation, and is otherwise blank.
	CharmURL *charm.URL `yaml:"charm,omitempty"`

	// CollectMetricsTime records the time the collect metrics hook was last run.
	// It's set to nil if the hook was not run at all. Recording time as int64
	// because the yaml encoder cannot encode the time.Time struct.
	CollectMetricsTime int64 `yaml:"collectmetricstime,omitempty"`
}

State defines the local persistent state of the uniter, excluding relation state.

func (State) CollectedMetricsAt

func (st State) CollectedMetricsAt() time.Time

type StateFile

type StateFile struct {
	// contains filtered or unexported fields
}

StateFile holds the disk state for a uniter.

func NewStateFile

func NewStateFile(path string) *StateFile

NewStateFile returns a new StateFile using path.

func (*StateFile) Read

func (f *StateFile) Read() (*State, error)

Read reads a State from the file. If the file does not exist it returns ErrNoStateFile.

func (*StateFile) Write

func (f *StateFile) Write(st *State) error

Write stores the supplied state to the file.

type Step

type Step string

Step describes the recorded progression of an operation.

const (
	// Queued indicates that the uniter should undertake the operation
	// as soon as possible.
	Queued Step = "queued"

	// Pending indicates that the uniter has started, but not completed,
	// the operation.
	Pending Step = "pending"

	// Done indicates that the uniter has completed the operation,
	// but may not yet have synchronized all necessary secondary state.
	Done Step = "done"
)