executor

package
v1.6.112 Latest Latest
Warning

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

Go to latest
Published: Aug 13, 2023 License: MPL-2.0, MPL-2.0 Imports: 60 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// ExecutorVersionLatest is the current and latest version of the executor
	ExecutorVersionLatest = "2.0.0"

	// ExecutorVersionPre0_9 is the version of executor use prior to the release
	// of 0.9.x
	ExecutorVersionPre0_9 = "1.1.0"

	// IsolationModePrivate represents the private isolation mode for a namespace
	IsolationModePrivate = "private"

	// IsolationModeHost represents the host isolation mode for a namespace
	IsolationModeHost = "host"
)
View Source
const (
	// ExecutorDefaultMaxPort is the default max port used by the executor for
	// searching for an available port
	ExecutorDefaultMaxPort = 14512

	// ExecutorDefaultMinPort is the default min port used by the executor for
	// searching for an available port
	ExecutorDefaultMinPort = 14000
)

Variables

View Source
var (
	// The statistics the basic executor exposes
	ExecutorBasicMeasuredMemStats = []string{"RSS", "Swap"}
	ExecutorBasicMeasuredCpuStats = []string{"System Mode", "User Mode", "Percent"}
)
View Source
var (
	// ExecutorCgroupV1MeasuredMemStats is the list of memory stats captured by the executor with cgroup-v1
	ExecutorCgroupV1MeasuredMemStats = []string{"RSS", "Cache", "Swap", "Usage", "Max Usage", "Kernel Usage", "Kernel Max Usage"}

	// ExecutorCgroupV2MeasuredMemStats is the list of memory stats captured by the executor with cgroup-v2. cgroup-v2 exposes different memory stats and no longer reports rss or max usage.
	ExecutorCgroupV2MeasuredMemStats = []string{"Cache", "Swap", "Usage"}

	// ExecutorCgroupMeasuredCpuStats is the list of CPU stats captures by the executor
	ExecutorCgroupMeasuredCpuStats = []string{"System Mode", "User Mode", "Throttled Periods", "Throttled Time", "Percent"}
)

Functions

func ExecScript

func ExecScript(ctx context.Context, dir string, env []string, attrs *syscall.SysProcAttr,
	netSpec *drivers.NetworkIsolationSpec, name string, args []string) ([]byte, int, error)

ExecScript executes cmd with args and returns the output, exit code, and error. Output is truncated to drivers/shared/structs.CheckBufSize

func GetPluginMap

func GetPluginMap(logger hclog.Logger, fsIsolation bool) map[string]plugin.Plugin

func IsolationMode

func IsolationMode(plugin, task string) string

IsolationMode returns the namespace isolation mode as determined from agent plugin configuration and task driver configuration. The task configuration takes precedence, if it is configured.

func SupportedCaps

func SupportedCaps(allowNetRaw bool) []string

SupportedCaps returns a list of all supported capabilities in kernel.

Types

type ExecCommand

type ExecCommand struct {
	// Cmd is the command that the user wants to run.
	Cmd string

	// Args is the args of the command that the user wants to run.
	Args []string

	// Resources defined by the task
	Resources *drivers.Resources

	// StdoutPath is the path the process stdout should be written to
	StdoutPath string

	// StderrPath is the path the process stderr should be written to
	StderrPath string

	// Env is the list of KEY=val pairs of environment variables to be set
	Env []string

	// User is the user which the executor uses to run the command.
	User string

	// TaskDir is the directory path on the host where for the task
	TaskDir string

	// ResourceLimits determines whether resource limits are enforced by the
	// executor.
	ResourceLimits bool

	// Cgroup marks whether we put the process in a cgroup. Setting this field
	// doesn't enforce resource limits. To enforce limits, set ResourceLimits.
	// Using the cgroup does allow more precise cleanup of processes.
	BasicProcessCgroup bool

	// NoPivotRoot disables using pivot_root for isolation, useful when the root
	// partition is on a ramdisk which does not support pivot_root,
	// see man 2 pivot_root
	NoPivotRoot bool

	// Mounts are the host paths to be be made available inside rootfs
	Mounts []*drivers.MountConfig

	// Devices are the the device nodes to be created in isolation environment
	Devices []*drivers.DeviceConfig

	// NetworkIsolation is the network isolation configuration.
	NetworkIsolation *drivers.NetworkIsolationSpec

	// ModePID is the PID isolation mode (private or host).
	ModePID string

	// ModeIPC is the IPC isolation mode (private or host).
	ModeIPC string

	// Capabilities are the linux capabilities to be enabled by the task driver.
	Capabilities []string
	// contains filtered or unexported fields
}

ExecCommand holds the user command, args, and other isolation related settings.

Important (!): when adding fields, make sure to update the RPC methods in grpcExecutorClient.Launch and grpcExecutorServer.Launch. Number of hours spent tracking this down: too many.

func (*ExecCommand) Close

func (c *ExecCommand) Close()

func (*ExecCommand) GetWriters

func (c *ExecCommand) GetWriters() (stdout io.WriteCloser, stderr io.WriteCloser)

GetWriters returns the unexported io.WriteCloser for the stdout and stderr handles. This is mainly used for unit testing purposes.

func (*ExecCommand) SetWriters

func (c *ExecCommand) SetWriters(out io.WriteCloser, err io.WriteCloser)

SetWriters sets the writer for the process stdout and stderr. This should not be used if writing to a file path such as a fifo file. SetStdoutWriter is mainly used for unit testing purposes.

func (*ExecCommand) Stderr

func (c *ExecCommand) Stderr() (io.WriteCloser, error)

Stderr returns a writer for the configured file descriptor

func (*ExecCommand) Stdout

func (c *ExecCommand) Stdout() (io.WriteCloser, error)

Stdout returns a writer for the configured file descriptor

type Executor

type Executor interface {
	// Launch a user process configured by the given ExecCommand
	Launch(launchCmd *ExecCommand) (*ProcessState, error)

	// Wait blocks until the process exits or an error occures
	Wait(ctx context.Context) (*ProcessState, error)

	// Shutdown will shutdown the executor by stopping the user process,
	// cleaning up and resources created by the executor. The shutdown sequence
	// will first send the given signal to the process. This defaults to "SIGINT"
	// if not specified. The executor will then wait for the process to exit
	// before cleaning up other resources. If the executor waits longer than the
	// given grace period, the process is forcefully killed.
	//
	// To force kill the user process, gracePeriod can be set to 0.
	Shutdown(signal string, gracePeriod time.Duration) error

	// UpdateResources updates any resource isolation enforcement with new
	// constraints if supported.
	UpdateResources(*drivers.Resources) error

	// Version returns the executor API version
	Version() (*ExecutorVersion, error)

	// Returns a channel of stats. Stats are collected and
	// pushed to the channel on the given interval
	Stats(context.Context, time.Duration) (<-chan *cstructs.TaskResourceUsage, error)

	// Signal sends the given signal to the user process
	Signal(os.Signal) error

	// Exec executes the given command and args inside the executor context
	// and returns the output and exit code.
	Exec(deadline time.Time, cmd string, args []string) ([]byte, int, error)

	ExecStreaming(ctx context.Context, cmd []string, tty bool,
		stream drivers.ExecTaskStream) error
}

Executor is the interface which allows a driver to launch and supervise a process

func CreateExecutor

func CreateExecutor(logger hclog.Logger, driverConfig *base.ClientDriverConfig,
	executorConfig *ExecutorConfig) (Executor, *plugin.Client, error)

CreateExecutor launches an executor plugin and returns an instance of the Executor interface

func NewExecutor

func NewExecutor(logger hclog.Logger) Executor

NewExecutor returns an Executor

func NewExecutorWithIsolation

func NewExecutorWithIsolation(logger hclog.Logger) Executor

func ReattachToExecutor

func ReattachToExecutor(reattachConfig *plugin.ReattachConfig, logger hclog.Logger) (Executor, *plugin.Client, error)

ReattachToExecutor launches a plugin with a given plugin config

type ExecutorConfig

type ExecutorConfig struct {

	// LogFile is the file to which Executor logs
	LogFile string

	// LogLevel is the level of the logs to putout
	LogLevel string

	// FSIsolation if set will use an executor implementation that support
	// filesystem isolation
	FSIsolation bool
}

ExecutorConfig is the config that Nomad passes to the executor

type ExecutorPlugin

type ExecutorPlugin struct {
	// TODO: support backwards compatibility with pre 0.9 NetRPC plugin
	plugin.NetRPCUnsupportedPlugin
	// contains filtered or unexported fields
}

func (*ExecutorPlugin) GRPCClient

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

func (*ExecutorPlugin) GRPCServer

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

type ExecutorVersion

type ExecutorVersion struct {
	Version string
}

ExecutorVersion is the version of the executor

