Configuring options to run your container

You can run a single container on a VM or on each VM in a managed instance group(MIG). To do this, specify a container image and configuration parameters whenyou create a VM instance or an instance template.

This document describes the configuration options for running containers onCompute Engine instances.

Note: The Compute Engine feature that deploys containers on VMs during VM creation is deprecated. Use thedocker run commands in a startup script or use thecloud-init tool to configure and to run containers on your VMs and MIGs. For more information, seeMigrate containers that were deployed on VMs during VM creation.

Before you begin

When you create an instance or an instance template to use forDeploying containers on VMs and MIGs,specify the container configuration using the Google Cloud console or theGoogle Cloud CLI.

The following sections describe how to configure containers on VM instances,but you can configure the following options when creating an instance templateas well. Use the Google Cloud console or the Google Cloud CLI to configure optionsfor VM instances in an instance template.

You can use thedocker run commands to configure a container on a VM instancethat is running Container-Optimized OS or specify thedocker run command in astartup script to create and configure a VM. For more information, seeUse startup scripts to deploy containers on VMs.

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 restarton failure or to never restart.

docker run

Use the--restart flag of thedocker run command.Repeated attempts to restart a container are driven by the default Dockerbehavior, as specified in the Docker--restartreference.

Console

Note: TheDeploy container option in the Google Cloud console is deprecated. Use the equivalentdocker run command to configure and to run the container.

  1. Go to theCreate an instance page.

    Go to Create an instance

  2. In theContainer section, clickDeploy container.

  3. On theConfigure container page, do the following:

    1. Specify a container image name.
    2. In theRestart policy section, select the restart policy for thecontainer.
    3. To confirm the container details, clickSelect.

  4. Continue with the VM creation process.

gcloud

Note: Thecreate-with-container gcloud CLI command is deprecated. Use the equivalentdocker run command to configure and to run the container.

Use the--container-restart-policy flag to specify container a restartpolicy:

  • always (default)
  • on-failure
  • never

The following example launches a container withon-failure restart policy,which means the restart only happens when the container exit code isnonzero:

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

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

Running a container in privileged mode

You can run a container in privileged mode to allow access to all deviceson the host. Containers are run as "unprivileged" by default and aren'tallowed to access any devices.

docker run

Use the--privileged flag of thedocker run command. For more information, seeRuntime privilege and Linux capabilities.

Console

Note: TheDeploy container option in the Google Cloud console is deprecated. Use the equivalentdocker run command to configure and to run the container.

  1. Go to theCreate an instance page.

    Go to Create an instance

  2. In theContainer section, clickDeploy container.

  3. On theConfigure container page, do the following:

    1. Specify a container image name.
    2. SelectRun as privileged.
    3. To confirm the container details, clickSelect.

  4. Continue with the VM creation process.

gcloud

Note: Thecreate-with-container gcloud CLI command is deprecated. Use the equivalentdocker run command to configure and to run the container.

Use the--container-privileged flag to run a container with runtimeprivilege. The following example launches a busybox container in privilegedmode:

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

Use thegcloud 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 forSTDIN in the container runtime to keep theSTDIN stream open in a container. If this is not set, reads fromSTDINin the container always result inEOF.

Along withallocating a pseudo-TTY, keeping theSTDIN streamopen is necessary for establishing an interactive shell in the container andfor the container to receive its standard input from a pipe.

docker run

Use the--interactive (-i) flag of thedocker run command. For more information, see the documentation for--interactiveflag.

Console

Note: TheDeploy container option in the Google Cloud console is deprecated. Use the equivalentdocker run command to configure and to run the container.

  1. Go to theCreate an instance page.

    Go to Create an instance

  2. In theContainer section, clickDeploy container.

  3. On theConfigure container page, do the following:

    1. Specify a container image name.
    2. SelectAllocate a buffer for STDIN.
    3. To confirm the container details, clickSelect.

  4. Continue with the VM creation process.

gcloud

Note: Thecreate-with-container gcloud CLI command is deprecated. Use the equivalentdocker run command to configure and to run the container.

Use--container-stdin flag to allocate a buffer forSTDIN inthe container runtime. The following example starts a container andkeeps itsSTDIN open:

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

Usegcloud 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 forSTDIN.

Allocating a pseudo-TTY

Allocating a pseudo-TTY for a container is necessary for establishing aninteractive shell in the container (along withallocating a buffer for STDIN).

docker run

Use the--tty (-t) flag of thedocker run command. For more information,see the--tty flag.

Console

Note: TheDeploy container option in the Google Cloud console is deprecated. Use the equivalentdocker run command to configure and to run the container.

  1. Go to theCreate an instance page.

    Go to Create an instance

  2. In theContainer section, clickDeploy container.

  3. On theConfigure container page, do the following:

    1. Specify a container image name.
    2. SelectAllocate a pseudo-TTY.
    3. To confirm the container details, clickSelect.

  4. Continue with the VM creation process.

gcloud

