taskenv

Documentation

Index

• Constants
• Variables
• func InterpolateNetworks(taskEnv *TaskEnv, networks structs.Networks) structs.Networks
• func InterpolateServices(taskEnv *TaskEnv, services []*structs.Service) []*structs.Service
• func SetPortMapEnvs(envs map[string]string, ports map[string]int) map[string]string
• type Builder
  • func NewBuilder(node *structs.Node, alloc *structs.Allocation, task *structs.Task, ...) *Builder
  • func NewEmptyBuilder() *Builder
  • func (b *Builder) Build() *TaskEnv
  • func (b *Builder) SetAllocDir(dir string) *Builder
  • func (b *Builder) SetClientSharedAllocDir(dir string) *Builder
  • func (b *Builder) SetClientTaskLocalDir(dir string) *Builder
  • func (b *Builder) SetClientTaskRoot(dir string) *Builder
  • func (b *Builder) SetClientTaskSecretsDir(dir string) *Builder
  • func (b *Builder) SetDeviceHookEnv(hookName string, envs map[string]string) *Builder
  • func (b *Builder) SetDriverNetwork(n *drivers.DriverNetwork) *Builder
  • func (b *Builder) SetHookEnv(hook string, envs map[string]string) *Builder
  • func (b *Builder) SetHostEnvvars(filter []string) *Builder
  • func (b *Builder) SetSecretsDir(dir string) *Builder
  • func (b *Builder) SetTaskLocalDir(dir string) *Builder
  • func (b *Builder) SetTemplateEnv(m map[string]string) *Builder
  • func (b *Builder) SetUpstreams(upstreams []structs.ConsulUpstream) *Builder
  • func (b *Builder) SetVaultToken(token, namespace string, inject bool) *Builder
  • func (b *Builder) UpdateTask(alloc *structs.Allocation, task *structs.Task) *Builder
• type TaskEnv
  • func NewEmptyTaskEnv() *TaskEnv
  • func NewTaskEnv(env, envClient, deviceEnv, node map[string]string, ...) *TaskEnv
  • func (t *TaskEnv) All() map[string]string
  • func (t *TaskEnv) AllValues() (map[string]cty.Value, map[string]error, error)
  • func (t *TaskEnv) ClientPath(rawPath string, joinEscape bool) (string, bool)
  • func (t *TaskEnv) DeviceEnv() map[string]string
  • func (t *TaskEnv) List() []string
  • func (t *TaskEnv) Map() map[string]string
  • func (t *TaskEnv) ParseAndReplace(args []string) []string
  • func (t *TaskEnv) ReplaceEnv(arg string) string

Constants

