You can configure a Compute Engine instance or aninstance template to deploy and launch aDocker container. Compute Engine supplies an up-to-dateContainer-Optimized OS (COS)image with Docker installed and launches your container when your instancestarts.

Before you begin

• If you aren't familiar with containers, readWhat are containers and their benefits.
• If you aren't familiar with Docker, read theDocker documentation.
• Read aboutContainer-Optimized OS.
• Read aboutmanaged instance groups (MIGs).
• If you haven't already, set upauthentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  1. Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:

     gcloudinit

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.
  2. Set a default region and zone.

Choosing to deploy containers on instances and MIGs

By deploying containers on Compute Engine, you can simplifyapp deployment while controlling your instance infrastructure.

• Manage instances that are running containers in the same way you would treatany other instance when configuring and managing your Compute Engineinfrastructure.
• Use familiar processes and tools such as the Google Cloud CLI orthe Compute Engine API to manage your instances with containers.
• Create scalable services using managed instance groups (MIGs) runningcontainers, which offer features like autoscaling, autohealing,rolling updates, multi-zone deployments, and load balancing.

Alternatively, you might consider deploying toGoogle Kubernetes Engine to:

• Run a large number of microservices
• Have faster container startup time
• Take advantage ofKubernetes automated orchestration, including auto upgrades, node auto repair, andautoscaling

Running each microservice on a separate instance on Compute Enginecould make the operating system overhead a significant part of your cost.Google Kubernetes Engine lets you deploy multiple containers and groups of containersfor each instance, which can allocate host instance resources more efficientlyto microservices with a smaller footprint.

How deploying containers on Compute Engine works

The common methods of deploying software onto a Compute Engineinstance include:

• Deploying software on instance boot using astartup script orcloud-init.
• Creating a custom boot disk image with software pre-installed.

Both of the methods in the previous list combine the tasks of configuring theapp and setting up the operating system environment. As the developer, you mustcarefully track and resolve any runtime dependencies. For example, if two appsrunning on a VM use different versions of the same library, you must installboth versions and point to them through system variables.

Alternatively, you can deploy software in a container onto an instance or to aMIG. A container carries both application software and the requiredlibraries and is isolated from OS apps and libraries. A container can bemoved between deployment environments without dealing with conflicting libraryversions in the container and its OS.

The following process describes how you deploy a container onCompute Engine:

1. You bundle your app and required libraries into a Docker image andpublish the image toArtifact Registry, or athird-party registry such as Docker Hub.
2. You specify a Docker image name and thedocker runconfiguration when creating an instance or an instance template for aMIG.

Note: As of November 1, 2020, Docker Hubrate limits apply to unauthenticated or authenticated pull requests on theDocker Free plan. To avoid disruptions and have greater control over yoursoftware supply chain, you can migrate your dependencies toArtifact Registry.

Compute Engine executes the following tasks after you make a requestto create an instance:

1. Compute Engine creates a VM instance that uses a Google-providedContainer-Optimized OS image. Thisimage includes a Docker runtime and additional software that is responsiblefor starting your container.
2. Compute Engine stores your container settings ininstance metadata under thegce-container-declaration metadata key.
3. When the VM starts, the Container-Optimized OS image uses thedocker run command configuration that is stored in the instance's metadata,pulls the container image from the repository, and starts the container.

Limitations

• You can only deploy one container for each instance. ConsiderGoogle Kubernetes Engine if you need to deploy multiplecontainers per instance.

• You can only deploy containers from a public repository or from a privateArtifact Registry or Container Registry repository that you can access. Otherprivate repositories are not supported.

  See the access control documentation forArtifact Registry orContainer Registry for informationabout private registry permissions.

  Caution: Container Registry is deprecated. Effective March 18, 2025, Container Registry is shut down, and writing images to Container Registry is unavailable. For details on the deprecation and how to migrate to Artifact Registry, seeContainer Registry deprecation.

• You can't map an instance's ports to the container's ports (Docker's-poption). To enable access to your containers, seePublishing container ports.

• You can only useContainer-Optimized OS imageswith this deployment method.