Note: Thecreate-with-container gcloud CLI command is deprecated. Use the equivalentdocker run command to configure and to run the container.

Use the--container-tty flag to allocate a pseudo-TTY. The followingexample 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 thegcloud 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

TheENTRYPOINT of a container image specifies what executable to run when thecontainer starts and lets you run the container as if it were that binary.

You can override theENTRYPOINT command of the container image.

docker run

Use the--entrypoint flag (command only, no arguments) of thedocker run command. Learn aboutENTRYPOINT and the--entrypoint flag.

Console

Note: TheDeploy container option in the Google Cloud console is deprecated. Use the equivalentdocker run command to configure and to run the container.

  1. Go to theCreate an instance page.

    Go to Create an instance

  2. In theContainer section, clickDeploy container.

  3. On theConfigure container page, do the following:

    1. Specify a container image name.
    2. In theCommand field, enter a single executable command withoutparameters—for example,uptime.
    3. To confirm the container details, clickSelect.

  4. Continue with the VM creation process.

gcloud

Note: Thecreate-with-container gcloud CLI command is deprecated. Use the equivalentdocker run command to configure and to run the container.

Use the--container-command flag to override the containerimageENTRYPOINT. The following example runs theuptime command in abusybox 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 thegcloud 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 theupdate-container commandto clear the default command for the updated container.

Passing arguments to container ENTRYPOINT command

You can pass (append) arguments to the containerENTRYPOINT command or override the default containerCMD command.

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

Console

Note: TheDeploy container option in the Google Cloud console is deprecated. Use the equivalentdocker run command to configure and to run the container.

  1. Go to theCreate an instance page.

    Go to Create an instance

  2. In theContainer section, clickDeploy container.

  3. On theConfigure container page, do the following:

    1. Specify a container image name.
    2. In theArguments section, clickAdd argument.
    3. Enter one command argument for each box.
    4. To confirm the container details, clickSelect.

  4. Continue with the VM creation process.

gcloud

Note: Thecreate-with-container gcloud CLI command is deprecated. Use the equivalentdocker run command to configure and to run the container.

Use the--container-arg flag to pass arguments to a container imageENTRYPOINT 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"
Note: Make sure to use the equals sign (=) with the--container-argflag to ensure proper argument parsing. For example:--container-arg=ARG.

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

Use the--clear-container-args flag with theupdate-container command toremove all arguments from container declaration.

Configuring log driver options

If you need to configure log driver options, you can create a VMstartup script to update your Dockerconfiguration file with the logging options that you need. These options applyto all containers that run on the VM and that do not specify log driver options.

For example, the following startup script sets several options–including anoption to limit the container's log size–then restarts Docker on the VM:

cat <<EOF > /etc/docker/daemon.json{  "live-restore": true,  "storage-driver": "overlay2",  "log-opts": {    "max-size": "10m"  }}EOFsystemctl restart docker

Setting environment variables

You can set environment variables in a container. Only the last value ofKEY is taken when theKEYis repeated more than once.

docker run

Use the--env flag of thedocker run command. Learn how Docker engine enablessetting environment variables.

Console

Note: TheDeploy container option in the Google Cloud console is deprecated. Use the equivalentdocker run command to configure and to run the container.

  1. Go to theCreate an instance page.

    Go to Create an instance

  2. In theContainer section, clickDeploy container.

  3. On theConfigure container page, do the following:

    1. Specify a container image name.
    2. In theEnvironment variables section, clickAdd variable.
    3. Add or remove environment variables as necessary, one for each line.
    4. To confirm the container details, clickSelect.

  4. Continue with the VM creation process.

gcloud

Note: Thecreate-with-container gcloud CLI command is deprecated. Use the equivalentdocker run command to configure and to run the container.

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

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 alocal file. The following example sets the two environment variablesfrom theenv.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 theenv.txt file are:

# this is a commentHOME=/homeMODE=testOWNER=admin

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

Use the--remove-container-env flag to remove environment variables whenupdating a container on a VM. The following example removes the environmentvariables calledMODE andOWNER:

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.

docker run

Use the--volume flag and the--mount flag with mounttype=bind ofthedocker run command. Learn how the Docker enginemounts a host directoryas a data volume.

Console

Note: TheDeploy container option in the Google Cloud console is deprecated. Use the equivalentdocker run command to configure and to run the container.

  1. Go to theCreate an instance page.

    Go to Create an instance

  2. In theContainer section, clickDeploy container.

  3. On theConfigure container page, do the following:

    1. Specify a container image name.
    2. In theVolume mounts section, clickAdd volume.

    3. From theVolume type list, selectDirectory, and do thefollowing:

      • In theMount path field, specify a mount path in a containerdirectory structure at which to mount a host directory.
      • In theHost path field, specify a host path to the hostdirectory to mount.
      • In theMode list, specify whether to mount the directory inread/write or read-only mode.

    4. To confirm the container details, clickSelect.

  4. Continue with the VM creation process.

gcloud

Note: Thecreate-with-container gcloud CLI command is deprecated. Use the equivalentdocker run command to configure and to run the container.

