Overview
This is an Open Preview release of containers on Virtual Machines. As a result, we may make backward-incompatible changes and it is not covered by any SLA or deprecation policy. Customers should take this into account when using this Open Preview release.
Google Compute Engine is extending its support for Docker containers. This release is a Preview release of a container-optimized OS image that includes Docker and a Kubernetes Kubelet—an open source agent to manage containers.
The container OS image includes:
- Debian 7.
- The Docker runtime. To learn more about Docker, visit www.docker.io.
- An open-source metadata framework and the Kubernetes Kubelet—a lightweight agent to create and manage containers based on the metadata.
Get involved
We encourage you to be involved in the development and design of the image and the related open source projects:
- Give early feedback and talk with the community (including the developer team) on the google-containers mailing list.
- Ask development and best practices questions on Stack Overflow.
- Browse and contribute to the Kubernetes project on GitHub.
- Chat with the community on IRC.
- Nominate a project for our early adopter program for companies.
- For questions about Docker images or with Docker in general, we encourage you to join the very active Docker community.
Starting a bare container-vm instance
A container VM image is specified like any other Google Compute Engine image,
as an argument to the --image flag of the gcloud compute instances create
command:
$ gcloud compute instances create instance-name \
--image container-vm \
--zone us-central1-a \
--machine-type f1-micro
You can list all available versions with:
$ gcloud compute images list --project google-containers
Once the instance is running, you can SSH into the instance and use the Docker command line tool to create and manage your containers.
Creating containers at time of instance creation
The container VM image includes the Kubernetes Kubelet - an agent that can parse a YAML-formatted list of containers and create those containers at the instance's boot time. The Kubelet also monitors the listed containers, restarting them should they fail at any time.
This manifest is passed to the
--metadata-from-file
flag of gcloud compute instances create as a key/value pair whose key is always
google-container-manifest. The value of the pair is the relative path to a
manifest.
--metadata-from-file google-container-manifest=containers.yaml
All of the containers in the group share the same network namespace;
you can connect from one container to a service running on another container
using localhost and the port of the service. Two containers of the same
group cannot run services on the same port.
Quickstart example
The following example creates a new Compute Engine instance with a
busybox container. The container responds to incoming streams on
port 8080 with "hello world".
Create the manifest
Create a containers.yaml file with the following contents:
version: v1beta2
containers:
- name: simple-echo
image: busybox
command: ['nc', '-p', '8080', '-l', '-l', '-e', 'echo', 'hello world!']
ports:
- name: nc-echo
hostPort: 8080
containerPort: 8080
Create the instance
Create your Google Compute Engine instance with the
gcloud compute instances create command, and pass the manifest using the
--metadata-from-file flag:
$ gcloud compute instances create containervm-test-1 \
--image container-vm \
--metadata-from-file google-container-manifest=containers.yaml \
--zone us-central1-a \
--machine-type f1-micro
Test your app
Your new instance is up and running and contains the Docker container you specified in the manifest. To test it, SSH into your instance:
$ gcloud compute ssh --zone us-central1-a containervm-test-1
To confirm that the container has been created:
me@containervm-test-1:~$ sudo docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
eb8cfe4e7848 busybox:latest nc -p 8080 -l -l -e 12 minutes ago Up 12 minutes simple-echo
1e72de9888bb busybox:latest sh -c 'rm -f nap && 12 minutes ago Up 12 minutes 0.0.0.0:8080->8080/tcp .net
Use netcat to query the container:
me@containervm-test-1:~$ nc localhost 8080
hello world!
More examples
The Container VM Guestbook GitHub repository contains another example of using GCE container VMs to run Docker containers. It demonstrates the deployment of a Redis database and a simple Python app to create a guestbook app with local storage.
Container manifest
The YAML file is formatted as follows:
version: v1beta2 // Required.
containers: // Required.
- name: string // Required.
image: string // Required.
command: [string]
workingDir: string
volumeMounts:
- name: string
mountPath: string
readOnly: boolean
ports:
- name: string
containerPort: int
hostPort: int
protocol: string
env:
- name: string
value: string
restartPolicy:
- string: {}
volumes:
- name: string
source: emptyDir | HostDir
emptyDir: {}
hostDir:
path: string
| Field name | Value type | Required? | Spec |
|---|---|---|---|
| version | string | Required | The version of the manifest. Must be v1beta2. |
| containers[] | list | Required | The list of containers to launch. |
| containers[].name | string | Required | A symbolic name used to create and track the container. Must be an RFC1035 compatible value (a single segment of a DNS name). All containers must have unique names. |
| containers[].image | string | Required | The container image to run. |
| containers[].command[] | list of string | The command line to run. If this is omitted, the container is assumed to have a command embedded in it. | |
| containers[].workingDir | string | The initial working directory for the command. Default is the container’s embedded working directory or else the Docker default. | |
| containers[].volumeMounts[] | list | Data volumes to expose into the container. | |
| containers[].volumeMounts[].name | string | The name of the volume to mount. This must match the name of a volume defined in volumes[]. | |
| containers[].volumeMounts[].mountPath | string | The path at which to mount the volume inside the container. This must be an absolute path and no longer than 512 characters. | |
| containers[].volumeMounts[].readOnly | boolean | Whether this volume should be read-only. Default is false (read-write). |
|
| containers[].ports[] | list | Ports to expose from the container. All of these are exposed out through the public interface of the VM. | |
| containers[].ports[].name | string | A symbolic name used to create and track the port. Must be an RFC1035 compatible value (a single segment of a DNS name). | |
| containers[].ports[].containerPort | int | The port on which the container is listening. | |
| containers[].ports[].hostPort | int | The port on the host which maps to the containerPort. Default is the same as containerPort. |
|
| containers[].ports[].protocol | string | The protocol for this port. Valid options are TCP and UDP. Default is TCP. |
|
| containers[].env[] | list | Environment variables to set before the container runs. | |
| containers[].env[].name | string | The name of the environment variable. | |
| containers[].env[].value | string | The value of the environment variable. | |
| restartPolicy | object | The restart policy for this pod of containers. The following values are accepted:
"restartPolicy": {Default is |
|
| volumes[] | list | A list of volumes to share between containers. | |
| volumes[].name | string | The name of the volume. Must be an RFC1035 compatible value (a single segment of a DNS name). All volumes must have unique names. These are referenced by containers[].volumeMounts[].name. |
|
| volumes[].source | object | The kind of volume. The value can be a hostDir with an existing path, or emptyDir (the default) which represents a temporary directory that shares a pod's lifetime. |
|
| volumes[].source.emptyDir | object | The default volume source. Specifies that the volume being mounted is a temporary directory that shares the pod's lifetime. The value of emptyDir is an empty object:emptyDir: {} |
|
| volumes[].source.hostDir | object | Specifies that the volume being mounted is an existing directory on the host machine. Requires volumes[].source.hostDir.path. |
|
| volumes[].source.hostDir.path | string | The path of an existing directory on the host machine to expose to the container. |
Example manifest file
The file below:
- Creates three containers: the
google/docker-registrythat allows you to push/pull images from Google Cloud Storage, and a client and a server image pulled from that registry. - Creates a Docker
data volume called
data. - Mounts
dataon two of the containers. - Mounts the host machine's
/tmpdirectory on one container as/host_tmp. - Opens up ports on two containers.
- Specifies environment variables on the
repositorycontainer to set before the container is run.
version: v1beta2
containers:
- name: repository
image: google/docker-registry
ports:
- name: registry
containerPort: 5000
env:
- name: GCS_BUCKET
value: my-private-repo-bucket
- name: client
image: localhost:5000/data-loader
volumeMounts:
- name: data
mountPath: /mnt/data
- name: server
image: localhost:5000/data-server
ports:
- name: www
containerPort: 80
volumeMounts:
- name: data
mountPath: /mnt/data
- name: tmp
mountPath: /host_tmp
volumes:
- name: data
- name: tmp
source:
hostDir:
path: /tmp
In order to use the Docker registry launched by this manifest, you must enable read-write permission to your Google Cloud Storage buckets when creating the instance:
$ gcloud compute instances create registry-example \
--scopes storage-rw \
--image container-vm \
--metadata-from-file google-container-manifest=containers.yaml \
--zone us-central1-a \
--machine-type f1-micro
Changelog
- January 12, 2015
-
The image has been updated to
container-vm-v20150112- Upgrade docker to 1.4.1
- Upgrade kubelet (kubernetes agent) to 0.7.4
- Reduced size of initramfs for faster boot.
- Bundled docker images for kubernetes/pause and cAdvisor.
- The "container-vm" alias automatically points to this image.
- December 8, 2014
-
The image has been updated to
container-vm-v20141208- Upgrade docker to 1.3.2
- Upgrade kubelet (kubernetes agent) to 0.5.4
- "container-vm" image alias has been created.
Specifying
--image container-vmwhen creating an instance starts up the most recent version of the container-optimized image.
- October 16, 2014
-
The image has been updated to
container-vm-v20141016 - September 29, 2014
-
The image has been updated to
container-vm-v20140929.- Upgrade bash to 4.2+dfsg-0.1+deb7u1 to fix vulnerability CVE-2014-7169.
- September 25, 2014
-
The image has been updated to
container-vm-v20140925.- Upgrade bash to 4.2+dfsg-0.1+deb7u1 to fix vulnerability CVE-2014-6271.
- August 26, 2014
-
The image has been updated to
container-vm-v20140826.- Kubelet built from Kubernetes source code, trunk head as of 2014-08-22.
hostPortis required to be explicitly specified if a port mapping between container port and host port is required.- Docker 1.2 is included.
- nsinit is included.
- Google Cloud SDK is included.
- August 1, 2014
-
The image has been updated to
container-vm-v20140731.- The new image uses Docker 1.1.2.
- cAdvisor is started by default, listening on port 4194.
- July 17, 2014
-
The image has been updated to
container-vm-v20140710.- The new image uses the Kubernetes Kubelet instead of
container-agent. versionis incremented tov1beta2.containers[].env[].keybecomescontainers[].env[].namecontainers[].volumeMounts[].pathbecomescontainers[].volumeMounts[].mountPath
- The new image uses the Kubernetes Kubelet instead of
The v1beta1 format can still be used with the original
container-vm-v20140522 image.