const (
	// AllocDir is the environment variable with the path to the alloc directory
	// that is shared across tasks within a task group.
	AllocDir = "NOMAD_ALLOC_DIR"

	// TaskLocalDir is the environment variable with the path to the tasks local
	// directory where it can store data that is persisted to the alloc is
	// removed.
	TaskLocalDir = "NOMAD_TASK_DIR"

	// SecretsDir is the environment variable with the path to the tasks secret
	// directory where it can store sensitive data.
	SecretsDir = "NOMAD_SECRETS_DIR"

	// MemLimit is the environment variable with the tasks memory limit in MBs.
	MemLimit = "NOMAD_MEMORY_LIMIT"

	// MemMaxLimit is the environment variable with the tasks maximum memory limit in MBs.
	MemMaxLimit = "NOMAD_MEMORY_MAX_LIMIT"

	// CpuLimit is the environment variable with the tasks CPU limit in MHz.
	CpuLimit = "NOMAD_CPU_LIMIT"

	// CpuCores is the environment variable for passing the task's reserved cpu cores
	CpuCores = "NOMAD_CPU_CORES"

	// AllocID is the environment variable for passing the allocation ID.
	AllocID = "NOMAD_ALLOC_ID"

	// ShortAllocID is the environment variable for passing the short version
	// of the allocation ID.
	ShortAllocID = "NOMAD_SHORT_ALLOC_ID"

	// AllocName is the environment variable for passing the allocation name.
	AllocName = "NOMAD_ALLOC_NAME"

	// TaskName is the environment variable for passing the task name.
	TaskName = "NOMAD_TASK_NAME"

	// GroupName is the environment variable for passing the task group name.
	GroupName = "NOMAD_GROUP_NAME"

	// JobID is the environment variable for passing the job ID.
	JobID = "NOMAD_JOB_ID"

	// JobName is the environment variable for passing the job name.
	JobName = "NOMAD_JOB_NAME"

	// JobParentID is the environment variable for passing the ID of the parnt of the job
	JobParentID = "NOMAD_JOB_PARENT_ID"

	// AllocIndex is the environment variable for passing the allocation index.
	AllocIndex = "NOMAD_ALLOC_INDEX"

	// Datacenter is the environment variable for passing the datacenter in which the alloc is running.
	Datacenter = "NOMAD_DC"

	// CgroupParent is the environment variable for passing the cgroup parent in which cgroups are made.
	CgroupParent = "NOMAD_PARENT_CGROUP"

	// Namespace is the environment variable for passing the namespace in which the alloc is running.
	Namespace = "NOMAD_NAMESPACE"

	// Region is the environment variable for passing the region in which the alloc is running.
	Region = "NOMAD_REGION"

	// AddrPrefix is the prefix for passing both dynamic and static port
	// allocations to tasks.
	// E.g $NOMAD_ADDR_http=127.0.0.1:80
	//
	// The ip:port are always the host's.
	AddrPrefix = "NOMAD_ADDR_"

	HostAddrPrefix = "NOMAD_HOST_ADDR_"

	// IpPrefix is the prefix for passing the host IP of a port allocation
	// to a task.
	IpPrefix = "NOMAD_IP_"

	HostIpPrefix = "NOMAD_HOST_IP_"

	// PortPrefix is the prefix for passing the port allocation to a task.
	// It will be the task's port if a port map is specified. Task's should
	// bind to this port.
	PortPrefix = "NOMAD_PORT_"

	AllocPortPrefix = "NOMAD_ALLOC_PORT_"

	// HostPortPrefix is the prefix for passing the host port when a port
	// map is specified.
	HostPortPrefix = "NOMAD_HOST_PORT_"

	// MetaPrefix is the prefix for passing task meta data.
	MetaPrefix = "NOMAD_META_"

	// UpstreamPrefix is the prefix for passing upstream IP and ports to the alloc
	UpstreamPrefix = "NOMAD_UPSTREAM_"

	// VaultToken is the environment variable for passing the Vault token
	VaultToken = "VAULT_TOKEN"

	// VaultNamespace is the environment variable for passing the Vault namespace, if applicable
	VaultNamespace = "VAULT_NAMESPACE"
)

A set of environment variables that are exported by each driver.

Variables

var (
	// ErrInvalidObjectPath is returned when a key cannot be converted into
	// a nested object path like "foo...bar", ".foo", or "foo."
	ErrInvalidObjectPath = errors.New("invalid object path")
)

Functions

func InterpolateNetworks

func InterpolateNetworks(taskEnv *TaskEnv, networks structs.Networks) structs.Networks

InterpolateNetworks returns an interpolated copy of the task group networks with values from the task's environment.

Current interoperable fields:

• Hostname
• DNS

func InterpolateServices

func InterpolateServices(taskEnv *TaskEnv, services []*structs.Service) []*structs.Service

InterpolateServices returns an interpolated copy of services and checks with values from the task's environment.

func SetPortMapEnvs

func SetPortMapEnvs(envs map[string]string, ports map[string]int) map[string]string

SetPortMapEnvs sets the PortMap related environment variables on the map

Types

type Builder

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

Builder is used to build task environment's and is safe for concurrent use.

func NewBuilder

func NewBuilder(node *structs.Node, alloc *structs.Allocation, task *structs.Task, region string) *Builder

NewBuilder creates a new task environment builder.

func NewEmptyBuilder

func NewEmptyBuilder() *Builder

NewEmptyBuilder creates a new environment builder.

func (*Builder) Build

func (b *Builder) Build() *TaskEnv

Build must be called after all the tasks environment values have been set.

func (*Builder) SetAllocDir

func (b *Builder) SetAllocDir(dir string) *Builder

func (*Builder) SetClientSharedAllocDir

func (b *Builder) SetClientSharedAllocDir(dir string) *Builder

func (*Builder) SetClientTaskLocalDir

func (b *Builder) SetClientTaskLocalDir(dir string) *Builder

func (*Builder) SetClientTaskRoot

func (b *Builder) SetClientTaskRoot(dir string) *Builder

func (*Builder) SetClientTaskSecretsDir

func (b *Builder) SetClientTaskSecretsDir(dir string) *Builder

func (*Builder) SetDeviceHookEnv

func (b *Builder) SetDeviceHookEnv(hookName string, envs map[string]string) *Builder

