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:

docker run --rm busybox echo "hello world"

The following output appears:

Unable to find image 'busybox:latest' locally
latest: Pulling from library/busybox
. . .
Status: Downloaded newer image for busybox:latest
hello world

When managing SSH keys in metadata, all user accounts managed by Compute Engine on the cos image are added to the docker group by default. This lets any logged-in user run docker commands without root privileges. When managing SSH keys using OS Login, the user account needs to be added to the docker group manually. Or else, the user has to add sudo for each docker command.

Accessing public Container Registry

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

docker run --rm gcr.io/google-containers/busybox echo "hello world"

The following output appears:

Unable to find image 'gcr.io/google-containers/busybox:latest' locally
Pulling repository gcr.io/google-containers/busybox
. . .
Status: Downloaded newer image for gcr.io/google-containers/busybox:latest
hello world

Accessing Private Container Registry

Starting with milestone 60 releases, docker-credential-gcr is pre-installed in Container-Optimized OS images. It's the recommended way to access private Container Registry.

To use docker-credential-gcr, run the following command:

docker-credential-gcr configure-docker

The following output appears:

/home/username/.docker/config.json configured to use this credential helper

For Container Registry registries, use the following command:

docker run --rm gcr.io/your-project/your-image

Alternately, you can fetch appropriate OAuth access tokens from Compute Engine metadata and use them with the docker login command manually, as shown in the following example:

METADATA=http://metadata.google.internal/computeMetadata/v1
SVC_ACCT=$METADATA/instance/service-accounts/default
ACCESS_TOKEN=$(curl -H 'Metadata-Flavor: Google' $SVC_ACCT/token | cut -d'"' -f 4)
docker login -u oauth2accesstoken -p $ACCESS_TOKEN https://gcr.io
docker run … gcr.io/your-project/your-image

Supported Container Registry hostnames are:

  • us.gcr.io
  • eu.gcr.io
  • asia.gcr.io

Using cloud-init with Container Registry

This cloud-init example uses the Cloud Config format to start a Docker container from an image stored in Docker's container registry called DockerHub. The example below uses the Cloud Config format to start a Docker container from an image stored in Container Registry:

#cloud-config

users:
- name: cloudservice
  uid: 2000

write_files:
- path: /etc/systemd/system/cloudservice.service
  permissions: 0644
  owner: root
  content: |
    [Unit]
    Description=Start a simple docker container
    Wants=gcr-online.target
    After=gcr-online.target

    [Service]
    Environment="HOME=/home/cloudservice"
    ExecStartPre=/usr/bin/docker-credential-gcr configure-docker
    ExecStart=/usr/bin/docker run --rm -u 2000 --name=mycloudservice gcr.io/google-containers/busybox:latest /bin/sleep 3600
    ExecStop=/usr/bin/docker stop mycloudservice
    ExecStopPost=/usr/bin/docker rm mycloudservice

runcmd:
- systemctl daemon-reload
- systemctl start cloudservice.service

Configuring Docker daemon to pull images from registry cache

You can configure Docker daemon to pull images from a registry cache by using registry mirrors.

  1. Configure the daemon to use the registry-mirror option in one of the following ways:

    • In the /etc/default/docker file, add the registry-mirror option for the registry (for example, https://mirror.gcr.io):
    echo 'DOCKER_OPTS="--registry-mirror=https://mirror.gcr.io"' | tee /etc/default/docker
    
    • In the /etc/default/docker file, append "--registry-mirror=https://mirror.gcr.io" to the existing DOCKER_OPTS:
    sed -i -e 's|"$| --registry-mirror=https://mirror.gcr.io"|' /etc/default/docker
    
  2. After adding the registry mirror, restart the Docker daemon for the changes to take effect:

    sudo systemctl daemon-reload
    sudo systemctl restart docker
    

Adding a configuration to /etc/default/docker is non-persistent across reboot. To ensure that your docker configuration remains persistent across reboots, consider adding the commands either in the cloud-init script of the instance's metadata in the cloud-config format or startup script.

The following example uses the cloud-config format to configure a registry-mirror:

#cloud-config

runcmd:
- echo 'DOCKER_OPTS="--registry-mirror=https://mirror.gcr.io"' | tee /etc/default/docker
- systemctl daemon-reload
- systemctl restart docker

Running a Kubernetes cluster

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

  1. Make sure that your Kubernetes master can be reached by opening port 443 in your firewall.
  2. Download Kubernetes release binaries, unpack, and bring up the cluster as follows:

    # Download and extract the latest kubernetes release.
    cd <empty-dir>
    KUBERNETES_VERSION="v1.4.6"
    curl -sSL -o kubernetes.tar.gz https://github.com/kubernetes/kubernetes/releases/download/${KUBERNETES_VERSION}/kubernetes.tar.gz
    tar xzf kubernetes.tar.gz
    cd kubernetes
    
    # Configure environment to use Container-Optimized OS
    export KUBE_OS_DISTRIBUTION=cos
    
    # Start up a cluster and verify that it is running:
    cluster/kube-up.sh
    cluster/kubectl.sh get nodes
    cluster/kubectl.sh get pods --namespace=kube-system
    
  3. Now, you can run your application on the cluster. For example, you can start a Redis cluster using the following example:

    cluster/kubectl.sh create -f \
      examples/guestbook/all-in-one/guestbook-all-in-one.yaml
    cluster/kubectl.sh get pods
    cluster/kubectl.sh describe pods redis-master-pod-name
    

For instances running as part of a GKE cluster, Docker and Kubelet logs are also automatically exported to Google Cloud's operations suite logging. Logs for Docker, Kubelet, and kube-proxy are available in Google Cloud's operations suite under Compute Engine VM Instance when using the Google Cloud Console.

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

cluster/kube-down.sh