operation

Documentation

Index

• Variables
• func DeployConflictCharmURL(err error) (*corecharm.URL, 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, 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 RequiresMachineLock
  • func (RequiresMachineLock) NeedsGlobalMachineLock() bool
• 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
• 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 DeployConflictCharmURL

func DeployConflictCharmURL(err error) (*corecharm.URL, bool)

DeployConflictCharmURL returns the charm URL used to create the supplied deploy conflict error, and a bool indicating success.

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

	// 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 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, getInstallCharm func() (*corecharm.URL, error), acquireLock func(string) (func() error, 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)

	// NewUpdateStorage creates an operation to ensure the supplied storage
	// tags are known and tracked.
	NewUpdateStorage(tags []names.StorageTag) (Operation, error)

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

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

Factory creates operations.

func NewFactory

func NewFactory(
	deployer charm.Deployer,
	runnerFactory runner.Factory,
	callbacks Callbacks,
	storageUpdater StorageUpdater,
	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

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

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

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

	// UpdateStatusTime records the time the update status hook was last run.
	// It's set to nil if the hook was not run at all.
	UpdateStatusTime int64 `yaml:"updatestatustime,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"
)

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.