Documentation

Index

Constants

View Source
const (
	// DriverHealthy is the default health description that should be used
	// if the driver is nominal
	DriverHealthy = "Healthy"

	// Pre09TaskHandleVersion is the version used to identify that the task
	// handle is from a driver that existed before driver plugins (v0.9). The
	// driver should take appropriate action to handle the old driver state.
	Pre09TaskHandleVersion = 0
)
View Source
const (
	// ApiVersion010 is the initial API version for the device plugins
	ApiVersion010 = "v0.1.0"
)
View Source
const CheckBufSize = cstructs.CheckBufSize

CheckBufSize is the size of the buffer that is used for job output

Variables

View Source
var (
	HealthStateUndetected = HealthState("undetected")
	HealthStateUnhealthy  = HealthState("unhealthy")
	HealthStateHealthy    = HealthState("healthy")
)
View Source
var (
	// FSIsolationNone means no isolation. The host filesystem is used.
	FSIsolationNone = FSIsolation("none")

	// FSIsolationChroot means the driver will use a chroot on the host
	// filesystem.
	FSIsolationChroot = FSIsolation("chroot")

	// FSIsolationImage means the driver uses an image.
	FSIsolationImage = FSIsolation("image")
)
View Source
var (
	// NetIsolationModeHost disables network isolation and uses the host network
	NetIsolationModeHost = NetIsolationMode("host")

	// NetIsolationModeGroup uses the group network namespace for isolation
	NetIsolationModeGroup = NetIsolationMode("group")

	// NetIsolationModeTask isolates the network to just the task
	NetIsolationModeTask = NetIsolationMode("task")

	// NetIsolationModeNone indicates that there is no network to isolate and is
	// inteded to be used for tasks that the client manages remotely
	NetIsolationModeNone = NetIsolationMode("none")
)
View Source
var CgroupMountEmpty = "Cgroup mount point unavailable"
View Source
var DriverRequiresRootMessage = "Driver must run as root"
View Source
var DriverStatsNotImplemented = cstructs.DriverStatsNotImplemented

DriverStatsNotImplemented is the error to be returned if a driver doesn't implement stats.

View Source
var ErrTaskNotFound = fmt.Errorf("task not found for given id")
View Source
var NoCgroupMountMessage = "Failed to discover cgroup mount point"

Functions

func BytesToMB

func BytesToMB(bytes int64) int64

func DeviceToProto

func DeviceToProto(device *DeviceConfig) *proto.Device

func DevicesToProto

func DevicesToProto(devices []*DeviceConfig) []*proto.Device

func MountToProto

func MountToProto(mount *MountConfig) *proto.Mount

func MountsToProto

func MountsToProto(mounts []*MountConfig) []*proto.Mount

func NetworkIsolationSpecToProto

func NetworkIsolationSpecToProto(spec *NetworkIsolationSpec) *proto.NetworkIsolationSpec

func ResourcesToProto

func ResourcesToProto(r *Resources) *proto.Resources

func Serve

func Serve(d DriverPlugin, logger hclog.Logger)

Serve is used to serve a driverplugin

func TaskStatsToProto

func TaskStatsToProto(stats *TaskResourceUsage) (*proto.TaskStats, error)

Types

type Capabilities

type Capabilities struct {
	// SendSignals marks the driver as being able to send signals
	SendSignals bool

	// Exec marks the driver as being able to execute arbitrary commands
	// such as health checks. Used by the ScriptExecutor interface.
	Exec bool

	//FSIsolation indicates what kind of filesystem isolation the driver supports.
	FSIsolation FSIsolation

	//NetIsolationModes lists the set of isolation modes supported by the driver
	NetIsolationModes []NetIsolationMode

	// MustInitiateNetwork tells Nomad that the driver must create the network
	// namespace and that the CreateNetwork and DestroyNetwork RPCs are implemented.
	MustInitiateNetwork bool
}

func (*Capabilities) HasNetIsolationMode

func (c *Capabilities) HasNetIsolationMode(m NetIsolationMode) bool

type CpuStats

type CpuStats = cstructs.CpuStats

CpuStats holds cpu usage related stats

type DeviceConfig

type DeviceConfig struct {
	TaskPath    string
	HostPath    string
	Permissions string
}

func DeviceFromProto

func DeviceFromProto(device *proto.Device) *DeviceConfig

func DevicesFromProto

func DevicesFromProto(devices []*proto.Device) []*DeviceConfig

func (*DeviceConfig) Copy

func (d *DeviceConfig) Copy() *DeviceConfig

type DriverExecTaskNotSupported

