Exec

The exec resource allows the execution of arbitrary commands and scripts. Depending on the parameters specified, the commands are executed either on the local machine or inside of a container.

When either the image or target fields are specified, the command is executed inside of a container. When neither of these fields are specified, the command is executed on the local machine.

Local execution

When running on the local machine, the command runs in the local user space, and has access to all the environment variables that the user executing jumppad run has access too. Additional environment variables, and the working directory for the command can be specified as part of the resource.

Log files for an exec running on the local machine are written to $HOME/.jumppad/logs/exec_[name].log and the rendered script can be found in the jumppad temp directory $HOME/.jumppad/tmp/exec[name].sh.

Remote execution

Execution can either be in a stand alone container or can target an existing and running container. When targeting an existing container, the target field must be specified. When running in a stand alone container, the image block must be specified.

Setting outputs

Output variables for the exec resource can be set by echoing a key value pair to the output file inside the script. An environment variable ${EXEC_OUTPUT} is automatically added to the environment of the script and points to the output.

Any outputs set in the script are automatically parsed into a map and are available via the output parameter.

The following example demonstrates how to set an output variable in a script.

resource "exec" "inline" {
  script = <<-EOF
  #!/bin/bash
  ls -lha

  echo "FOO=BAR" > ${EXEC_OUTPUT}
  EOF
}

output "foo" {
  value = resource.exec.inline.output.FOO
}

Properties

Name: script
Type: (string: "")
Required: required
Readonly

Description

The script to execute.

resource "exec" "inline" {
  script = <<-EOF
  #!/bin/bash
  ls -lha
  EOF
}

resource "exec" "file" {
  script = file("script.sh")
}

resource "exec" "template" {
  script = template_file("script.sh.tpl", {
    foo = "bar"
  })
}

Name
working_directory
Type
(string: "")
Required
Readonly
Description
The working directory to execute the script in.
Name
timeout
Type
(string: 300s)
Required
Readonly
Description
The timeout for the script to execute as a duration e.g. 30s.

Name: environment
Type: (map[string]string: map[]{})
Required
Readonly

Description

Environment variables to set for the script.

resource "exec" "env" {
  environment = {
    FOO = "bar"
  }

  script = <<-EOF
  #!/bin/bash
  echo $${FOO}
  EOF
}

Name
output
Type
(map[string]string: map[]{})
Required
Readonly
readonly
Description
Map of output variables set by echoing key value pairs to the output file from the execs script.
resource "exec" "inline" { script = <<-EOF echo "FOO=BAR" > ${EXEC_OUTPUT} EOF }
Name
exit_code
Type
(int: )
Required
Readonly
readonly
Description
The exit code returned by the executed script.
Name
checksum
Type
(string: "")
Required
Readonly
readonly
Description
A checksum of the script content used to determine if the script has changed.

The following properties are only valid for local execution.

Name
daemon
Type
(bool: false)
Required
Readonly
Description
The process will be run as a daemon if set to true.
Name
pid
Type
(int: )
Required
Readonly
readonly
Description
This is the pid of the parent process.

The following properties are only valid for remote execution in a target container.

Name: target
Type: (ref: )
Required
Readonly

Description

A reference to a target container resource to execute the script in.

resource "container" "alpine" {
  image {
    name = "alpine"
  }
}

resource "exec" "uname" {
  target = resource.container.alpine

  script = <<-EOF
  #!/bin/bash
  uname -a
  EOF
}

The following properties are only valid for remote execution in a standalone container.

Name
image
Type
(image: {})
Required
Readonly
Description
The image to use for the container.
Name
network
Type
(network_attachment: {})
Required
Readonly
Description
The network to attach the container to.
Name
volume
Type
(volume: {})
Required
Readonly
Description
The volumes to mount to the container.
Name
run_as
Type
(user: {})
Required
Readonly
Description
The user to run the script as.

image

Image defines a Docker image used when creating this container. An Image can be stored in a public or a private repository.

Name
name
Type
(string: "")
Required
required
Readonly
Description
Name of the image to use when creating the container, can either be the full canonical name or short name for Docker official images. e.g. consul:v1.6.1 or docker.io/consul:v1.6.1.
Name
username
Type
(string: "")
Required
Readonly
Description
Username to use when connecting to a private image repository
Name
password
Type
(string: "")
Required
Readonly
Description
Password to use when connecting to a private image repository, for both username and password interpolated environment variables can be used in place of static values.
image { name = "myregistry.io/myimage:latest" username = env("REGISTRY_USERNAME") password = env("REGISTRY_PASSWORD") }

network_attachment

Network attachment defines a network to which the container is attached.

