drivers

package
v1.3.5 Latest Latest
Warning

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

 Go to latest Published: Aug 31, 2022 License: MPL-2.0 Imports: 32 Imported by: 529

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

	// DetachSignal is a special signal sent to remote task drivers when a
	// task should be detached instead of killed. This allows a remote task
	// to be left running and transferred to a replacement allocation in
	// cases like down or drained nodes causing the original allocation to
	// be terminal.
	DetachSignal = "DETACH"
)
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
	// intended 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 added in v0.10.0 

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

	// MountConfigs tells Nomad which mounting config options the driver supports.
	MountConfigs MountConfigSupport

	// RemoteTasks indicates this driver runs tasks on remote systems
	// instead of locally. The Nomad client can use this information to
	// adjust behavior such as propogating task handles between allocations
	// to avoid downtime when a client is lost.
	RemoteTasks bool
}

func (*Capabilities) HasNetIsolationMode added in v0.10.0 

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

type CpuStats 

type CpuStats = cstructs.CpuStats

CpuStats holds cpu usage related stats

type DNSConfig added in v0.12.0 

type DNSConfig struct {
	Servers  []string
	Searches []string
	Options  []string
}

func (*DNSConfig) Copy added in v0.12.0 

func (c *DNSConfig) Copy() *DNSConfig

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 added in v0.10.0 

type DriverNetworkManager interface {
	CreateNetwork(allocID string, request *NetworkCreateRequest) (*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 added in v0.9.2 

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 added in v0.9.2 

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 added in v0.9.2 

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 added in v0.9.2 

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 added in v0.9.2 

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 added in v0.9.2 

type ExecTaskStreamingRequestMsg = proto.ExecTaskStreamingRequest

type ExecTaskStreamingResponseMsg added in v0.9.2 

type ExecTaskStreamingResponseMsg = proto.ExecTaskStreamingResponse

func NewExecStreamingResponseExit added in v0.9.2 

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 HostsConfig added in v1.1.2 

type HostsConfig struct {
	Hostname string
	Address  string
}

type InternalCapabilities added in v0.10.4 

type InternalCapabilities struct {
	DisableLogCollection     bool
	DisableMetricsCollection bool
}

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

type InternalCapabilitiesDriver added in v0.10.4 

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 LinuxResources 

type LinuxResources struct {
	CPUPeriod        int64
	CPUQuota         int64
	CPUShares        int64
	MemoryLimitBytes int64
	OOMScoreAdj      int64

	CpusetCpus       string
	CpusetCgroupPath 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 MemoryResources added in v1.1.0 

type MemoryResources = structs.AllocatedMemoryResources

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 added in v0.10.0 

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

type MountConfigSupport added in v0.11.3 

type MountConfigSupport int32

MountConfigSupport is an enum that defaults to "all" for backwards compatibility with community drivers. 

const (
	MountConfigSupportAll MountConfigSupport = iota
	MountConfigSupportNone
)

type NetIsolationMode added in v0.10.0 

type NetIsolationMode string

type NetworkCreateRequest added in v1.1.5 

type NetworkCreateRequest struct {

	// Hostname is the hostname the user has specified that the network should
	// be configured with.
	Hostname string
}

NetworkCreateRequest contains all the relevant information when creating a network via DriverNetworkManager.CreateNetwork.

type NetworkIsolationSpec added in v0.10.0 

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

func NetworkIsolationSpecFromProto added in v0.10.0 

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
	Ports          *structs.AllocatedPorts
}

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
	JobID         string
	TaskGroupName string
	Name          string // task.Name
	Namespace     string
	NodeName      string
	NodeID        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
	DNS              *DNSConfig
	// 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 NewTaskHandleFromState added in v1.1.0 

func NewTaskHandleFromState(ts *structs.TaskState) *TaskHandle

NewTaskHandleFromState returns the TaskHandle stored in a TaskState or nil if no handle was stored.

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

func (*TaskHandle) Store added in v1.1.0 

func (h *TaskHandle) Store(ts *structs.TaskState)

Store this TaskHandle on the given TaskState.

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 added in v0.9.2 

type TerminalSize struct {
	Height int
	Width  int
}

Source Files

View all Source files

Directories

Path Synopsis

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.