Version: v1.5.6 Latest Latest

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

Go to latest
Published: May 19, 2023 License: MPL-2.0 Imports: 31 Imported by: 449




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


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"


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)


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 {

	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 {
		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 block.
	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

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


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL