executor

package
v0.0.0-...-6dcf2a5 Latest Latest
Warning

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

 Go to latest Published: Feb 16, 2024 License: MPL-2.0 Imports: 56 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 (
	// CPU shares limits are defined by the Linux kernel.
	// https://github.com/torvalds/linux/blob/0dd3ee31125508cd67f7e7172247f05b7fd1753a/kernel/sched/sched.h#L409-L418
	MinCPUShares = 2
	MaxCPUShares = 262_144
)
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, compute cpustats.Compute) 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

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

func (c *ExecCommand) CpusetCgroup() string

CpusetCgroup returns the path to the cgroup in which the Nomad client will write the PID of the task process for managing cpu core usage.

On cgroups v1 systems this returns the path to the cpuset cgroup specifically. Critical: is "/reserve/<id>" or "/share"; do not try to parse this!

On cgroups v2 systems this just returns the unified cgroup.

On non-Linux systems this returns the empty string and has no meaning.

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) StatsCgroup 

func (c *ExecCommand) StatsCgroup() string

StatsCgroup returns the path to the cgroup Nomad client will use to inspect for spawned process IDs.

On cgroups v1 systems this returns the path to the freezer cgroup.

On cgroups v2 systems this just returns the unified cgroup.

On non-Linux systems this returns the empty string and has no meaning.

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, compute cpustats.Compute) Executor

NewExecutor returns an Executor

func NewExecutorWithIsolation 

func NewExecutorWithIsolation(logger hclog.Logger, compute cpustats.Compute) Executor

func ReattachToExecutor 

func ReattachToExecutor(reattachConfig *plugin.ReattachConfig, logger hclog.Logger, compute cpustats.Compute) (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

	// Compute contains system cpu compute information
	Compute cpustats.Compute
}

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) ListProcesses 

func (l *LibcontainerExecutor) ListProcesses() *set.Set[int]

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 

func (l *LibcontainerExecutor) Wait(ctx context.Context) (*ProcessState, error)

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
	OOMKilled bool
	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) ListProcesses 

func (e *UniversalExecutor) ListProcesses() *set.Set[procstats.ProcessID]

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 

func (e *UniversalExecutor) Wait(ctx context.Context) (*ProcessState, error)

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

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.