Running Containers on Instances

You can run a Docker container on a machine running Container-Optimized OS in much the same way as you would on most other node image distributions: by using the docker run command. For example:

$ sudo docker run --rm busybox echo "hello world"
Unable to find image 'busybox:latest' locally
latest: Pulling from library/busybox
. . .
Status: Downloaded newer image for busybox:latest
hello world

To run docker run and other Docker commands as a non-root user (without using sudo), your account must be a member of the docker group. On newer versions of the cos node image, user accounts are included in that group by default. On older images, you can explicitly add the user account to the docker group by running the following command. Then, log out of your current session and log back in:

$ sudo usermod -a -G docker ${USER}

Also, you can avoid logging out by running the following command after updating the docker group:

$ exec sudo su ${USER}

Accessing Public Google Container Registry

Google Container Registry support is built in to the cos node image. To start a container from Google Container Registry, run:

$ docker run --rm echo "hello world"
Unable to find image '' locally
Pulling repository
. . .
Status: Downloaded newer image for
hello world

Accessing Private Google Container Registry

In order to access containers on private Google Container Registry, you need to fetch appropriate OAuth access tokens from Google Compute Engine metadata and use them with the docker login command. Here is an example how this can be done.

$ SVC_ACCT=$METADATA/instance/service-accounts/default
$ ACCESS_TOKEN=$(curl -H 'Metadata-Flavor: Google' $SVC_ACCT/token \
    | cut -d'"' -f 4)
$ docker login -u _token -p $ACCESS_TOKEN
$ docker run --rm<your-project>/<your-image> <command>

Container-Optimized OS images provide a /usr/share/google/ script, which fetches and stores the necessary OAuth access tokens. The script stores the tokens in the instance's home directory, where Docker looks for access tokens by default.

$ /usr/share/google/
$ docker run …

On older images, make sure you have added your account to the docker group as described in the preceding step.

Supported GCR hostnames are:


Starting a Docker container via Cloud-Config

The Cloud-Config example explains how to start a docker container. It can be extended to start a container from Google Container Registry as follows:


- 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 /bin/sleep 3600
    ExecStop=/usr/bin/docker stop mycloudservice
    ExecStopPost=/usr/bin/docker rm mycloudservice

- systemctl daemon-reload
- systemctl start cloudservice.service

Running a Kubernetes cluster

The recommended approach to running a Kubernetes cluster on Google Cloud Platform is using Container Engine. However, if you want to run a self-managed version of open-source Kubernetes, follow these instructions.

First, make sure that your Kubernetes master can be reached by opening port 443 in your firewall.

Then, download Kubernetes release binaries, unpack, and bring up the cluster as follows:

# Download and extract the latest kubernetes release.
cd <empty-dir>
curl -sSL -o kubernetes.tar.gz${KUBERNETES_VERSION}/kubernetes.tar.gz
tar xzf kubernetes.tar.gz
cd kubernetes

# Configure environment to use Container-Optimized OS.

# Start up a cluster and verify that it is running:
cluster/ get nodes
cluster/ get pods --namespace=kube-system

Now you can run your application on the cluster. For example, you can start a Redis cluster using the example below.

cluster/ create -f \
cluster/ get pods
cluster/ describe pods <redis-master-pod-name>

Once your cluster is no longer needed, you can tear it down:


Send feedback about...

Container-Optimized OS