Configuring Options to Run Your Container

When you create an instance or an instance template to use for running containers on Compute Engine, specify the container configuration using the Google Cloud Platform Console or the gcloud command line tool.

Note: The following sections describe how to configure options for VM instances but you can configure these options when creating an instance template as well. To configure the following options for instance templates, use the Advanced container options section on the Create an instance template page in the console or use the gcloud compute instance-templates create-with-container command in the examples below.

Before you begin

• If you want to use the command-line examples in this guide:
  1. Install or update to the latest version of the gcloud command-line tool.
  2. Set a default region and zone.
• If you aren't familiar with Containers, read What are containers and their benefits.
• If you aren't familiar with Docker, read the Docker documentation.
• Read about Deploying containers on Compute Engine.

Specifying restart policy

You can set restart policy to specify whether to restart a container on exit. The default policy is to always restart. You can also set the policy to restart on failure or to never restart.

Note: This is similar to --restart flag of docker run command. Repeated attempts to restart a container are driven by the default Docker behavior, as specified in the Docker --restart reference.

Console

1. Go to the VM instances page.

   Go to the VM instances page

2. Click the Create instance button to create a new instance.
3. Under the Container section, specify the desired restart policy.

gcloud

Use --container-restart-policy flag to specify container restart policy:

• always (default)
• on-failure
• never

The following example launches a container with on-failure restart policy, which means the restart only happens when the container exit code is non-zero:

gcloud compute instances create-with-container busybox-vm \
    --container-image docker.io/busybox:1.27 \
    --container-restart-policy on-failure

Use the gcloud compute instances update-container command with the --container-restart-policy flag the restart policy for a container running on a VM.

Running a container in privileged mode

You can run a container in privileged mode to allow access to all devices on the host. Containers are run as "unprivileged" by default and are not allowed to access any devices.

Note: This is equivalent of --privileged flag of the docker run command. Learn about container runtime privilege.

Console

1. Go to the VM instances page.

   Go to the VM instances page

2. Click the Create instance button to create a new instance.
3. Under the Container section, check Deploy container image.
4. Click Advanced container options.
5. Check Run as privileged.

gcloud

Use the --container-privileged flag to run a container with runtime privilege. The following example launches a busybox container in privileged mode:

gcloud compute instances create-with-container busybox-vm \
   --container-image docker.io/busybox:1.27 \
   --container-privileged

Use the gcloud compute instances update-container command with --container-privileged flag to update a container on a VM. Use --no-container-privileged flag to turn off privileged mode.

Allocating a buffer for STDIN in the container runtime

You can allocate a buffer for STDIN in the container runtime to keep the STDIN stream open in a container. If this is not set, reads from STDIN in the container will always result in EOF.

Keeping STDIN stream open is necessary for establishing an interactive shell in the container (alongside with allocating a pseudo-TTY) and for the container to be able to receive its standard input from a pipe.

Note: This is equivalent of --interactive (-i) flag of docker run command. Learn about the --interactive flag.

Console

1. Go to the VM instances page.

   Go to the VM instances page

2. Click the Create instance button to create a new instance.
3. Under the Container section, check Deploy container image.
4. Click Advanced container options.
5. Check Allocate a buffer for STDIN.

gcloud

Use --container-stdin flag to allocate a buffer for STDIN in the container runtime. The following example starts a container and keeps its STDIN open:

gcloud compute instances create-with-container busybox-vm \
    --container-image docker.io/busybox:1.27 \
    --container-stdin

Use gcloud compute instances update-container command with --container-stdin flag to update a container on a VM. Use --no-container-stdin flag to turn off allocation of a buffer for STDIN.

Allocating a pseudo-TTY

Allocating a pseudo-TTY for a container is necessary for establishing an interactive shell in the container (alongside with allocating a buffer for STDIN).

Note: This is equivalent of --tty (-t) flag of docker run command. Learn about the --tty flag.

Console

1. Go to the VM instances page.

   Go to the VM instances page

