operation

package
v0.0.0-...-ea3e8b0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 25, 2024 License: AGPL-3.0 Imports: 19 Imported by: 48

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNoSavedState is returned by StateOps if there is no saved state.  This is
	// usually seen when a unit starts for the first time.
	ErrNoSavedState           = errors.New("saved uniter state 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 NewDeployConflictError 

func NewDeployConflictError(charmURL string) error

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

func RunningHookMessage 

func RunningHookMessage(hookName string, info hook.Info) 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

	NotifyHookCompleted(string, context.Context)
	NotifyHookFailed(string, context.Context)

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

	// ActionStatus returns the status of the action required by the action operation for
	// cancelation.
	ActionStatus(actionId string) (string, error)

	// GetArchiveInfo is used to find out how to download a charm archive. It's
	// only used by Deploy operations.
	GetArchiveInfo(charmURL string) (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 string) error

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

	// SetSecretRotated updates the secret rotation status.
	SetSecretRotated(url string, originalRevision int) error

	// SecretsRemoved updates the unit secret state when
	// secrets are removed.
	SecretsRemoved(uris []string) error

	// RemoteInit copies the charm to the remote instance. CAAS only.
	RemoteInit(runningStatus remotestate.ContainerRunningStatus, abort <-chan struct{}) 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
	// TODO(jam): 2019-10-24 Include RemoteAppName
	// ForceRemoteUnit skips unit inference and existence validation.
	ForceRemoteUnit bool
	// RunLocation describes where the command must run.
	RunLocation runner.RunLocation
}

CommandArgs stores the arguments for a Command operation.

func (CommandArgs) Validate 

func (args CommandArgs) Validate() error

Validate the command arguments.

type CommandResponseFunc 

type CommandResponseFunc func(*utilexec.ExecResponse, error) bool

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

type DeployConflictError 

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

DeployConflictError is returned by the deploy operation when the charm cannot be deployed.

func (*DeployConflictError) Error 

func (err *DeployConflictError) Error() string

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

func (DoesNotRequireMachineLock) ExecutionGroup() string

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.
	// On remote state change, the executor will fire the operation's
	// RemoteStateChanged method.
	Run(Operation, <-chan remotestate.Snapshot) 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(unitName string, cfg ExecutorConfig) (Executor, error)

NewExecutor returns an Executor which takes its starting state from the controller, and records state changes there. If no saved state exists, the executor's starting state will be the supplied InitialState.

type ExecutorConfig 

type ExecutorConfig struct {
	StateReadWriter UnitStateReadWriter
	InitialState    State
	AcquireLock     func(string, string) (func(), error)
	Logger          Logger
}

ExecutorConfig defines configuration for an Executor.

type Factory 

type Factory interface {

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

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

	// NewRemoteInit inits the remote charm on CAAS pod.
	NewRemoteInit(runningStatus remotestate.ContainerRunningStatus) (Operation, error)

	// NewSkipRemoteInit skips a remote-init operation.
	NewSkipRemoteInit(retry bool) (Operation, error)

	// NewNoOpFinishUpgradeSeries creates a noop which simply resets the
	// status of a units upgrade series.
	NewNoOpFinishUpgradeSeries() (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 string) (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 string) (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)

	// NewNoOpSecretsRemoved creates an operation to update the secrets
	// state when secrets are removed.
	NewNoOpSecretsRemoved(uris []string) (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
	State          *uniter.State
	Abort          <-chan struct{}
	MetricSpoolDir string
	Logger         Logger
}

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"

	// RemoteInit indicates the CAAS uniter is installing/upgrading the
	// charm on the remote instance.
	RemoteInit Kind = "remote-init"
)

type Logger 

type Logger interface {
	Errorf(string, ...interface{})
	Warningf(string, ...interface{})
	Infof(string, ...interface{})
	Debugf(string, ...interface{})
	Tracef(string, ...interface{})
}

Logger determines the logging methods used by the operations package.

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

	// ExecutionGroup returns a string used to construct the name of the machine lock.
	ExecutionGroup() 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)

	// RemoteStateChanged is called when the remote state changed during execution
	// of the operation.
	RemoteStateChanged(snapshot remotestate.Snapshot)
}

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.

func Unwrap 

func Unwrap(op Operation) Operation

Unwrap peels back one layer of a wrapped operation.

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

func (RequiresMachineLock) ExecutionGroup() string

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

	// Removed indicates whether the remove hook has run.
	Removed bool `yaml:"removed"`

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

	// HookStep records any hook operation's progression. It will only be set
	// if Hook is also set. If not set, fallback to using just Step.
	// HookStep is recorded separately to Step so as not to lose the hook
	// state when initialising the agent and running any upgrade operation.
	HookStep *Step `yaml:"hook-step,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 string `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.

func (State) Report 

func (st State) Report() map[string]interface{}

func (State) Validate 

func (st State) Validate() (err error)

Validate returns an error if the state violates expectations.

type StateOps 

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

StateOps reads and writes uniter state from/to the controller.

func NewStateOps 

func NewStateOps(readwriter UnitStateReadWriter) *StateOps

NewStateOps returns a new StateOps.

func (*StateOps) Read 

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

Read a State from the controller. If the saved state does not exist it returns ErrNoSavedState.

func (*StateOps) Write 

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

Write stores the supplied state on the controller.

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.

type UnitStateReadWriter 

type UnitStateReadWriter interface {
	State() (params.UnitStateResult, error)
	SetState(unitState params.SetUnitStateArg) error
}

UnitStateReadWriter encapsulates the methods from a state.Unit required to set and get unit state.

type WrappedOperation 

type WrappedOperation interface {
	Operation

	WrappedOperation() Operation
}

WrappedOperation extends Operation to provide access to the wrapped operation.

Source Files

View all Source files

Directories

Path Synopsis
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.