type DriverExecTaskNotSupported struct{}

DriverExecTaskNotSupported can be embedded by drivers which don't support the ExecTask RPC. This satisfies the ExecTask func requirement of the DriverPlugin interface.

func (DriverExecTaskNotSupported) ExecTask

func (_ DriverExecTaskNotSupported) ExecTask(taskID string, cmd []string, timeout time.Duration) (*ExecTaskResult, error)

type DriverNetwork

type DriverNetwork struct {
	// PortMap can be set by drivers to replace ports in environment
	// variables with driver-specific mappings.
	PortMap map[string]int

	// IP is the IP address for the task created by the driver.
	IP string

	// AutoAdvertise indicates whether the driver thinks services that
	// choose to auto-advertise-addresses should use this IP instead of the
	// host's. eg If a Docker network plugin is used
	AutoAdvertise bool
}

DriverNetwork is the network created by driver's (eg Docker's bridge network) during Prestart.

func (*DriverNetwork) Advertise

func (d *DriverNetwork) Advertise() bool

Advertise returns true if the driver suggests using the IP set. May be called on a nil Network in which case it returns false.

func (*DriverNetwork) Copy

func (d *DriverNetwork) Copy() *DriverNetwork

Copy a DriverNetwork struct. If it is nil, nil is returned.

func (*DriverNetwork) Hash

func (d *DriverNetwork) Hash() []byte

Hash the contents of a DriverNetwork struct to detect changes. If it is nil, an empty slice is returned.

type DriverNetworkManager

type DriverNetworkManager interface {
	CreateNetwork(allocID string) (*NetworkIsolationSpec, bool, error)
	DestroyNetwork(allocID string, spec *NetworkIsolationSpec) error
}

DriverNetworkManager is the interface with exposes function for creating a network namespace for which tasks can join. This only needs to be implemented if the driver MUST create the network namespace

type DriverPlugin

type DriverPlugin interface {
	base.BasePlugin

	TaskConfigSchema() (*hclspec.Spec, error)
	Capabilities() (*Capabilities, error)
	Fingerprint(context.Context) (<-chan *Fingerprint, error)

	RecoverTask(*TaskHandle) error
	StartTask(*TaskConfig) (*TaskHandle, *DriverNetwork, error)
	WaitTask(ctx context.Context, taskID string) (<-chan *ExitResult, error)
	StopTask(taskID string, timeout time.Duration, signal string) error
	DestroyTask(taskID string, force bool) error
	InspectTask(taskID string) (*TaskStatus, error)
	TaskStats(ctx context.Context, taskID string, interval time.Duration) (<-chan *cstructs.TaskResourceUsage, error)
	TaskEvents(context.Context) (<-chan *TaskEvent, error)

	SignalTask(taskID string, signal string) error
	ExecTask(taskID string, cmd []string, timeout time.Duration) (*ExecTaskResult, error)
}

DriverPlugin is the interface with drivers will implement. It is also implemented by a plugin client which proxies the calls to go-plugin. See the proto/driver.proto file for detailed information about each RPC and message structure.

type DriverSignalTaskNotSupported

type DriverSignalTaskNotSupported struct{}

DriverSignalTaskNotSupported can be embedded by drivers which don't support the SignalTask RPC. This satisfies the SignalTask func requirement for the DriverPlugin interface.

func (DriverSignalTaskNotSupported) SignalTask

func (DriverSignalTaskNotSupported) SignalTask(taskID, signal string) error

type ExecOptions

type ExecOptions struct {
	// Command is command to run
	Command []string

	// Tty indicates whether pseudo-terminal is to be allocated
	Tty bool

	// streams
	Stdin  io.ReadCloser
	Stdout io.WriteCloser
	Stderr io.WriteCloser

	// terminal size channel
	ResizeCh <-chan TerminalSize
}

func StreamToExecOptions

func StreamToExecOptions(
	ctx context.Context,
	command []string,
	tty bool,
	stream ExecTaskStream) (*ExecOptions, <-chan error)

StreamToExecOptions is a convenience method to convert exec stream into ExecOptions object.

type ExecTaskResult

type ExecTaskResult struct {
	Stdout     []byte
	Stderr     []byte
	ExitResult *ExitResult
}

type ExecTaskStream

type ExecTaskStream interface {
	// Send relays response message back to API.
	//
	// The call is synchronous and no references to message is held: once
	// method call completes, the message reference can be reused or freed.
	Send(*ExecTaskStreamingResponseMsg) error

	// Receive exec streaming messages from API.  Returns `io.EOF` on completion of stream.
	Recv() (*ExecTaskStreamingRequestMsg, error)
}