2. Click the Create instance button to create a new instance.
3. Under the Container section, check Deploy container image.
4. Click Advanced container options.
5. Check Allocate a pseudo-TTY.

gcloud

Use --container-tty flag to allocate a pseudo-TTY. The following example launches a container and allocates a pseudo-TTY:

 gcloud compute instances create-with-container busybox-vm \
    --container-image docker.io/busybox:1.27 \
    --container-stdin \
    --container-tty

Use the gcloud compute instances update-container command with --container-tty flag to update a container on a VM. Use --no-container-tty flag to not allocate a pseudo-TTY.

Overriding default command to execute on container startup

The ENTRYPOINT of a container image specifies what executable to run when the container starts and allows you to run the container as if it were that binary.

You can override the ENTRYPOINT command of the container image.

Note: This is similar to --entrypoint flag (command only, no arguments) of docker run command. Learn about ENTRYPOINT and --entrypoint flag.

Console

1. Go to the VM instances page.

   Go to the VM instances page

2. Click the Create instance button to create a new instance.
3. Under the Container section, check Deploy container image.
4. Click Advanced container options.
5. In the Command box, enter a single executable command without parameters, for example: uptime.

gcloud

Use --container-command flag to override container image ENTRYPOINT. The following example runs uptime command in a busybox container to display the time since the last boot:

gcloud compute instances create-with-container busybox-vm \
   --container-image docker.io/busybox:1.27 \
   --container-command "uptime"

Use the gcloud compute instances update-container command with the --container-command flag to update a command for a container on a VM.

Use the --clear-container-command flag with the update-container command to clear the default command for the updated container.

Passing arguments to container ENTRYPOINT command

You can pass (append) arguments to container ENTRYPOINT command or override the default container CMD command.

Note: This is similar to passing arguments to an entrypoint in [ARG...] section of docker run [OPTIONS] IMAGE [COMMAND] [ARG...] command. Learn about ENTRYPOINT and --entrypoint flag.

Console

1. Go to the VM instances page.

   Go to the VM instances page

2. Click the Create instance button to create a new instance.
3. Under the Container section, check Deploy container image.
4. Click Advanced container options.
5. Under Command arguments, click Add argument.
6. Enter one command argument per box.

gcloud

Use --container-arg flag to pass arguments to container image ENTRYPOINT command. Use a separate flag for each argument.

The following example runs the /bin/ash command with -c ‘ls -l’ arguments in a container that has been set up to automatically run busybox:

gcloud compute instances create-with-container busybox-vm \
   --container-image docker.io/busybox:1.27 \
   --container-command "/bin/ash" \
   --container-arg="-c" \
   --container-arg="ls -l"

Note: Make sure to use ‘=’ with the --container-arg flag to ensure proper argument parsing. For example: --container-arg=[ARG].

Use the gcloud compute instances update-container command with the --container-arg flags to update command arguments for a container running on a VM. The update replaces the entire argument list with the new list.

Use --clear-container-args flag with the update-container command to remove all arguments from container declaration.

Setting environment variables

You can set environment variables in a container. Only the last value of [KEY] is taken when the [KEY] is repeated more than once.

Note: This is equivalent of the --env flag of the docker run command. Learn how Docker engine allows setting environment variables.

Console

1. Go to the VM instances page.

   Go to the VM instances page

2. Click the Create instance button to create a new instance.
3. Under the Container section, check Deploy container image.
4. Click Advanced container options.
5. Under Environment variables, click Add variable.
6. Add or remove environment variables as necessary, one per line.

gcloud

Use the --container-env flag to set environment variables in a container. The following example sets three environment variables: HOME, MODE, and OWNER:

gcloud compute instances create-with-container busybox-vm \
    --container-image docker.io/busybox:1.27 \
    --container-env HOME=/home,MODE=test,OWNER=admin

Use the --container-env-file flag to set environment variables from a local file. The following example sets the two environment variables from the env.txt file:

gcloud compute instances create-with-container busybox-vm \
    --container-image docker.io/busybox:1.27 \
    --container-env-file ./env.txt

The contents of the env.txt file are:

