docker.html.md.erb

---
title: Using Docker in Cloud Foundry
owner: Diego
---

<strong><%= modified_date %></strong>

This topic describes how Cloud Foundry (CF) operators can enable CF developers to run their apps in Docker containers, and explains how Docker works in Cloud Foundry.

For information about Diego, the Cloud Foundry component that manages application containers, see the [Diego Architecture](../concepts/diego/diego-architecture.html) topic.  For information about how CF developers push apps with Docker images, see [Deploy an App with Docker](../devguide/deploy-apps/push-docker.html).

##<a id='enable'></a>Enable Docker

By default, apps deployed with the `cf push` command run in standard Cloud Foundry Linux containers. With Docker support enabled, Cloud Foundry can also deploy and manage apps running in Docker containers.

To deploy apps to Docker, developers run `cf push` with the `--docker-image` option and the location of a Docker image to create the containers from. See the [Push a Docker Image](../devguide/deploy-apps/push-docker.html) topic for information about how CF developers push apps with Docker images.

To enable Docker support on a CF deployment, an operator must do the following:

* [Enable](#feature-flag) the `diego_docker` feature flag.

* [Configure](#access-registry) access to any Docker registries that developers want to use images from.

###<a id='feature-flag'></a>Enable and Disable the diego_docker Feature Flag

The `diego_docker` feature flag governs whether a CF deployment supports Docker containers.

To enable Docker support, run:
<pre class='terminal'>
$ cf enable-feature-flag diego_docker
</pre>

To disable Docker support, run:
<pre class='terminal'>
$ cf disable-feature-flag diego_docker
</pre>

<p class='note'><strong>Note</strong>: Disabling the <code>diego_docker</code> feature flag stops all Docker-based apps in your deployment within a few convergence cycles, on the order of a minute.</p>

###<a id='access-registry'></a>Configure Docker Registry Access

<%= vars.docker_auth %>

##<a id='contents'></a>Docker Image Contents

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.

##<a id='create-container'></a>How Garden-runC Creates Containers##

Diego currently uses Garden-runC to construct Linux containers.

Both Docker and Garden-runC use libraries from the [Open Container Initiative (OCI)](https://www.opencontainers.org/) to build Linux containers.
After creation, these containers use name space isolation, or *namespaces*, and 
control groups, or *cgroups*, to isolate processes in containers and limit 
resource usage.
These are common kernel resource isolation features used by all Linux 
containers.

<%= vars.garden_runc %>

Before Garden-runC creates a Linux container, it creates a file system that is 
mounted as the root file system of the container.
Garden-runC supports mounting Docker images as the root file systems for the 
containers it creates.

When creating a container, both Docker and Garden-runC perform the following 
actions:

* Fetch and cache the individual layers associated with a Docker image
* Combine and mount the layers as the root file system

These actions produce a container whose contents exactly match the contents of 
the associated Docker image.

Earlier 
versions of Diego used Garden-Linux. For more information, see the 
[Garden](../concepts/architecture/garden.html) topic.

##<a id='run-monitor'></a>How Diego Runs and Monitors Processes ##

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

To determine which processes to run, the [Cloud Controller](../concepts/architecture/cloud-controller.html)
fetches and stores the metadata associated with the Docker image.
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](../concepts/architecture/router.html) to route traffic to the lowest-numbered port [exposed](https://docs.docker.com/engine/reference/builder/#expose) in the Docker image, or port 8080 if the Dockerfile does not explicitly expose a listen port.

<p class='note'><strong>Note</strong>: When launching an application on Diego, the Cloud Controller honors any user-specified overrides such as a custom start command or custom environment variables.</p>

##<a id='multi-tenant'></a>Docker Security Concerns in a Multi-Tenant Environment##

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

Garden-runC provides features that 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 users 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.
Docker applications can use fuse mounts through [volume services](../devguide/deploy-apps/push-docker.html#volume), but they cannot directly mount fuse devices from within the container.

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.