executor

Documentation

Overview

Package exec is used to invoke child processes across various platforms to provide the following features:

- Least privilege - Resource constraints - Process isolation

A "platform" may be defined as coarsely as "Windows" or as specifically as "linux 3.20 with systemd". This allows Nomad to use best-effort, best- available capabilities of each platform to provide resource constraints, process isolation, and security features, or otherwise take advantage of features that are unique to that platform.

The `semantics of any particular instance are left up to the implementation. However, these should be completely transparent to the calling context. In other words, the Java driver should be able to call exec for any platform and just work.

Index

• type Executor
  • func Command(name string, arg ...string) Executor
  • func NewExecutor() Executor
  • func OpenId(id string) (Executor, error)
• type LinuxExecutor
  • func (e *LinuxExecutor) Command() *cmd
  • func (e *LinuxExecutor) ConfigureTaskDir(taskName string, alloc *allocdir.AllocDir) error
  • func (e *LinuxExecutor) ForceStop() error
  • func (e *LinuxExecutor) ID() (string, error)
  • func (e *LinuxExecutor) Limit(resources *structs.Resources) error
  • func (e *LinuxExecutor) Open(id string) error
  • func (c *LinuxExecutor) SetGID(groupid string) error
  • func (c *LinuxExecutor) SetUID(userid string) error
  • func (e *LinuxExecutor) Shutdown() error
  • func (e *LinuxExecutor) Start() error
  • func (e *LinuxExecutor) Wait() error

Types

type Executor

type Executor interface {
	// Limit must be called before Start and restricts the amount of resources
	// the process can use. Note that an error may be returned ONLY IF the
	// executor implements resource limiting. Otherwise Limit is ignored.
	Limit(*structs.Resources) error

	// ConfigureTaskDir must be called before Start and ensures that the tasks
	// directory is properly configured.
	ConfigureTaskDir(taskName string, alloc *allocdir.AllocDir) error

	// Start the process. This may wrap the actual process in another command,
	// depending on the capabilities in this environment. Errors that arise from
	// Limits or Runas may bubble through Start()
	Start() error

	// Open should be called to restore a previous execution. This might be needed if
	// nomad is restarted.
	Open(string) error

	// Wait waits till the user's command is completed.
	Wait() error

	// Returns a handle that is executor specific for use in reopening.
	ID() (string, error)

	// Shutdown should use a graceful stop mechanism so the application can
	// perform checkpointing or cleanup, if such a mechanism is available.
	// If such a mechanism is not available, Shutdown() should call ForceStop().
	Shutdown() error

	// ForceStop will terminate the process without waiting for cleanup. Every
	// implementations must provide this.
	ForceStop() error

	// Command provides access the underlying Cmd struct in case the Executor
	// interface doesn't expose the functionality you need.
	Command() *cmd
}

Executor is an interface that any platform- or capability-specific exec wrapper must implement. You should not need to implement a Java executor. Rather, you would implement a cgroups executor that the Java driver will use.

func Command

func Command(name string, arg ...string) Executor

Command is a mirror of exec.Command that returns a platform-specific Executor

func NewExecutor

func NewExecutor() Executor

func OpenId

func OpenId(id string) (Executor, error)

OpenId is similar to executor.Command but will attempt to reopen with the passed ID.

type LinuxExecutor

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

Linux executor is designed to run on linux kernel 2.8+.

func (*LinuxExecutor) Command

func (e *LinuxExecutor) Command() *cmd

func (*LinuxExecutor) ConfigureTaskDir

func (e *LinuxExecutor) ConfigureTaskDir(taskName string, alloc *allocdir.AllocDir) error

func (*LinuxExecutor) ForceStop

func (e *LinuxExecutor) ForceStop() error

func (*LinuxExecutor) ID

func (e *LinuxExecutor) ID() (string, error)

If cgroups are used, the ID is the cgroup structurue. Otherwise, it is the PID of the spawn-daemon process. An error is returned if the process was never started.

func (*LinuxExecutor) Limit

func (e *LinuxExecutor) Limit(resources *structs.Resources) error

func (*LinuxExecutor) Open

func (e *LinuxExecutor) Open(id string) error

Open's behavior is to kill all processes associated with the id and return an error. This is done because it is not possible to re-attach to the spawn-daemon's stdout to retrieve status messages.

func (*LinuxExecutor) SetGID

func (c *LinuxExecutor) SetGID(groupid string) error

SetGID changes the Gid for this command (must be set before starting)

func (*LinuxExecutor) SetUID

func (c *LinuxExecutor) SetUID(userid string) error

SetUID changes the Uid for this command (must be set before starting)

func (*LinuxExecutor) Shutdown

func (e *LinuxExecutor) Shutdown() error

func (*LinuxExecutor) Start

func (e *LinuxExecutor) Start() error

func (*LinuxExecutor) Wait

func (e *LinuxExecutor) Wait() error