docker.html.md.erb

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

<%# Reset page title based on platform type %>
<% if vars.platform_code != 'CF' %>

<% set_title("Using Docker in", vars.app_runtime_abbr) %>

<% end %>

You can activate Docker support so <%= vars.app_runtime_abbr %> can deploy and manage apps based on Docker container images.

For information about Diego, the <%= vars.app_runtime_first %> component that manages app containers, see
[Diego Components and Architecture](../concepts/diego/diego-architecture.html). For information about how <%= vars.app_runtime_abbr %> developers push apps with Docker images, see [Deploying an App with Docker](../devguide/deploy-apps/push-docker.html).


## <a id='enable'></a> Activate Docker image support

By default, apps deployed with the `cf push` command run in <%= vars.app_runtime_abbr %> containers based on standard filesystems that come bundled with <%= vars.platform_code %>. With Docker
support activated, <%= vars.app_runtime_abbr %> can also deploy and manage apps based on Docker container images.

To deploy Docker-image-based apps, developers run `cf push` with the `--docker-image` option and the location of a Docker image from which to create the containers. For information about how <%= vars.app_runtime_abbr %> developers push apps with Docker images, see [Push a Docker Image](../devguide/deploy-apps/push-docker.html).

To activate Docker support on a <%= vars.app_runtime_abbr %> deployment, you must:

* Activate the `diego_docker` feature flag.

* Configure access to any Docker registries that you want to use images from.

Configuring these properties requires admin-level access to the <%= vars.app_runtime_abbr %> deployment, and cannot be done by individual app developers.

### <a id='feature-flag'></a> Enable and deactivate the diego_docker feature flag

The `diego_docker` feature flag governs whether a <%= vars.app_runtime_abbr %> deployment supports Docker-image-based containers.

To activate Docker image support, run:

```
cf enable-feature-flag diego_docker
```

To deactivate Docker image support, run:

```
cf disable-feature-flag diego_docker
```

<p> Deactivating the <code>diego_docker</code> feature flag stops
all Docker-image-based apps in your deployment within a few convergence cycles, on the order of a one minute.</p>

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

To support Docker-image-based apps, <%= vars.app_runtime_abbr %> needs the ability to access Docker registries
using either a Certificate Authority or an IP address allow list. For information about
configuring this access, see [Installing Certificates on VMs](https://bosh.io/docs/trusted-certs/).


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

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:

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

For earlier versions of Diego using Garden-Linux, see [Garden](../concepts/architecture/garden.html).


## <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 fetches and stores the metadata associated with the
Docker image. The Cloud Controller uses this metadata to:

* Run the start command as the user specified in the Docker image.

* Instruct Diego and the Gorouter to route traffic to the lowest-numbered port exposed in the Docker image, or port 8080 if the Dockerfile does not explicitly expose a listen port.

For more information about Cloud Controller, see [Cloud Controller](../concepts/architecture/cloud-controller.html).

For more information about Gorouter and the routing tier, see [<%= vars.app_runtime_abbr %> Routing Architecture](../concepts/cf-routing-architecture.html).

For more information about exposed ports in Docker images, see the [Expose](https://docs.docker.com/engine/reference/builder/#expose) section of the _Dockerfile reference_ topic in the
Docker documentation.

<p> When you launch an app on Diego, the Cloud Controller honors any user specified overrides. For example, 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-image-based container that runs on Diego remains somewhat higher than that of a buildpack app
because Docker allows you to fully specify the contents of your root file systems. A buildpack app runs on a trusted root filesystem.

Garden-runC provides features that allow the platform to run Docker images more securely in a multitenant context. In
particular, <%= vars.app_runtime_abbr %> 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, for example, the ability to mount FuseFS devices, from working in Docker containers. Docker apps can use
fuse mounts through volume services, but they cannot directly mount fuse devices from within the container.

For more information about volume services, see [Using an External File System (Volume Services)](../devguide/services/using-vol-services.html).

To mitigate security concerns, <%= vars.company_name %> run only trusted Docker containers on the platform. By default,
the Cloud Controller does not allow Docker based apps to run on the platform.