ExecTaskStream represents a stream of exec streaming messages, and is a handle to get stdin and tty size and send back stdout/stderr and exit operations.

The methods are not concurrent safe; callers must ensure that methods are called from at most one goroutine.

type ExecTaskStreamingDriver

type ExecTaskStreamingDriver interface {
	ExecTaskStreaming(ctx context.Context, taskID string, execOptions *ExecOptions) (*ExitResult, error)
}

ExecTaskStreamingDriver marks that a driver supports streaming exec task. This represents a user friendly interface to implement, as an alternative to the ExecTaskStreamingRawDriver, the low level interface.

type ExecTaskStreamingRawDriver

type ExecTaskStreamingRawDriver interface {
	ExecTaskStreamingRaw(
		ctx context.Context,
		taskID string,
		command []string,
		tty bool,
		stream ExecTaskStream) error
}

ExecTaskStreamingRawDriver represents a low-level interface for executing a streaming exec call, and is intended to be used when driver instance is to delegate exec handling to another backend, e.g. to a executor or a driver behind a grpc/rpc protocol

Nomad client would prefer this interface method over `ExecTaskStreaming` if driver implements it.

type ExecTaskStreamingRequestMsg

type ExecTaskStreamingRequestMsg = proto.ExecTaskStreamingRequest

type ExecTaskStreamingResponseMsg

type ExecTaskStreamingResponseMsg = proto.ExecTaskStreamingResponse

func NewExecStreamingResponseExit

func NewExecStreamingResponseExit(exitCode int) *ExecTaskStreamingResponseMsg

type ExitResult

type ExitResult struct {
	ExitCode  int
	Signal    int
	OOMKilled bool
	Err       error
}

func (*ExitResult) Copy

func (r *ExitResult) Copy() *ExitResult

func (*ExitResult) Successful

func (r *ExitResult) Successful() bool

type FSIsolation

type FSIsolation string

FSIsolation is an enumeration to describe what kind of filesystem isolation a driver supports.

type Fingerprint

type Fingerprint struct {
	Attributes        map[string]*pstructs.Attribute
	Health            HealthState
	HealthDescription string

	// Err is set by the plugin if an error occurred during fingerprinting
	Err error
}

type HealthState

type HealthState string

type InternalCapabilities

type InternalCapabilities struct {
	DisableLogCollection     bool
	DisableMetricsCollection bool
}

InternalCapabilities flags disabled functionality. Zero value means all is supported.

type InternalCapabilitiesDriver

type InternalCapabilitiesDriver interface {
	InternalCapabilities() InternalCapabilities
}

InternalCapabilitiesDriver is an experimental interface enabling a driver to disable some nomad functionality (e.g. logs or metrics).

Intended for internal drivers only while the interface is stabalized.

type InternalDriverPlugin

type InternalDriverPlugin interface {
	// Shutdown allows the plugin to cleanup any running state to avoid leaking
	// resources. It should not block.
	Shutdown()
}

InternalDriverPlugin is an interface that exposes functions that are only implemented by internal driver plugins.

type LinuxResources

type LinuxResources struct {
	CPUPeriod        int64
	CPUQuota         int64
	CPUShares        int64
	MemoryLimitBytes int64
	OOMScoreAdj      int64
	CpusetCPUs       string
	CpusetMems       string

	// PrecentTicks is used to calculate the CPUQuota, currently the docker
	// driver exposes cpu period and quota through the driver configuration
	// and thus the calculation for CPUQuota cannot be done on the client.
	// This is a capatability and should only be used by docker until the docker
	// specific options are deprecated in favor of exposes CPUPeriod and
	// CPUQuota at the task resource stanza.
	PercentTicks float64
}

func (*LinuxResources) Copy

func (r *LinuxResources) Copy() *LinuxResources

type MemoryStats

type MemoryStats = cstructs.MemoryStats

MemoryStats holds memory usage related stats

type MountConfig

type MountConfig struct {
	TaskPath        string
	HostPath        string
	Readonly        bool
	PropagationMode string
}

func MountFromProto

func MountFromProto(mount *proto.Mount) *MountConfig

func MountsFromProto

func MountsFromProto(mounts []*proto.Mount) []*MountConfig

func (*MountConfig) Copy

func (m *MountConfig) Copy() *MountConfig

func (*MountConfig) IsEqual

func (m *MountConfig) IsEqual(o *MountConfig) bool

type NetIsolationMode

type NetIsolationMode string

type NetworkIsolationSpec