# this is a comment
HOME=/home
MODE=test
OWNER=admin

Use the gcloud compute instances update-container command with the --container-env or --container-env-file flag to update environment variables for a container on a VM. This will update any variables present in the VM instance's container declaration. Variables that are not in the container declaration are added.

Use --remove-container-env flag to remove environment variables when updating a container on a VM. The following example removes the environment variables called MODE and OWNER:

gcloud compute instances update-container busybox-vm \
    --remove-container-env MODE,OWNER

If a specified environment variable does not exist, it is silently ignored.

Mounting a host directory as a data volume

You can mount a directory from a host VM into a container.

Note: This is equivalent of the --volume flag and the --mount flag with mount type=bind of the docker run command. Learn how Docker engine mounts a host directory as a data volume.

Console

1. Go to the VM instances page.

   Go to the VM instances page

2. Click the Create instance button to create a new instance.
3. Under the Container section, check Deploy container image.
4. Click Advanced container options.
5. Under Host directory mounts, click Add volume.

6. Specify:

   • A mount path, a path in a container directory structure where you would like to mount a host directory.
   • A host path, a path to the host directory that you would like to mount.
   • Whether to mount the directory in read/write or read-only mode.

gcloud

Use --container-mount-host-path flag to mount a host VM directory into a container. The following example mounts the host directory /tmp into the container at /logs in read-write mode:

gcloud compute instances create-with-container busybox-vm \
    --container-image docker.io/busybox:1.27 \
    --container-mount-host-path mount-path=/logs,host-path=/tmp,mode=rw

Specify mode=ro to mount a host directory in read-only mode.

Use the gcloud compute instances update-container command with the --container-mount-host-path flag to update host directory mounts on a container. Use --remove-container-mounts flag to remove volume mounts with the specified mount paths when updating. The following example removes a host path mount with mount-path=/logs:

gcloud compute instances update-container busybox-vm \
    --remove-container-mounts /logs

If the specified mount path does not exist, it is silently ignored.

Mounting tmpfs file system as a data volume

You can mount an empty tmpfs file system into a container.

Note: This is similar to a Kubernetes EmptyDir volume with medium:Memory. Unlike Docker, where tmpfs data is deleted on container restarts, with tmpfs on a Compute Engine container, the volume and its data persist across container restarts and are deleted only on VM restart.

Console

1. Go to the VM instances page.

   Go to the VM instances page

2. Click the Create instance button to create a new instance.
3. Under the Container section, check Deploy container image.
4. Click Advanced container options.
5. Under Tmpfs mounts, click Add volume.
6. Specify a mount path, a path in a container directory structure where you would like to mount a tmpfs volume. The tmpfs volume will be mounted in read/write mode.

gcloud

Use the --container-mount-tmpfs flag to mount an empty tmpfs file system into a container. The following example mounts a tmpfs file system into the container at /cache in read-write mode:

gcloud compute instances create-with-container busybox-vm \
   --container-image docker.io/busybox:1.27 \
   --container-mount-tmpfs mount-path=/cache

Use gcloud compute instances update-container command with --container-mount-tmpfs flag to update tmpfs mounts on a container. Use --remove-container-mountsflag to remove a tmpfs mount with the specified mount path when updating. The following example removes tmpfs mount with mount-path=/cache:

gcloud compute instances update-container busybox-vm \
    --remove-container-mounts /cache

If the specified mount path does not exist, it is silently ignored.

Mounting a persistent disk as a data volume

Beta

This is a Beta release of Mounting a persistent disk as a data volume in a container on Compute Engine. This feature is not covered by any SLA or deprecation policy and might be subject to backward-incompatible changes.

With Container-Optimized OS 69 or newer, you can mount persistent disks from a host VM into a container.

Note: This is similar to using the gcePersistentDisk volume type in Kubernetes.

Prerequisites

• The disk must have an ext4 filesystem or have no filesystem. With no initial filesystem, the container startup agent formats the disk to ext4, and only read/write attachment and mounting are supported.
• The disk must be attached to the VM.