Use the--container-mount-host-path flag to mount a host VM directoryinto a container. The following example mounts the host directory/tmpinto 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

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

Use thegcloud compute instances update-container command with the--container-mount-host-path flag to update host directory mounts on acontainer. Use the--remove-container-mounts flag to remove volume mountswith the specified mount paths. The following example removesa host path mount withmount-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.

An empty tmpfs file system is similar to a Google Kubernetes EngineEmptyDirvolume withmedium:Memory. Unlike Docker, wheretmpfs data is deleted oncontainer restarts, withtmpfs on a Compute Engine container, thevolume and its data persist across container restarts and are deleted only on VMrestart.

Console

Note: TheDeploy container option in the Google Cloud console is deprecated. Use the equivalentdocker run command to configure and to run the container.

  1. Go to theCreate an instance page.

    Go to Create an instance

  2. In theContainer section, clickDeploy container.

  3. On theConfigure container page, do the following:

    1. Specify a container image name.
    2. In theVolume mounts section, clickAdd volume.
    3. From theVolume type list, selectTmpFS.
    4. In theMount path field, specify a mount path in a containerdirectory structure where you would like to mount a TmpFS volume.
    5. In theMode list, specify whether to mount the TmpFS volume inread/write or read-only mode.
    6. To confirm the container details, clickSelect.

  4. Continue with the VM creation process.

gcloud

Note: Thecreate-with-container gcloud CLI command is deprecated. Use the equivalentdocker run command to configure and to run the container.

Use the--container-mount-tmpfs flag to mount an emptytmpfs file systeminto a container. The following example mounts atmpfs file system intothe 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 thegcloud compute instances update-container command with the--container-mount-tmpfs flag to updatetmpfs mounts on a container.Use the--remove-container-mountsflag to remove atmpfs mount withthe specified mount path when updating. The following example removes thetmpfs mount withmount-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

WithContainer-Optimized OS 69 orlater, you can mount persistent disks from a host VM into a container.

Note: This is similar to using thegcePersistentDiskvolume type in Google Kubernetes Engine.

Prerequisites

  • The disk must have anext4 file system or have no file system. With noinitial file system, the container startup agent formats the disk toext4,and only read/write attachment and mounting are supported.
  • The disk must beattached 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

Note: TheDeploy container option in the Google Cloud console is deprecated. Use the equivalentdocker run command to configure and to run the container.

  1. Go to theCreate an instance page.

    Go to Create an instance

  2. In theContainer section, clickDeploy container.

  3. On theConfigure container page, do the following:

    1. Specify a container image name.
    2. In theVolume mounts section, clickAdd volume.
    3. From theVolume type list, selectDisk.
    4. In theMount path field, specify a path in the containerdirectory structure where you would like to mount the persistent disk.
    5. From theDisk name list, select an existing disk tomount.
    6. In thePartition field, specify the partition number tomount if the disk has a partition table. If the disk does not havepartitions, leave this field blank.
    7. In theMode list, specify whether to mount the directory inread/write or read-only mode.
    8. To confirm the container details, clickSelect.

  4. Continue with the VM creation process.

gcloud

Note: Thecreate-with-container gcloud CLI command is deprecated. Use the equivalentdocker run command to configure and to run the container.

Use thegcloud compute instances create-with-containercommand or thegcloud compute instances update-containercommand with the--container-mount-disk flag to mount a persistent diskinto a container.

The following example mounts two disks,my-data-disk andmy-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 attachesmy-data-disk, the--create-diskflag creates and attachesmy-scatch-disk, and the--container-mount-diskflag mounts the attached disks to the container. Because amode is notspecified formy-scratch-disk, that disk is mounted to the container inread/write mode by default.

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

Use the--remove-container-mounts flag to remove a disk volume mount withthe specified mount path. The following example changes the mount mode ofmy-data-disk to read/write and removes the disk mount withmount-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 doesnot exist, it is silently ignored.

Publishing container ports

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

Container ports have a one-to-one mapping to the host VM ports. For example, acontainer port 80 maps to the host VM port 80. Compute Engine does notsupport the port publishing (-p) flag, and you don't have to specify it forthe mapping to work.

To publish a container's ports,configure firewall rulesto enable access to the host VM's ports. The corresponding ports of thecontainer are accessible automatically, according to the firewall rules.

Example: Publishing port 80 for an NGINX container

docker run

Configure the--network="host" flag when usingthedocker run command. Learn more aboutcontainer network settings and host mode.

gcloud

Note: Thecreate-with-container gcloud CLI command is deprecated. Use the equivalentdocker run command to configure and to run the container.

The following example shows how to create a VM instance with an NGINXcontainer 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.15 \--tags http-server

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

  2. 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 thehttp-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. Youdon't need to perform any additional configuration.

    You can create firewall rules for host VM protocol:port combinationswhere the protocol istcp orudp. These rules effectively governaccess from outside the VM to the corresponding container ports.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-18 UTC.