• You can only use this feature through the Google Cloud console or theGoogle Cloud CLI, not the API.

Preparing a container for deployment

Choose one of the following approaches to make your container image accessibleto Compute Engine:

• Upload your Docker imageto Artifact Registry.
• Use any publicly available container images fromDocker Hub or other registries.

Deploying a container on a new instance

You can deploy a container on a new VM instance by using theGoogle Cloud console or the Google Cloud CLI.

Updating a container on an instance

You can update a Docker image and configuration options to run thecontainer on an instance using Google Cloud console or the Google Cloud CLI.

When you update an running a container, Compute Engine performs twosteps:

• Updates container declaration on the instance. Compute Enginestores the updated container declaration ininstance metadata under thegce-container-declaration metadata key.
• Stops and restartsthe instance to actuate the updated configuration, if the instance is running.If the instance is stopped, updates the container declaration and keeps theinstance stopped. The instance downloads the new image and launches thecontainer at startup.

gcloud compute instances update-container nginx-vm \    --container-image gcr.io/cloud-marketplace/google/nginx1:latest

Deploying a container on a managed instance group

You can deploy a container to a new managed instance group (MIG) usingGoogle Cloud console or the Google Cloud CLI by following these steps:

1. Create aninstance template that isbased on a Docker image.

   Note: To maintain identical instances in your group, include a specificDocker image version in your instance template, such asnginx1:15. Formore information, seeDeterministic instance templates.

2. Create aMIGfrom the new instance template.

gcloud compute instance-templates create-with-containerTEMPLATE_NAME \  --container-imageDOCKER_IMAGE

gcloud compute instance-templates create-with-container nginx-template \    --container-image gcr.io/cloud-marketplace/google/nginx1:15

Now that you have an instance template, you cancreate a MIGthat uses the instance template. For example, to create a MIGby using the gcloud CLI and thenginx-template that you justcreated, run the following command:

gcloud compute instance-groups managed create example-group \    --base-instance-name nginx-vm \    --size 3 \    --template nginx-template

Updating a managed instance group running a container

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

You can update a managed instance group (MIG) to deploy a new version of aDocker image or a new version of the Container-Optimized OS image.

Updating a MIG to a new version of a container image

You can deploy a new version of a Docker image to a MIGby using the Managed Instance Group Updater, in three steps:

1. Prepare a new Docker image for deployment.
2. Create an instance template based on the new Docker image in the same way youcreate a container-based template.
3. Update a MIG to the new instance template by using theManaged Instance Group Updater.

Updating a managed instance group to a new version of Container-Optimized OS image

Google updates Container-Optimized OS imagesregularly,and you might want to apply those updates to your containerized MIGs withoutchanging your Docker image. You can update a MIG to a new version of aContainer-Optimized OS image by using Google Cloud console or theGoogle Cloud CLI in two steps:

1. Create an instance template based on the current version of your Dockerimage, the same way youcreate a container-based templatefor a new MIG. The latest supported version of aContainer-Optimized OS image is used by default.
2. Update a MIG with the new instance template by usingManaged Instance Group Updater.

Connecting to a container using SSH

You can connect to a container on an instance by using SSH. Use thegcloud CLI to rungcloud compute ssh with the--container flag:

gcloud compute sshINSTANCE_NAME --containerCONTAINER_NAME

Replace the following:

• INSTANCE_NAME: the name of the instance
• CONTAINER_NAME: the name of the container

Learn more about thegcloud compute sshcommand and its arguments.

Monitoring containers on Compute Engine

To monitor your instances running a Container-Optimized OS image, use theNode Problem Detector agent,which communicates with Cloud Monitoring and reports health-related metrics.The agent is built into Container-Optimized OS images starting with Milestone77.

To enable the agent, in containers using images with Milestone 88 or later, editthecustom metadata sectionand setgoogle-monitoring-enabled totrue.

To find other ways of enabling the Node Problem Detector, visitEnabling health monitoring.

The Node Problem Detector agent supports the metrics in themetrics listthat begin withguest/.