type NetworkIsolationSpec struct {
	Mode   NetIsolationMode
	Path   string
	Labels map[string]string
}

func NetworkIsolationSpecFromProto

func NetworkIsolationSpecFromProto(pb *proto.NetworkIsolationSpec) *NetworkIsolationSpec

type PluginDriver

type PluginDriver struct {
	plugin.NetRPCUnsupportedPlugin
	// contains filtered or unexported fields
}

PluginDriver wraps a DriverPlugin and implements go-plugins GRPCPlugin interface to expose the the interface over gRPC

func NewDriverPlugin

func NewDriverPlugin(d DriverPlugin, logger hclog.Logger) *PluginDriver

func (*PluginDriver) GRPCClient

func (p *PluginDriver) GRPCClient(ctx context.Context, broker *plugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

func (*PluginDriver) GRPCServer

func (p *PluginDriver) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

type ResourceUsage

type ResourceUsage = cstructs.ResourceUsage

ResourceUsage holds information related to cpu and memory stats

type Resources

type Resources struct {
	NomadResources *structs.AllocatedTaskResources
	LinuxResources *LinuxResources
}

func ResourcesFromProto

func ResourcesFromProto(pb *proto.Resources) *Resources

func (*Resources) Copy

func (r *Resources) Copy() *Resources

type TaskConfig

type TaskConfig struct {
	ID            string
	JobName       string
	TaskGroupName string
	Name          string
	Env           map[string]string
	DeviceEnv     map[string]string
	Resources     *Resources
	Devices       []*DeviceConfig
	Mounts        []*MountConfig
	User          string
	AllocDir      string

	StdoutPath       string
	StderrPath       string
	AllocID          string
	NetworkIsolation *NetworkIsolationSpec
	// contains filtered or unexported fields
}

func (*TaskConfig) Copy

func (tc *TaskConfig) Copy() *TaskConfig

func (*TaskConfig) DecodeDriverConfig

func (tc *TaskConfig) DecodeDriverConfig(t interface{}) error

func (*TaskConfig) EncodeConcreteDriverConfig

func (tc *TaskConfig) EncodeConcreteDriverConfig(t interface{}) error

func (*TaskConfig) EncodeDriverConfig

func (tc *TaskConfig) EncodeDriverConfig(val cty.Value) error

func (*TaskConfig) EnvList

func (tc *TaskConfig) EnvList() []string

func (*TaskConfig) TaskDir

func (tc *TaskConfig) TaskDir() *allocdir.TaskDir

type TaskEvent

type TaskEvent struct {
	TaskID      string
	TaskName    string
	AllocID     string
	Timestamp   time.Time
	Message     string
	Annotations map[string]string

	// Err is only used if an error occurred while consuming the RPC stream
	Err error
}

type TaskHandle

type TaskHandle struct {
	// Version is set by the driver an allows it to handle upgrading from
	// an older DriverState struct. Prior to 0.9 the only state stored for
	// driver was the reattach config for the executor. To allow upgrading to
	// 0.9, Version 0 is handled as if it is the json encoded reattach config.
	Version     int
	Config      *TaskConfig
	State       TaskState
	DriverState []byte
}

TaskHandle is the state shared between a driver and the client. It is returned to the client after starting the task and used for recovery of tasks during a driver restart.

func NewTaskHandle

func NewTaskHandle(version int) *TaskHandle

func (*TaskHandle) Copy

func (h *TaskHandle) Copy() *TaskHandle

func (*TaskHandle) GetDriverState

func (h *TaskHandle) GetDriverState(v interface{}) error

func (*TaskHandle) SetDriverState

func (h *TaskHandle) SetDriverState(v interface{}) error

type TaskResourceUsage

type TaskResourceUsage = cstructs.TaskResourceUsage

TaskResourceUsage holds aggregated resource usage of all processes in a Task and the resource usage of the individual pids

func TaskStatsFromProto

func TaskStatsFromProto(pb *proto.TaskStats) (*TaskResourceUsage, error)

type TaskState

type TaskState string
const (
	TaskStateUnknown TaskState = "unknown"
	TaskStateRunning TaskState = "running"
	TaskStateExited  TaskState = "exited"
)

type TaskStatus

type TaskStatus struct {
	ID               string
	Name             string
	State            TaskState
	StartedAt        time.Time
	CompletedAt      time.Time
	ExitResult       *ExitResult
	DriverAttributes map[string]string
	NetworkOverride  *DriverNetwork
}

type TerminalSize

type TerminalSize struct {
	Height int
	Width  int
}

Directories

Path Synopsis
proto
testutils
utils