There are two ways to create and configure Compute Engine instances runningContainer-Optimized OS from Google.

Forsimple scenarios where you want to run a single container on a VM or on eachVM in amanaged instance group,you can specify a container image and optionalconfiguration parameters when you define the instance or instance template.Compute Engine creates the instance with the latest version ofContainer-Optimized OS and launches the specified container when the VMstarts.

Foradvanced scenarios where you can deploy multiple containers and configureDocker options usingcloud-init, you can create a Compute Engine instance withyour choice of Container-Optimized OS image, and then proceed to configure the container asneeded.

Creating a simple instance

Use this method to deploy a single container on a VM using the latest version ofContainer-Optimized OS. You can perform this task using the Google Cloud consoleor gcloud CLI.

gcloud compute instances create-with-containerinstance-name \    --container-imageimage-name

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

gcloudcomputeinstancescreate-with-containerhello-app\--container-imageus-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0

docker.io/httpd:2.4

To run a single container on each VM in a managed instance group, specify thecontainer image name when defining the instance template. SeeCreating an instance template with a container imagefor more information.

Creating an instance for advanced scenarios

Use this method to select a specific Container-Optimized OS image, to deploymultiple containers, and to usecloud-init for advanced configuration.

Viewing available images

Container-Optimized OS images are available on Google Cloud console'slist of images with the prefixcos.These are hosted under thecos-cloud project. You can also see allcurrently available releases on command line by running the following command:

gcloud compute images list --project cos-cloud --no-standard-images

The output is similar to the following:

NAME                       PROJECT    FAMILY      DEPRECATED  STATUScos-69-10895-385-0         cos-cloud  cos-69-lts              READYcos-73-11647-534-0         cos-cloud  cos-73-lts              READYcos-77-12371-251-0         cos-cloud  cos-77-lts              READYcos-81-12871-103-0         cos-cloud  cos-81-lts              READYcos-beta-81-12871-44-0     cos-cloud  cos-beta                READYcos-dev-84-13078-0-0       cos-cloud  cos-dev                 READYcos-stable-81-12871-103-0  cos-cloud  cos-stable              READY

gcloud compute instances createinstance-name \    --imageimage-name \    --image-project cos-cloud \    --zonecompute-zone \    --machine-typemachine-type-name

gcloud compute instances create cos-test \    --image cos-beta-67-10575-13-0 \    --image-project cos-cloud \    --zone us-east1-d \    --machine-type n1-standard-1

POST https://compute.googleapis.com/compute/v1/projects/project-id/zones/compute-zone/instances{  'machineType': 'zones/compute-zone/machineTypes/machine-type-name',  'name': 'instance-name',  'networkInterfaces': [    {      'accessConfigs': [        {          'type': 'ONE_TO_ONE_NAT',          'name': 'External NAT'        }      ],      'network': 'global/networks/default'    }  ],  'disks': [    {      'type': 'PERSISTENT',      'boot': true,      'autoDelete': true,      'initializeParams': {        'sourceImage': 'projects/cos-cloud/global/images/image-name'      }    }  ]}

Configuring an instance

In some cases, you might want to do additional configuration when the instanceboots. You can use thecloud-init tool with Container-Optimized OS to applyconfiguration information that you supply in acloud-config format.

Using cloud-init with the Cloud config format

Container-Optimized OS images includecloud-init as a way to configure your instance when it boots up. Thecloud-init toolexpects its configuration in the value of theuser-data key of theinstance metadata. Thecloud-inittool understandsmultiple formats.

Here's an examplecloud-init file showing how to create a user account andcreate a systemd service owned by this user that controls the management of aDocker busybox container:

