Using Docker in CFAR
Page last updated:
This topic describes how Cloud Foundry Application Runtime (CFAR) operators can enable CFAR developers to run their apps in Docker containers, and explains how Docker works in CFAR.
For information about Diego, the CFAR component that manages app containers, see Diego Components and Architecture. For information about how CFAR developers push apps with Docker images, see Deploying an App with Docker.
By default, apps deployed with the
cf push command run in standard CFAR Linux containers. With Docker support enabled, CFAR 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. For information about how CFAR developers push apps with Docker images, see Push a Docker Image.
To enable Docker support on a CFAR deployment, an operator must:
Configure access to any Docker registries that developers want to use images from.
diego_docker feature flag governs whether a CFAR deployment supports Docker containers.
To enable Docker support, run:
cf enable-feature-flag diego_docker
To disable Docker support, run:
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.
To support Docker, CFAR 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 in the BOSH documentation.
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
CMDdirectives, and is specified in the Dockerfile.
Diego currently uses Garden-runC to construct Linux containers.
Both Docker and Garden-runC use libraries from the Open Container Initiative (OCI) 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.
Earlier versions of Diego used Garden-Linux. For more information, see Garden.
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. For more information about the Gorouter, see Gorouter. For more information about exposed ports in Docker images, see the Expose section of the Dockerfile reference topic in the Docker documentation.
Note: When launching an app on Diego, the Cloud Controller honors any user-specified overrides such as a custom start command or custom environment variables.
The attack surface area for a Docker-based container running on Diego remains somewhat higher than that of a buildpack app because Docker allows users to fully specify the contents of their 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 multi-tenant context. In particular, CFAR 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 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),
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 apps to run on the platform.Create a pull request or raise an issue on the source for this page in GitHub