operation

Documentation

Index

• Variables
• func IsDeployConflictError(err error) bool
• func NewDeployConflictError(charmURL *corecharm.URL) error
• func RunningHookMessage(hookName string) string
• type Callbacks
• type CommandArgs
• type CommandResponseFunc
• type DoesNotRequireMachineLock
  • func (DoesNotRequireMachineLock) NeedsGlobalMachineLock() bool
• type Executor
  • func NewExecutor(stateFilePath string, initialState State, ...) (Executor, error)
• type Factory
  • func NewFactory(params FactoryParams) Factory
• type FactoryParams
• type Kind
• type Operation
• type RequiresMachineLock
  • func (RequiresMachineLock) NeedsGlobalMachineLock() bool
• type State
• type StateFile
  • func NewStateFile(path string) *StateFile
  • func (f *StateFile) Read() (*State, error)
  • func (f *StateFile) Write(st *State) error
• type Step
• type StorageUpdater

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")
	ErrCannotAcceptLeadership = errors.New("cannot accept leadership")
)

Functions

func IsDeployConflictError

func IsDeployConflictError(err error) bool

IsDeployConflictError returns true if the error is a deploy conflict error.

func NewDeployConflictError

func NewDeployConflictError(charmURL *corecharm.URL) error

NewDeployConflictError returns an error indicating that the charm with the supplied URL failed to deploy.

func RunningHookMessage

func RunningHookMessage(hookName string) string

RunningHookMessage returns the info message to print when running a hook.

Types

type Callbacks

type Callbacks interface {
	// 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

	// SetExecutingStatus sets the agent state to "Executing" with a message.
	SetExecutingStatus(string) 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)

	// 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 controller can legitimately garbage collect that
	// charm or the application's settings for it. It's only used by Deploy operations.
	SetCurrentCharm(charmURL *corecharm.URL) error

	// SetSeriesStatusUpgrade is intended to give the uniter a chance to
	// upgrade the status of a running series upgrade before or after
	// upgrade series hook code completes and, for display purposes, to
	// supply a reason as to why it is making the change.
	SetUpgradeSeriesStatus(status model.UpgradeSeriesStatus, reason string) error

	// RemoveUpgradeCharmProfileData is intended to clean up the LXDProfile status
	// to ensure that we start from a clean slate.
	RemoveUpgradeCharmProfileData() 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 DoesNotRequireMachineLock

type DoesNotRequireMachineLock struct{}

DoesNotRequireMachineLock is embedded in the various operations to express whether they need a global machine lock or not.

func (DoesNotRequireMachineLock) NeedsGlobalMachineLock

func (DoesNotRequireMachineLock) NeedsGlobalMachineLock() bool

NeedsGlobalMachineLock is part of the Operation interface. It is embedded in the various operations.

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, initialState State, acquireLock func(string) (func(), 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)

	// NewNoOpUpgrade creates a noop upgrade operation for the supplied charm.
	// The purpose is to go through the machinations so that in the commit phase,
	// the uniter records the current charm url and modified version in local state
	// so it knows the upgraded charm has been unpacked and it can run the upgrade-charm hook.
	// For a caas uniter, the operator is the thing that does the charm upgrade,
	// so we just plug in a no op into the uniter state machine.
	NewNoOpUpgrade(charmURL *corecharm.URL) (Operation, error)

	// NewNoOpFinishUpgradeSeries creates a noop which simply resets the
	// status of a units upgrade series.
	NewNoOpFinishUpgradeSeries() (Operation, error)

	// NewFinishUpgradeCharmProfile simply cleans up the state of the unit
	// of a upgrade charm profile.
	NewFinishUpgradeCharmProfile(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)

	// NewSkipHook creates an operation to mark the supplied hook as
	// completed successfully, without executing the hook.
	NewSkipHook(hookInfo hook.Info) (Operation, error)

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

	// NewFailAction creates an operation that marks an action as failed.
	NewFailAction(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)

	// NewAcceptLeadership creates an operation to ensure the uniter acts as
	// application leader.
	NewAcceptLeadership() (Operation, error)

	// NewResignLeadership creates an operation to ensure the uniter does not
	// act as application leader.
	NewResignLeadership() (Operation, error)
}

Factory creates operations.

func NewFactory

func NewFactory(params FactoryParams) Factory

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

type FactoryParams

type FactoryParams struct {
	Deployer       charm.Deployer
	RunnerFactory  runner.Factory
	Callbacks      Callbacks
	Abort          <-chan struct{}
	MetricSpoolDir string
}

FactoryParams holds all the necessary parameters for a new operation factory.

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

	// NeedsGlobalMachineLock returns a bool expressing whether we need to lock the machine.
	NeedsGlobalMachineLock() bool

	// 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 RequiresMachineLock

type RequiresMachineLock struct{}

DoesNotRequireMachineLock is embedded in the various operations to express whether they need a global machine lock or not.

func (RequiresMachineLock) NeedsGlobalMachineLock

func (RequiresMachineLock) NeedsGlobalMachineLock() bool

NeedsGlobalMachineLock is part of the Operation interface. It is embedded in the various operations.

type State

type State struct {

	// Leader indicates whether a leader-elected hook has been queued to run, and
	// no more recent leader-deposed hook has completed.
	Leader bool `yaml:"leader"`

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

	// Stopped indicates whether the stop hook has run.
	Stopped bool `yaml:"stopped"`

	// Installed indicates whether the install hook has run.
	Installed bool `yaml:"installed"`

	// StatusSet indicates whether the charm being deployed has ever invoked
	// the status-set hook tool.
	StatusSet bool `yaml:"status-set"`

	// 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"`

	// ConfigHash stores a hash of the latest known charm
	// configuration settings - it's used to determine whether we need
	// to run config-changed.
	ConfigHash string `yaml:"config-hash,omitempty"`

	// TrustHash stores a hash of the latest known charm trust
	// configuration settings - it's used to determine whether we need
	// to run config-changed.
	TrustHash string `yaml:"trust-hash,omitempty"`

	// AddressesHash stores a hash of the latest known
	// machine/container addresses - it's used to determine whether we
	// need to run config-changed.
	AddressesHash string `yaml:"addresses-hash,omitempty"`
}

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

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"
)

type StorageUpdater

type StorageUpdater interface {
	// UpdateStorage updates local knowledge of the storage attachments
	// with the specified tags.
	UpdateStorage([]names.StorageTag) error
}

StorageUpdater is an interface used for updating local knowledge of storage attachments.