Name
id
Type
(string: "")
Required
required
Readonly
Description
ID of the network to attach the container to, specified in reference format. e.g. to attach to a network called cloud
network { id = "network.cloud" }
Name
ip_address
Type
(string: "")
Required
Readonly
Description
Static IP address to assign container for the network, the ip address must be within range defined by the network subnet. If this parameter is omitted an IP address will be automatically assigned.
Name
aliases
Type
([]string: [])
Required
Readonly
Description
Aliases allow alternate names to specified for the container. Aliases can be used to reference a container across the network, the container will respond to ping and other network resolution using the primary assigned name [name].container.shipyard.run and the aliases.
network { name = "network.cloud" aliases = [ "alt1.container.local.jmpd.in", "alt2.container.local.jmpd.in" ] }
Name
name
Type
(string: "")
Required
Readonly
readonly
Description
Name will equal the name of the network as created by jumppad.
Name
assigned_address
Type
(string: "")
Required
Readonly
readonly
Description
assigned_address will equal the assigned IP address for the network. This will equal ip_address if set; otherwise, this is the automatically assigned ip_address.

volume

A volume type allows the specification of an attached volume.

Name
source
Type
(string: "")
Required
required
Readonly
Description
The source volume to mount in the container, can be specified as a relative ./ or absolute path /usr/local/bin. Relative paths are relative to the file declaring the container.
Name
destination
Type
(string: "")
Required
required
Readonly
Description
The destination in the container to mount the volume to, must be an absolute path.
Name
type
Type
(string: bind)
Required
Readonly
Description
The type of the mount, can be one of the following values:
- bind: bind the source path to the destination path in the container
- volume: source is a Docker volume
- tmpfs: create a temporary filesystem
Name
bind_propagation
Type
(string: rprivate)
Required
Readonly
Description
Configures bind propagation for Docker volume mounts, only applies to bind mounts, can be one of the following values:
- shared
- slave
- private
- rslave
- rprivate
For more information please see the Docker documentation https://docs.docker.com/storage/bind-mounts/#configure-bind-propagation
Name
bind_propagation_non_recursive
Type
(boolean: false)
Required
Readonly
Description
Configures recursiveness of the bind mount. By default Docker mounts with the equivalent of mount --rbind meaning that mounts below the the source directory are visible in the container. For instance running docker run --rm --mount type=bind,src=/,target=/host,readonly busybox will make /run of the host available as /host/run in the container -- and to make matters even worse it will be writable (since only the toplevel bind is set readonly, not the children). If bind_propagation_non_recursive is set to true then the container will only see an empty /host/run, meaning the tmpfs which is typically mounted to /run on the host is not propagated into the container.
Name
selinux_relabel
Type
(string: "")
Required
Readonly
Description
Configures Selinux relabeling for the container (usually specified as :z or :Z) and can be one of the following values:
- shared (Equivalent to :z)
- private (Equivalent to :Z)

run_as

User and Group configuration to be used when running a container, by default Docker runs commands in the container as root id 0.

Name
user
Type
(string: "")
Required
Readonly
Description
Linux user ID or user name to run the container as, this overrides the default user configured in the container image.
Name
group
Type
(string: "")
Required
Readonly
Description
Linux group ID or group name to run the container as, this overrides the default group configured in the container image.

Meta Properties

In addition to the main properties, all resources have meta properties, such as the id of the resource. To see the list of these properties please see the Meta Properties section in the documentation /docs/resources/meta.

Examples

resource "exec" "install" {
  script = <<-EOF
  #!/bin/sh
  OS=$(uname -s | tr '[:upper:]' '[:lower:]')
  ARCH=$(uname -m | tr '[:upper:]' '[:lower:]')

  if [ ! -f /tmp/consul ]; then
    curl -L -o /tmp/consul.zip \
      https://releases.hashicorp.com/consul/1.16.2/consul_1.16.2_$${OS}_$${ARCH}.zip
    cd /tmp && unzip ./consul.zip
  fi
  EOF
}

resource "exec" "run" {
  depends_on = ["resource.exec.install"]

  script = <<-EOF
  #!/bin/sh
  /tmp/consul agent -dev
  EOF

  daemon = true
}

resource "container" "alpine" {
  image {
    name = "alpine"
  }

  command = ["tail", "-f", "/dev/null"]
}

resource "exec" "in_container" {
  target = resource.container.alpine

  script = <<-EOF
  #/bin/sh
  ls -las
  EOF
}

resource "exec" "standalone" {
  image {
    name = "alpine"
  }

  script = <<-EOF
  #/bin/sh
  ls -las
  EOF
}