Exec

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.

resource "exec" "name" {
  ...
}

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.

Attributes

Attribute	Description
Script script required type: string	The script to execute. script = <<-EOF #!/bin/bash ls -lha EOF script = file("script.sh") script = template_file("script.sh.tpl", { foo = "bar" })
WorkingDirectory working_directory type: string	The working directory to execute the script in. working_directory = "/tmp"
Daemon daemon type: bool	The process will be run as a daemon if set to true. Only valid for local execution. daemon = true
Timeout timeout type: string	The timeout for the script to execute as a duration e.g. 30s. timeout = "60s"
Environment environment type: map[string]string	Environment variables to set for the script. resource "exec" "env" { environment = { FOO = "bar" } script = <<-EOF #!/bin/bash echo $${FOO} EOF }
Image image type: block Image	The image to use for the container. Only valid for remote execution in a standalone container. image { name = "redis:latest" }
Target target type: Reference to Container	A reference to a target container resource to execute the script in. Only valid for remote execution in an existing container. target = resource.container.alpine
Networks network type: []block NetworkAttachment	The network to attach the container to. Only valid for remote execution in an existing container. network { id = resource.network.main.meta.id }
Volumes volume type: []block Volume	The volumes to mount to the container. Only valid for remote execution in an existing container. volume { source = "./files" destination = "/tmp/files" }
RunAs run_as type: block User	The user to run the script as. Only valid for remote execution in an existing container. run_as = "root"
ExitCode exit_code type: int	The exit code the script completed with.
Output output type: map[string]string	Any console output that the script outputs.

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute	Description
Meta ID meta.id string	The full ID of the resource e.g. `resource.type.name`. This is computed from the full resource path: // given the following resource resource "container" "ubuntu" { ... } // the resulting id will be resource.container.ubuntu
Meta Type meta.type string	The type of the resource. This taken from the type label of the resource definition. // given the following resource resource "container" "ubuntu" { ... } // the resulting type will be container
Meta Name meta.name string	The name of the resource. This taken from the name label of the resource definition. // given the following resource resource "container" "ubuntu" { ... } // the resulting name will be ubuntu
PID pid type: int	This is the pid of the parent process. Only valid for local execution.

---

Image

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

container {
  image {
    ...
  }
}

Attributes

Attribute	Description
Name name required type: string	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 = "redis:latest"
Username username type: string	Username to use when connecting to a private image repository username = "my_username"
Password password type: string	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. password = "my_password"

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute	Description
ID id type: string	ID is the unique identifier for the image, this is independent of tag and changes each time the image is built. An image that has been tagged multiple times also shares the same ID. ID string `hcl:"id,optional" json:"id,omitempty"`

---

NetworkAttachment

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

network {
  ...
}

Attributes

Attribute	Description
ID id required type: string	ID of the network to attach the container to, specified in reference format. e.g. to attach to a network called `cloud`. id = resource.network.main.meta.id
IPAddress ip_address type: string	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. ip_address = "10.0.5.24"
Aliases aliases type: []string	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. aliases = [ "alt1.container.local.jmpd.in", "alt2.container.local.jmpd.in" ]

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Attribute	Description
Name name type: string	Name will equal the name of the network as created by jumppad.
AssignedAddress assigned_address type: string	`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.

container {
  volume {
    ...
  }
}

Attributes

Attribute	Description
Source source required type: string	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. source = "./files/nginx"
Destination destination required type: string	The destination in the container to mount the volume to, must be an absolute path. destination = "/etc/nginx"
Type type type: string	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 type = "bind"
ReadOnly read_only type: bool	Whether or not the volume is read only. read_only = true
BindPropagation bind_propagation type: string	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 bind_propagation = "shared"
BindPropagationNonRecursive bind_propagation_non_recursive type: bool	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. or 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. 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 thetmpfs which is typically mounted to /run on the host is not propagated into the container. bind_propagation_non_recursive = true
SelinuxRelabel selinux_relabel type: string	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) selinux_relabel = "shared"

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

---

User

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

user {
  ...
}

Attributes

Attribute	Description
User user required type: string	Linux user ID or user name to run the container as, this overrides the default user configured in the container image. user = "root"
Group group required type: string	Linux group ID or group name to run the container as, this overrides the default group configured in the container image. group = "root"

Computed Attributes

These attributes are computed when the config is parsed and applied, and are therefore only known at parsetime or runtime.

Examples

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

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

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

Local

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
}

Remote

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
}