To interact with the metrics collected by the agent, visit theMetrics Explorer.

Viewing logs

You can view three types of logs related to containers:

1. Startup agent logs, also known askonlet logs. The startup agent parses the container's configuration and runs tasksto start the container on a Compute Engine instance.

2. Docker event logs report container events, including container startand stop events.

3. Logs from your container include theSTDOUT from apps that runin your container.

Viewing startup agent logs

Startup agent logs are available in the serial console, through thejournald system service included in the OS image, and throughCloud Logging.

Viewing startup agent logs in the serial console

gcloud compute instances get-serial-port-outputINSTANCE_NAME

gcloud compute instances get-serial-port-output nginx-vm

Viewing startup agent logs injournald

1. Connect to your instancewith a container by using SSH.

2. Execute thesudo journalctl command to see the instance startup andcontainer startup logs. Use the following command to filter for containerstartup agent logs (konlet).

   sudo journalctl -u konlet*

Viewing startup agent logs in Logging

gcloud logging read "resource.type=gce_instance AND \    logName=projects/PROJECT_ID/logs/cos_system AND \    jsonPayload.SYSLOG_IDENTIFIER=konlet-startup AND \    jsonPayload._HOSTNAME=INSTANCE_NAME"

gcloud logging read "resource.type=gce_instance AND \    logName=projects/my-project/logs/cos_system AND \    jsonPayload.SYSLOG_IDENTIFIER=konlet-startup AND \    jsonPayload._HOSTNAME=nginx-vm" \    --limit 10

Viewing Docker event logs

You can view Docker event logs injournald and in Cloud Logging.

Viewing Docker event logs injournald

1. Connect to your instancewith a container using SSH.

2. Execute thesudo journalctl command with the following filter to seeDocker event logs.

   sudo journalctl -u docker-events-collector

Viewing Docker event logs in Logging

gcloud logging read "resource.type=gce_instance AND \    logName=projects/PROJECT_ID/logs/cos_system AND \    jsonPayload._HOSTNAME=INSTANCE_NAME AND \    jsonPayload.SYSLOG_IDENTIFIER=docker"

gcloud logging read "resource.type=gce_instance AND \    logName=projects/my-project/logs/cos_system AND \    jsonPayload._HOSTNAME=nginx-vm AND \    jsonPayload.SYSLOG_IDENTIFIER=docker" \    --limit 10

Viewing container logs

Specifying container-optimized images or image families

Containerized instances or instance templates are created to use the latestsupportedcontainer-optimized image by default.The image belongs to thecos-cloud project.

You can override this default with another image from thecos-cloud project.For information about available image families and their attributes, seeChoosing the right Container-Optimized OS version.

For example, after you know which image you want to use, in thegcloud CLI, either provide the--image flag tooverride the default container-optimized image or provide the--image-family flag to pick the latest image from the specifiedfamily at instance creation time.

The following example creates a containerized instance that uses the latestimage from thecos-dev image family:

gcloud compute instances create-with-container nginx-vm \    --image-family cos-dev \    --image-project cos-cloud \    --container-image gcr.io/cloud-marketplace/google/nginx1:1.15

Configuring firewall rules

Containerized instances launch containers whose network is set to host mode. Acontainer shares the host network stack, and all interfaces from the host areavailable to the container.

Bydefault, Google Cloudfirewall rules block all incoming connections to aninstance and allow all outgoing connections from an instance.

Create firewall rulesto allow incoming connections to your instance and therefore to the container.

Configuring options to run a container

You can configure the following options to run your container:

• Specify a container restart policy.
• Override containerENTRYPOINT (default command to be executed on containerstart).
• Pass arguments to containerENTRYPOINT command.
• Run a container in a privileged mode.
• Mount a host directory ortmpfs as a data volume inside the container.
• Set environment variables.
• Allocate a buffer forSTDIN in the container runtime.
• Allocate a pseudo-TTY.

Learn more aboutconfiguring options to run your container.

What's next

• Learn aboutconfiguring options to run your container.
• Learn more aboutmanaged instance groups.
• Learn aboutContainer-Optimized OS.