func (*ExecutorVersion) GoString

func (v *ExecutorVersion) GoString() string

type LibcontainerExecutor

type LibcontainerExecutor struct {
	// contains filtered or unexported fields
}

LibcontainerExecutor implements an Executor with the runc/libcontainer api

func (*LibcontainerExecutor) Exec

func (l *LibcontainerExecutor) Exec(deadline time.Time, cmd string, args []string) ([]byte, int, error)

Exec starts an additional process inside the container

func (*LibcontainerExecutor) ExecStreaming

func (l *LibcontainerExecutor) ExecStreaming(ctx context.Context, cmd []string, tty bool,
	stream drivers.ExecTaskStream) error

func (*LibcontainerExecutor) Launch

func (l *LibcontainerExecutor) Launch(command *ExecCommand) (*ProcessState, error)

Launch creates a new container in libcontainer and starts a new process with it

func (*LibcontainerExecutor) Shutdown

func (l *LibcontainerExecutor) Shutdown(signal string, grace time.Duration) error

Shutdown stops all processes started and cleans up any resources created (such as mountpoints, devices, etc).

func (*LibcontainerExecutor) Signal

func (l *LibcontainerExecutor) Signal(s os.Signal) error

Signal sends a signal to the process managed by the executor

func (*LibcontainerExecutor) Stats

func (l *LibcontainerExecutor) Stats(ctx context.Context, interval time.Duration) (<-chan *cstructs.TaskResourceUsage, error)

Stats returns the resource statistics for processes managed by the executor

func (*LibcontainerExecutor) UpdateResources

func (l *LibcontainerExecutor) UpdateResources(resources *drivers.Resources) error

UpdateResources updates the resource isolation with new values to be enforced

func (*LibcontainerExecutor) Version

func (l *LibcontainerExecutor) Version() (*ExecutorVersion, error)

Version returns the api version of the executor

func (*LibcontainerExecutor) Wait

Wait waits until a process has exited and returns it's exitcode and errors

type PluginReattachConfig

type PluginReattachConfig struct {
	Pid      int
	AddrNet  string
	AddrName string
}

ExecutorReattachConfig is the config that we serialize and de-serialize and store in disk

func NewPluginReattachConfig

func NewPluginReattachConfig(c *plugin.ReattachConfig) *PluginReattachConfig

func (*PluginReattachConfig) PluginConfig

func (c *PluginReattachConfig) PluginConfig() *plugin.ReattachConfig

PluginConfig returns a config from an ExecutorReattachConfig

type ProcessState

type ProcessState struct {
	Pid      int
	ExitCode int
	Signal   int
	Time     time.Time
}

ProcessState holds information about the state of a user process.

type UniversalExecutor

type UniversalExecutor struct {
	// contains filtered or unexported fields
}

UniversalExecutor is an implementation of the Executor which launches and supervises processes. In addition to process supervision it provides resource and file system isolation

func (*UniversalExecutor) Exec

func (e *UniversalExecutor) Exec(deadline time.Time, name string, args []string) ([]byte, int, error)

Exec a command inside a container for exec and java drivers.

func (*UniversalExecutor) ExecStreaming

func (e *UniversalExecutor) ExecStreaming(ctx context.Context, command []string, tty bool,
	stream drivers.ExecTaskStream) error

func (*UniversalExecutor) Launch

func (e *UniversalExecutor) Launch(command *ExecCommand) (*ProcessState, error)

Launch launches the main process and returns its state. It also configures an applies isolation on certain platforms.

func (*UniversalExecutor) Shutdown

func (e *UniversalExecutor) Shutdown(signal string, grace time.Duration) error

Shutdown cleans up the alloc directory, destroys resource container and kills the user process.

func (*UniversalExecutor) Signal

func (e *UniversalExecutor) Signal(s os.Signal) error

Signal sends the passed signal to the task

func (*UniversalExecutor) Stats

func (e *UniversalExecutor) Stats(ctx context.Context, interval time.Duration) (<-chan *cstructs.TaskResourceUsage, error)

func (*UniversalExecutor) UpdateResources

func (e *UniversalExecutor) UpdateResources(resources *drivers.Resources) error

func (*UniversalExecutor) Version

func (e *UniversalExecutor) Version() (*ExecutorVersion, error)

Version returns the api version of the executor

func (*UniversalExecutor) Wait

Wait waits until a process has exited and returns it's exitcode and errors

Jump to

Keyboard shortcuts

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