• Both partitionless devices and partitions are supported. For partition mounts, the disk cannot be blank; it must contain an existing partition table.

Console

1. Go to the VM instances page.

   Go to the VM instances page

2. Click the Create instance button to create a new instance.
3. Under the Container section, check Deploy container image.
4. Click Advanced container options.
5. Under Volume mounts, click Add volume.
6. Under Volume type, select Disk.
7. Specify a Mount path, a path in the container directory structure where you would like to mount the persistent disk.
8. Under Disk name, select either an existing disk to mount or Attach new disk.
9. If the disk has a partition table, specify the partition number to mount. Leave this field blank if the disk does not have partitions.
10. Specify whether to mount the directory in read/write or read-only mode.

gcloud

Use the gcloud beta compute instances create-with-container command or the gcloud beta compute instances update-container command with the --container-mount-disk flag to mount a persistent disk into a container.

The following example mounts two disks, my-data-disk and my-scratch-disk, into the container at /disks/data-disk and /disks/scratch-disk mount paths.

gcloud beta compute instances create-with-container busybox-vm \
    --disk name=my-data-disk \
    --create-disk name=my-scratch-disk,auto-delete=yes,image=ubuntu-1710-artful-v20180315,image-project=ubuntu-os-cloud \
    --container-image docker.io/busybox:1.27 \
    --container-mount-disk mount-path="/disks/data-disk",name=my-data-disk,mode=ro \
    --container-mount-disk mount-path="/disks/scratch-disk",name=my-scratch-disk

Note that the --disk flag attaches my-data-disk, the --create-disk flag creates and attaches my-scatch-disk, and the --container-mount-disk flags mount the attached disks to the container. Because a mode is not specified for my-scratch-disk, that disk is mounted to the container in read/write mode by default.

Use the gcloud beta compute instances update-container command with the --container-mount-disk flag to mount additional attached disks or to modify existing disk mounts.

Use the --remove-container-mounts flag to remove a disk volume mount with the specified mount path. The following example changes the mount mode of my-data-disk to read/write and removes the disk mount with mount-path="/disks/scratch-disk".

gcloud beta compute instances update-container busybox-vm \
    --container-mount-disk mount-path="/disks/data-disk",name=my-data-disk,mode=rw \
    --remove-container-mounts "/disks/scratch-disk"

If the mount path that you pass to the --remove-container-mounts flag does not exist, it is silently ignored.

Publishing container ports

VMs with containers use the host network mode where a container shares the host's network stack, and all interfaces from the host are available to the container.

Note: This is equivalent of passing the --network="host" flag when using the docker run command. Learn more about container network settings and host mode.

Container ports have a one-to-one mapping to the host VM ports. For example, a container port 80 maps to the host VM port 80, and you do not have to specify the port publishing (-p) flag for the mapping to work.

To publish a container's ports, configure firewall rules to allow access to the host VM instance's ports. The corresponding ports of the container will be accessible automatically, according to the firewall rules.

Example: Publishing port 80 for an NGINX container

The following is an example of how to create a VM instance with an NGINX container and allow traffic to the container's port 80.

1. Create a VM instance with an NGINX container:

   gcloud compute instances create-with-container nginx-vm \
       --container-image gcr.io/cloud-marketplace/google/nginx1:1.12 \
       --tags http-server
   

   The container shares the host VM's network stack, and the container's port 80 is published to the host VM's port 80. The http-server tag is used as a target tag for the firewall rule, created in the next step.

2. Create a firewall rule to allow connections to port 80 of the VM instance. The following firewall rule allows HTTP connections to VM instances with the http-server tag.

   gcloud compute firewall-rules create allow-http \
       --allow tcp:80 --target-tags http-server
   

   The container will automatically start receiving traffic on port 80. You do not need to perform any additional configuration.

   You can create firewall rules for host VM protocol:port combinations where the protocol is tcp or udp. These rules will effectively govern access from outside the VM to the corresponding container ports.

What's next

• Learn how deploy Docker containers on Compute Engine.
• Learn about Container-Optimized OS.