SetDeviceHookEnv sets environment variables from a device hook. Variables are Last-Write-Wins, so if a hook writes a variable that's also written by a later hook, the later hooks value always gets used.

func (*Builder) SetDriverNetwork

func (b *Builder) SetDriverNetwork(n *drivers.DriverNetwork) *Builder

SetDriverNetwork defined by the driver.

func (*Builder) SetHookEnv

func (b *Builder) SetHookEnv(hook string, envs map[string]string) *Builder

SetHookEnv sets environment variables from a hook. Variables are Last-Write-Wins, so if a hook writes a variable that's also written by a later hook, the later hooks value always gets used.

func (*Builder) SetHostEnvvars

func (b *Builder) SetHostEnvvars(filter []string) *Builder

SetHostEnvvars adds the host environment variables to the tasks. The filter parameter can be use to filter host environment from entering the tasks.

func (*Builder) SetSecretsDir

func (b *Builder) SetSecretsDir(dir string) *Builder

func (*Builder) SetTaskLocalDir

func (b *Builder) SetTaskLocalDir(dir string) *Builder

func (*Builder) SetTemplateEnv

func (b *Builder) SetTemplateEnv(m map[string]string) *Builder

func (*Builder) SetUpstreams

func (b *Builder) SetUpstreams(upstreams []structs.ConsulUpstream) *Builder

SetUpstreams defined by connect enabled group services

func (*Builder) SetVaultToken

func (b *Builder) SetVaultToken(token, namespace string, inject bool) *Builder

func (*Builder) UpdateTask

func (b *Builder) UpdateTask(alloc *structs.Allocation, task *structs.Task) *Builder

UpdateTask updates the environment based on a new alloc and task.

type TaskEnv

type TaskEnv struct {
	// NodeAttrs is the map of node attributes for interpolation
	NodeAttrs map[string]string

	// EnvMap is the map of environment variables
	EnvMap map[string]string

	// EnvMap is the map of environment variables with client-specific
	// task directories
	// See https://github.com/hashicorp/nomad/pull/9671
	EnvMapClient map[string]string
	// contains filtered or unexported fields
}

TaskEnv is a task's environment as well as node attribute's for interpolation.

func NewEmptyTaskEnv

func NewEmptyTaskEnv() *TaskEnv

NewEmptyTaskEnv creates a new empty task environment.

func NewTaskEnv

func NewTaskEnv(env, envClient, deviceEnv, node map[string]string, clientTaskDir, clientAllocDir string) *TaskEnv

NewTaskEnv creates a new task environment with the given environment, device environment and node attribute maps.

func (*TaskEnv) All

func (t *TaskEnv) All() map[string]string

All of the task's environment variables and the node's attributes in a single map.

func (*TaskEnv) AllValues

func (t *TaskEnv) AllValues() (map[string]cty.Value, map[string]error, error)

AllValues is a map of the task's environment variables and the node's attributes with cty.Value (String) values. Errors including keys are returned in a map by key name.

In the rare case of a fatal error, only an error value is returned. This is likely a programming error as user input should not be able to cause a fatal error.

func (*TaskEnv) ClientPath

func (t *TaskEnv) ClientPath(rawPath string, joinEscape bool) (string, bool)

ClientPath interpolates the argument as a path, using the environment variables with client-relative directories. The result is an absolute path on the client filesystem.

If the interpolated result is a relative path, it is made absolute If joinEscape, an interpolated path that escapes will be joined with the task dir. The result is checked to see whether it (still) escapes both the task working directory and the shared allocation directory.

func (*TaskEnv) DeviceEnv

func (t *TaskEnv) DeviceEnv() map[string]string

DeviceEnv returns the task's environment variables set by device hooks.

func (*TaskEnv) List

func (t *TaskEnv) List() []string

List returns the task's environment as a slice of NAME=value pair strings.

func (*TaskEnv) Map

func (t *TaskEnv) Map() map[string]string

Map of the task's environment variables.

func (*TaskEnv) ParseAndReplace

func (t *TaskEnv) ParseAndReplace(args []string) []string

ParseAndReplace takes the user supplied args replaces any instance of an environment variable or Nomad variable in the args with the actual value.

func (*TaskEnv) ReplaceEnv

func (t *TaskEnv) ReplaceEnv(arg string) string

ReplaceEnv takes an arg and replaces all occurrences of environment variables and Nomad variables. If the variable is found in the passed map it is replaced, otherwise the original string is returned.