Using Docker in Cloud Foundry

Page last updated: December 15, 2015

This topic describes Docker image support in Cloud Foundry with Diego and outlines how Cloud Foundry uses Diego to run Docker images. For more information about Diego, see the Diego Architecture topic.

A Docker image consists of a collection of layers. Each layer consists of one or both of the following:

  • Raw bits to download and mount. These bits form the file system.
  • Metadata that describes commands, users, and environment for the layer. This metadata includes the ENTRYPOINT and CMD directives, and is specified in the Dockerfile.

Creating Containers with Garden-Linux

Diego uses Garden-Linux to construct Linux containers. Garden-Linux builds Linux containers with the same kernel resource isolation features used by all Linux containers: namespaces and cgroups.

Linux container creation requires that a file system is mounted as the root file system of the container. Garden-Linux supports mounting Docker images as root file systems for the containers it constructs. Garden-Linux fetches and caches the individual layers associated with a Docker image, then combines and mounts them as the root file system, using the same libraries that power Docker.

This process yields a container with contents that exactly match the contents of the associated Docker image.

Running and Monitoring Processes with Diego

Once Garden-Linux creates a container, Diego runs and monitors the processes inside of it.

To determine which processes to run, the Cloud Controller fetches the metadata associated with the Docker image and returns it to the Cloud Controller. The Cloud Controller uses this metadata to perform the following actions:

  • Runs the start command as the user specified in the Docker image
  • Instructs Diego and the Gorouter to route traffic to the lowest-numbered port exposed in the Docker image

Note: When launching an application on Diego, the Cloud Controller honors any user-specified overrides such as a custom start command or custom environment variables.

Docker in a Multi-Tenant World

Since Docker allows users to fully specify the contents of their root file systems, the attack surface area for a Docker-based container running on Diego is somewhat higher than that of a buildpack application, which runs on a trusted root filesystem.

The Garden-Linux team has implemented a host of features to allow the platform to run Docker images more securely in a multi-tenant context. In particular, Cloud Foundry uses the user-namespacing feature found on modern Linux kernels to ensure that uses cannot gain escalated privileges on the host even if they escalate privileges within a container.

The Cloud Controller always runs Docker containers on Diego with user namespaces enabled. This security restriction prevents certain features, such as the ability to mount FuseFS devices, from working in Docker containers.

To mitigate security concerns, Cloud Foundry recommends that you run only trusted Docker containers on the platform. By default, the Cloud Controller does not allow Docker-based applications to run on the platform.

To allow Docker-based applications to run, a Cloud Controller administrator can enable the diego_docker feature flag with the following command: 

$ cf enable-feature-flag diego_docker

To disallow Docker-based applications, a Cloud Controller administrator can run the following command:

$ cf disable-feature-flag diego_docker

Note: Disabling the diego-docker feature flag stops all Docker-based apps in your deployment within a few convergence cycles, on the order of a minute.

Pushing a Docker image

Ensure you are running CLI 6.13.0 or a later version. See Getting Started with the cf CLI for installation instructions.

Run the following command to push a Docker image:

cf push lattice-app -o images/lattice-app

where the image is from an accessible Docker Registry such as the lattice-app on Docker Hub.

Note: See Docker Support in CF + Diego for information about pushing a docker image with an earlier version cf CLI.

Docker Caveats

This section contains known issues and limitations with running Docker images in Cloud Foundry.

  • Diego only supports secure registries bearing certificates signed by a common Certificate Authority (CA). Diego does not currently support self-signed certificates.

  • Diego currently only supports v2 Docker registries.

  • Diego is currently susceptible to recently disclosed Docker CVEs (e.g. CVE-2014-8178).

  • Diego does not currently support fetching images from private repositories.

  • Diego currently requires that the source registry for a Docker image is available when creating new application instances. If the registry is unavailable, Diego cannot start or restart applications.