interfaces

Documentation

Index

• type AllocRunner
• type AllocStatsReporter
• type DriverStats
• type RunnerDestroyHook
• type RunnerHook
• type RunnerPostrunHook
• type RunnerPreKillHook
• type RunnerPrerunHook
• type RunnerTaskRestartHook
• type RunnerUpdateHook
• type RunnerUpdateRequest
• type ShutdownHook
• type TaskExitedHook
• type TaskExitedRequest
• type TaskExitedResponse
• type TaskHook
• type TaskPoststartHook
• type TaskPoststartRequest
• type TaskPoststartResponse
• type TaskPreKillHook
• type TaskPreKillRequest
• type TaskPreKillResponse
• type TaskPrestartHook
• type TaskPrestartRequest
• type TaskPrestartResponse
• type TaskStateHandler
• type TaskStopHook
• type TaskStopRequest
• type TaskStopResponse
• type TaskUpdateHook
• type TaskUpdateRequest
• type TaskUpdateResponse

Types

type AllocRunner

type AllocRunner interface {
	// ID returns the ID of the allocation being run.
	ID() string

	// Run starts the runner and begins executing all the tasks as part of the
	// allocation.
	Run()

	// State returns a copy of the runners state object
	State() *state.State

	TaskStateHandler
}

AllocRunner is the interface for an allocation runner.

type AllocStatsReporter

type AllocStatsReporter interface {
	LatestAllocStats(taskFilter string) (*cstructs.AllocResourceUsage, error)
}

AllocStatsReporter gives access to the latest resource usage from the allocation

type DriverStats

type DriverStats interface {
	Stats(context.Context, time.Duration) (<-chan *cstructs.TaskResourceUsage, error)
}

DriverStats is the interface implemented by DriverHandles to return task stats.

type RunnerDestroyHook

type RunnerDestroyHook interface {
	RunnerHook
	Destroy() error
}

A RunnerDestroyHook is executed after AllocRunner.Run has exited and must make a best effort cleanup allocation resources. Destroy hooks must be safe to call without first calling Prerun.

type RunnerHook

type RunnerHook interface {
	Name() string
}

RunnerHook is a lifecycle hook into the life cycle of an allocation runner.

type RunnerPostrunHook

type RunnerPostrunHook interface {
	RunnerHook
	Postrun() error
}

A RunnerPostrunHook is executed after calling TaskRunner.Run, even for terminal allocations. Therefore Postrun hooks must be safe to call without first calling Prerun hooks.

type RunnerPreKillHook

type RunnerPreKillHook interface {
	RunnerHook

	PreKill()
}

A RunnerPreKillHook is executed inside of KillTasks before iterating and killing each task. It will run before the Leader task is killed.

type RunnerPrerunHook

type RunnerPrerunHook interface {
	RunnerHook
	Prerun() error
}

A RunnerPrerunHook is executed before calling TaskRunner.Run for non-terminal allocations. Terminal allocations do *not* call prerun.

type RunnerTaskRestartHook

type RunnerTaskRestartHook interface {
	RunnerHook

	PreTaskRestart() error
}

A RunnerTaskRestartHook is executed just before the allocation runner is going to restart all tasks.

type RunnerUpdateHook

type RunnerUpdateHook interface {
	RunnerHook
	Update(*RunnerUpdateRequest) error
}

A RunnerUpdateHook is executed when an allocation update is received from the server. Update is called concurrently with AllocRunner execution and therefore must be safe for concurrent access with other hook methods. Calls to Update are serialized so allocation updates will always be processed in order.

type RunnerUpdateRequest

type RunnerUpdateRequest struct {
	Alloc *structs.Allocation
}

type ShutdownHook

type ShutdownHook interface {
	RunnerHook

	Shutdown()
}

ShutdownHook may be implemented by AllocRunner or TaskRunner hooks and will be called when the agent process is being shutdown gracefully.

type TaskExitedHook

type TaskExitedHook interface {
	TaskHook

	// Exited is called after a task exits and may or may not be restarted.
	// Prestart may or may not have been called.
	//
	// The context is cancelled if the task is killed.
	Exited(context.Context, *TaskExitedRequest, *TaskExitedResponse) error
}

type TaskExitedRequest

type TaskExitedRequest struct{}

type TaskExitedResponse

type TaskExitedResponse struct{}

type TaskHook

type TaskHook interface {
	Name() string
}

TaskHook is a lifecycle hook into the life cycle of a task runner.

type TaskPoststartHook

type TaskPoststartHook interface {
	TaskHook

	// Poststart is called after the task has started. Poststart is not
	// called if the allocation is terminal.
	//
	// The context is cancelled if the task is killed.
	Poststart(context.Context, *TaskPoststartRequest, *TaskPoststartResponse) error
}

