Creating and Configuring Instances

You can create and configure Compute Engine instances running Container-Optimized OS from Google by using the gcloud command-line tool.

Viewing available images

Container-Optimized OS images are available on Google Cloud Platform Console's list of images with the prefix cos. These are hosted under the cos-cloud project. You can also see all currently available releases on command line by running:

gcloud compute images list \
    --project cos-cloud \

The output is similar to the following:

NAME                      PROJECT            FAMILY         STATUS
cos-beta-56-9000-66-0     cos-cloud          cos-beta       READY
cos-dev-57-9196-0-0       cos-cloud          cos-dev        READY
cos-stable-55-8872-76-0   cos-cloud          cos-stable     READY

Creating an instance with the gcloud command-line interface

You can use the gcloud compute instances create command with --image and --image-project flags to create a cos node image instance as follows:

gcloud compute instances create INSTANCE_NAME \
    --image cos-stable-55-8872-76-0 \
    --image-project cos-cloud \
    --zone us-east1-d \
    --machine-type n1-standard-1

In the above example, cos-beta-51-8172-26-0 is one of the available cos releases. It is recommended to use --preemptible flag for one-off experimental instances.

Connecting to an instance

You can SSH into your VM instance running the cos node image the same way you SSH into your other Google Compute Engine instances. For example:

gcloud compute ssh INSTANCE_NAME \
    --project PROJECT
    --zone ZONE

Creating an instance using the GCP Console

To run a Compute Engine instance with the Container-Optimized OS and a Docker container of your choice, follow these steps:

  1. Open the Compute Engine instance creation page on GCP Console.

    Create a new Compute Engine instance

  2. In the Containers section, check the box labeled Create VM instance running Docker containers.

  3. In the New Container dialog, enter the necessary information for the Container Image URL then click Done.

  4. Click Create.

This brings up a Container-Optimized OS instance ready with your Docker container up and running.

Configuring an instance

In some cases, you may want to do additional configuration when the instance boots. You can use the cloud-init tool with Container-Optimized OS to apply configuration information that you supply as a cloud-config format.

Using cloud-init

The cos node image includes cloud-init as a way to configure your instance when it boots up. Cloud-init reads value by the key user-data from the instance metadata. There are multiple formats for that field that Cloud-init understands. Below is a sample value for the user-data in cloud-config format that creates a user account and adds a systemd service:


- name: cloudservice
  uid: 2000

- path: /etc/systemd/system/cloudservice.service
  permissions: 0644
  owner: root
  content: |
    Description=Start a simple docker container

    ExecStart=/usr/bin/docker run --rm -u 2000 --name=mycloudservice busybox:latest /bin/sleep 3600
    ExecStop=/usr/bin/docker stop mycloudservice
    ExecStopPost=/usr/bin/docker rm mycloudservice

- systemctl daemon-reload
- systemctl start cloudservice.service

# Optional once-per-boot setup. Ex: mounting a PD.
- fsck.ext4 -tvy /dev/[DEVICE_ID]
- mkdir -p /mnt/disks/[MNT_DIR]
- mount -t ext4 -O ... /dev/[DEVICE_ID] /mnt/disks/[MNT_DIR]

When creating an instance use --metadata-from-file to set cloud-init metadata:

gcloud compute instances create INSTANCE_NAME \
    --image IMAGE_NAME \
    --metadata-from-file user-data=FILENAME

Other metadata flags

Metadata Key Description Default Behavior
cos-update-strategy Specifies update behavior. The only value accepted is: update_disabled. If not set all update from the current channel are automatically downloaded and installed.
cos-metrics-enabled Enables usage statistics and crash dump collection. Values could be:
false (default).
Disabled by default

Running startup scripts

You can specify a startup script through the metadata server, using the startup-script metadata key. You can use the gcloud command-line tool, the API, or GCP Console to provide a startup script. Refer to Running Startup Scripts for details.

Starting and stopping systemd services

To start the service specified in the hello.service file:

sudo systemctl start hello.service

To stop the above service:

sudo systemctl stop hello.service

Changing the time zone

The default time zone of Container-Optimized OS is UTC0. Create a symbolic link to your desired time zone as in the following example:

sudo rm /etc/localtime
sudo ln -s /usr/share/zoneinfo/US/Pacific /etc/localtime

Note that /etc is stateless, so the timezone will be reset to the default (UTC0) every reboot.

Disabling automatic updates

There are two ways to disable automatic updates. The preferred method is to use the cos-update-strategy metadata key:

--metadata cos-update-strategy=update_disabled

You can also disable automatic updates on a running instance with systemctl:

sudo systemctl stop update-engine
sudo systemctl mask update-engine
Was this page helpful? Let us know how we did:

Send feedback about...

Container-Optimized OS