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

Accessing public images in Container Registry or Artifact 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 images in Artifact Registry or 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 images in Artifact Registry or Container Registry.

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

docker-credential-gcr configure-docker --registries LOCATION-docker.pkg.dev

docker-credential-gcr configure-docker

The following output appears:

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

To run an image from the registry, use the following command:

docker run --rm LOCATION-docker.pkg.dev/your-project/repository/your-image

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

To use docker with sudo, run the following command. The -E command-line flag makes docker use the .docker/config.json file from a user's home directory instead of the root home directory.

sudo -E docker run --rm LOCATION-docker.pkg.dev/your-project/repository/your-image

sudo -E 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

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

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 --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

For more on configuring an instance with cloud-init, see Using cloud-init with the Cloud config format.

Troubleshooting

Resolving option conflicts between Docker daemon.json and flags

When configuring the Docker daemon, if the same option is set with a daemon.json file and with flags, Docker will fail to start with an error similar to:

unable to configure the Docker daemon with file /etc/docker/daemon.json:
the following directives are specified both as a flag and in the configuration file:

The recommended solution to resolve this conflict is to modify the default daemon.json, which is located at /etc/docker/daemon.json. Modifying this file allows for changing only the affected options, while maintaining the other default options. This can be done using cloud-init, for example using a cloud-config similar to:

#cloud-config

write_files:
- path: /tmp/modify_docker_daemon_opts.py
  permissions: 0744
  owner: root
  content: |
    import json, sys, os, logging

    DAEMON_OPTS_FILE = '/etc/docker/daemon.json'

    opts = {}
    if os.path.exists(DAEMON_OPTS_FILE):
      with open(DAEMON_OPTS_FILE) as f:
          try:
            opts = json.load(f)
          except:
            logging.info("json parsing failed, starting with empty config.")
            pass
    # Add your daemon option modifications here
    # For example,
    # opts['log-opts']['max-size'] = '100m'
    with open(DAEMON_OPTS_FILE, 'w') as f:
        json.dump(opts, f)

runcmd:
- python /tmp/modify_docker_daemon_opts.py
- rm -f /tmp/modify_docker_daemon_opts.py
- systemctl restart docker.service