type TaskPoststartRequest

type TaskPoststartRequest struct {
	// Exec hook (may be nil)
	DriverExec interfaces.ScriptExecutor

	// Network info (may be nil)
	DriverNetwork *drivers.DriverNetwork

	// TaskEnv is the task's environment
	TaskEnv *taskenv.TaskEnv

	// Stats collector
	DriverStats DriverStats
}

type TaskPoststartResponse

type TaskPoststartResponse struct{}

type TaskPreKillHook

type TaskPreKillHook interface {
	TaskHook

	// PreKilling is called right before a task is going to be killed or
	// restarted. They are called concurrently with TaskRunner.Run and may
	// be called without Prestart being called.
	PreKilling(context.Context, *TaskPreKillRequest, *TaskPreKillResponse) error
}

type TaskPreKillRequest

type TaskPreKillRequest struct{}

type TaskPreKillResponse

type TaskPreKillResponse struct{}

type TaskPrestartHook

type TaskPrestartHook interface {
	TaskHook

	// Prestart is called before the task is started including after every
	// restart. Prestart is not called if the allocation is terminal.
	//
	// The context is cancelled if the task is killed or shutdown but
	// should not be stored any persistent goroutines this Prestart
	// creates.
	Prestart(context.Context, *TaskPrestartRequest, *TaskPrestartResponse) error
}

type TaskPrestartRequest

type TaskPrestartRequest struct {
	// PreviousState is previously set data by the hook. It must be copied
	// to State below to be maintained across restarts.
	PreviousState map[string]string

	// Task is the task to run
	Task *structs.Task

	// TaskResources is the resources assigned to the task
	TaskResources *structs.AllocatedTaskResources

	// Vault token may optionally be set if a Vault token is available
	VaultToken string

	// NomadToken token may optionally be set if a Nomad token is available
	NomadToken string

	// TaskDir contains the task's directory tree on the host
	TaskDir *allocdir.TaskDir

	// TaskEnv is the task's environment
	TaskEnv *taskenv.TaskEnv

	// Alloc is the current version of the allocation
	Alloc *structs.Allocation
}

type TaskPrestartResponse

type TaskPrestartResponse struct {
	// Env is the environment variables to set for the task
	Env map[string]string

	// Mounts is the set of host volumes to mount into the task
	Mounts []*drivers.MountConfig

	// Devices are the set of devices to mount into the task
	Devices []*drivers.DeviceConfig

	// State allows the hook to emit data to be passed in the next time it is
	// run. Hooks must copy relevant PreviousState to State to maintain it
	// across restarts.
	State map[string]string

	// Done lets the hook indicate that it completed successfully and
	// should not be run again.
	Done bool
}

type TaskStateHandler

type TaskStateHandler interface {
	// TaskStateUpdated is used to notify the alloc runner about task state
	// changes.
	TaskStateUpdated()
}

TaskStateHandler exposes a handler to be called when a task's state changes

type TaskStopHook

type TaskStopHook interface {
	TaskHook

	// Stop is called after the task has exited and will not be started
	// again. It is the only hook guaranteed to be executed whenever
	// TaskRunner.Run is called (and not gracefully shutting down).
	// Therefore it may be called even when prestart and the other hooks
	// have not.
	//
	// Stop hooks must be idempotent. The context is cancelled if the task
	// is killed.
	Stop(context.Context, *TaskStopRequest, *TaskStopResponse) error
}

type TaskStopRequest

type TaskStopRequest struct {
	// ExistingState is previously set hook data and should only be
	// read. Stop hooks cannot alter state.
	ExistingState map[string]string

	// TaskDir contains the task's directory tree on the host
	TaskDir *allocdir.TaskDir
}

type TaskStopResponse

type TaskStopResponse struct{}

type TaskUpdateHook

type TaskUpdateHook interface {
	TaskHook

	// Update is called when the servers have updated the Allocation for
	// this task. Updates are concurrent with all other task hooks and
	// therefore hooks that implement this interface must be completely
	// safe for concurrent access.
	//
	// The context is cancelled if the task is killed.
	Update(context.Context, *TaskUpdateRequest, *TaskUpdateResponse) error
}

type TaskUpdateRequest

type TaskUpdateRequest struct {
	VaultToken string

	NomadToken string

	// Alloc is the current version of the allocation (may have been
	// updated since the hook was created)
	Alloc *structs.Allocation

	// TaskEnv is the task's environment
	TaskEnv *taskenv.TaskEnv
}

type TaskUpdateResponse

type TaskUpdateResponse struct{}