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 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
                                        }

                                        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