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 Console or the
gcloud
command-line tool.
Before you begin
- If you want to use the command-line examples in this guide:
- Install or update to the latest version of the gcloud command-line tool.
- Set a default region and zone.
- If you aren't familiar with Containers, read Containers at Google.
- If you aren't familiar with Docker, read the Docker documentation.
- Read about Deploying containers on Compute Engine.
Specifying a restart policy
You can set a 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.
Console
- Go to the VM instances page.
- Click the Create instance button to create a new instance.
- Under the Container section, specify the desired restart policy.
gcloud
Use the --container-restart-policy
flag to specify container a 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
nonzero:
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 for the restart policy on 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 aren't allowed to access any devices.
Console
- Go to the VM instances page.
- Click the Create instance button to create a new instance.
- Under the Container section, check Deploy container image.
- Click Advanced container options.
- 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 the
--container-privileged
flag to update a container on a VM. Use the
--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 always result in EOF
.
Along with allocating a pseudo-TTY, keeping the STDIN
stream
open is necessary for establishing an interactive shell in the container and
for the container to receive its standard input from a pipe.
Console
- Go to the VM instances page.
- Click the Create instance button to create a new instance.
- Under the Container section, check Deploy container image.
- Click Advanced container options.
- 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 the
--container-stdin
flag to update a container on a VM. Use the
--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 (along with allocating a buffer for STDIN).
Console
- Go to the VM instances page.
- Click the Create instance button to create a new instance.
- Under the Container section, check Deploy container image.
- Click Advanced container options.
- Check Allocate a pseudo-TTY.
gcloud
Use the --container-tty
flag to allocate a pseudo-TTY. The following
example starts 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 the
--container-tty
flag to update a container on a VM. Use the
--no-container-tty
flag to not allocate a pseudo-TTY.
Overriding the default command to execute on container startup
The ENTRYPOINT
of a container image specifies what executable to run when the
container starts and lets you run the container as if it were that binary.
You can override the ENTRYPOINT
command of the container image.
Console
- Go to the VM instances page.
- Click the Create instance button to create a new instance.
- Under the Container section, check Deploy container image.
- Click Advanced container options.
- In the Command box, enter a single executable command without
parameters, for example:
uptime
.
gcloud
Use the --container-command
flag to override the container
image ENTRYPOINT
. The following example runs the 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 the container
ENTRYPOINT
command or override the default container CMD
command.
Console
- Go to the VM instances page.
- Click the Create instance button to create a new instance.
- Under the Container section, check Deploy container image.
- Click Advanced container options.
- Under Command arguments, click Add argument.
- Enter one command argument per box.
gcloud
Use the --container-arg
flag to pass arguments to a container image
ENTRYPOINT
command. Use a separate flag for each argument.
The following example runs the /bin/ash
command with the -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"
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 the --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.
Console
- Go to the VM instances page.
- Click the Create instance button to create a new instance.
- Under the Container section, check Deploy container image.
- Click Advanced container options.
- Under Environment variables, click Add variable.
- 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 updates any variables present in
the VM instance's container declaration. Variables that are not in the
container declaration are added.
Use the --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.
Console
- Go to the VM instances page.
- Click the Create instance button to create a new instance.
- Under the Container section, check Deploy container image.
- Click Advanced container options.
- Under Host directory mounts, click Add volume.
Specify:
- A mount path. A path in a container directory structure at which to mount a host directory.
- A host path. A path to the host directory to mount.
- Whether to mount the directory in read/write or read-only mode.
gcloud
Use the --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 the --remove-container-mounts
flag to remove volume mounts
with the specified mount paths. 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.
Console
- Go to the VM instances page.
- Click the Create instance button to create a new instance.
- Under the Container section, check Deploy container image.
- Click Advanced container options.
- Under Tmpfs mounts, click Add volume.
- Specify a mount path, a path in a container directory structure where
you would like to mount a
tmpfs
volume. Thetmpfs
volume is 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 the gcloud compute instances update-container
command with the
--container-mount-tmpfs
flag to update tmpfs
mounts on a container.
Use the --remove-container-mounts
flag to remove a tmpfs
mount with
the specified mount path when updating. The following example removes the
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
With Container-Optimized OS 69 or later, you can mount persistent disks from a host VM into a container.
Prerequisites
- The disk must have an
ext4
file system or have no file system. With no initial file system, the container startup agent formats the disk toext4
, 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
- Go to the VM instances page.
- Click the Create instance button to create a new instance.
- Under the Container section, check Deploy container image.
- Click Advanced container options.
- Under Volume mounts, click Add volume.
- Under Volume type, select
Disk
. - Specify a Mount path, a path in the container directory structure where you would like to mount the persistent disk.
- Under Disk name, select either an existing disk to mount or Attach new disk.
- If the disk has a partition table, specify the partition number to mount. Leave this field blank if the disk does not have partitions.
- Specify whether to mount the directory in read/write or read-only mode.
gcloud
Use the
gcloud compute instances create-with-container
command or the
gcloud 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 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
flag mounts 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 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 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.
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. Compute Engine does not
support the port publishing (-p
) flag, and you do not have to specify it for
the mapping to work.
To publish a container's ports, configure firewall rules to enable access to the host VM instance's ports. The corresponding ports of the container are accessible automatically, according to the firewall rules.
Example: Publishing port 80 for an NGINX container
The following example shows how to create a VM instance with an NGINX container and allow traffic to the container's port 80.
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.Create a firewall rule to enable 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 automatically starts 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
orudp
. These rules effectively govern access from outside the VM to the corresponding container ports.
Feedback and questions
We welcome your feedback and questions! Please contact the Containers on Compute Engine team to ask questions, report issues, and request new capabilities.
What's next
- Learn how to deploy Docker containers on Compute Engine.
- Learn about Container-optimized OS.