#cloud-configusers:-name:cloudserviceuid:2000write_files:-path:/etc/systemd/system/cloudservice.servicepermissions:0644owner:rootcontent:|[Unit]Description=Start a simple docker container[Service]ExecStart=/usr/bin/docker run --rm -u 2000 --name=mycloudservice busybox:latest /bin/sleep 3600ExecStop=/usr/bin/docker stop mycloudserviceExecStopPost=/usr/bin/docker rm mycloudserviceruncmd:-systemctl daemon-reload-systemctl start cloudservice.service# Optional once-per-boot setup. For example: mounting a PD.bootcmd:-fsck.ext4 -tvy /dev/[DEVICE_ID]-mkdir -p /mnt/disks/[MNT_DIR]-mount -t ext4 -O ... /dev/[DEVICE_ID] /mnt/disks/[MNT_DIR]

gcloud compute instances createinstance-name \    --imageimage-name \    --image-project cos-cloud \--metadata-from-file user-data=filename

It is possible to set other metadata flags when creating Container-Optimized OSinstances. Because these properties are simple key-value pairs, you may use the--metadata flag in thegcloud compute instances create command to create theproperties. Also, starting frommilestone 97,you can setmetadata flags in projectmetadata using the--metadata flagin thegcloud compute project-info add-metadata command. Flagsdefined at the instance level will take precedence over flags defined at theproject level.

The previous example can be expanded to collect usage statistics andcrash dump collection with the following command:

gcloud compute instances createinstance-name \    --imageimage-name \    --image-project cos-cloud \--metadata-from-file user-data=filename \    --metadata=cos-metrics-enabled=true

Other metadata flags

You can SSH into your VM instance running thecos node image thesame wayyou SSH into other Compute Engine instances.

For example:

gcloud compute sshinstance-name \    --projectproject-id \    --zonecompute-zone

Running startup scripts

You can specify astartup script through themetadata server, using thestartup-script metadata key. You can use theGoogle Cloud CLI, the API, or Google Cloud console to provide astartup script. Refer toRunning Startup Scriptsfor details.

Time synchronization

Beforemilestone 85, Container-Optimized OS usessystemd'ssystemd-timesyncd service to synchronizethe local system clock with a remote Network Time Protocol (NTP) server via theSNTP protocol. The following entries in/etc/systemd/timesyncd.confconfiguration file show commented out default configuration values to help theadministrator make any desired changes:

cat /etc/systemd/timesyncd.conf# comments omitted for brevity[Time]#NTP=#FallbackNTP=metadata.google.internal#RootDistanceMaxSec=5#PollIntervalMinSec=32#PollIntervalMaxSec=2048

So the maximum acceptable root distance is 5 seconds and the minimum andmaximum poll intervals for NTP messages are 32 and 2048 seconds respectively.

Starting from milestone 85, Container-Optimized OS useschronyd service to synchronizethe local system clock with a remote Network Time Protocol (NTP) server via theNTP protocol. The following entries in the/etc/chrony/chrony.confconfiguration file show commented out default configuration values to help theadministrator make any desired changes:

cat /etc/chrony/chrony.conf# Use custom NTP serversserver metadata.google.internal prefer iburst# Record the rate at which the system clock gains/losses time.driftfile /var/lib/chrony/drift# Allow the system clock to be stepped in the first three updates# if its offset is larger than 1 second.makestep 1.0 3# Enable kernel synchronization of the real-time clock (RTC).rtcsync

The NTP server is set frometh0's DHCP response, which is usually theCompute Engine's metadata server:

networkctl status eth0 | grep NTP             NTP: 169.254.169.254

Changing the time zone

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

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

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

Enabling or disabling automatic updates

There are two ways to enable or disable automatic updates. The preferred methodis to set thecos-update-strategy instance metadata key toupdate_enabled orupdate_disabled, respectively. For example:

gcloud compute instances createinstance-name \    --imageimage-name \    --image-project cos-cloud \--metadata cos-update-strategy=update_disabled

Starting frommilestone 97,you can also disable or enable automatic updates in project metadata:

gcloud compute project-info add-metadata \--metadata cos-update-strategy=update_disabled

sudo systemctl stop update-enginesudo systemctl mask update-engine