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

      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
        }

        func (*Capabilities) HasNetIsolationMode

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

        type CpuStats

        type CpuStats = cstructs.CpuStats

          CpuStats holds cpu usage related stats

          type DNSConfig

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

          func (*DNSConfig) Copy

          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

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

                                          type MountConfigSupport int32

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

                                            const (
                                            	MountConfigSupportAll MountConfigSupport = iota
                                            	MountConfigSupportNone
                                            )

                                            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
                                                	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
                                                	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
                                                	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 (*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