Flocker Documentation Release 0.3.0dev1 ClusterHQ October 10, 2014 Contents 1 Introduction to Flocker 3 1.1 Motivation for Building Flocker.....................................3 1.2 Architecture...............................................4 1.3 Initial Implementation Strategy.....................................5 1.4 User Experience.............................................6 2 Getting Started 7 2.1 Installing Flocker.............................................7 2.2 Tutorial: Deploying and Migrating MongoDB.............................9 2.3 Flocker Application Examples...................................... 17 2.4 Flocker Feature Examples........................................ 27 3 Advanced Documentation 35 3.1 What’s New............................................... 35 3.2 Using Flocker.............................................. 36 3.3 Configuring Flocker........................................... 37 3.4 Volume Manager............................................. 40 3.5 Data-Oriented Clustering......................................... 42 3.6 Setting up External Routing....................................... 42 3.7 Debugging................................................ 43 3.8 Cleaning Up............................................... 43 4 Getting Involved 45 4.1 Contributing to Flocker......................................... 45 4.2 Infrastructure............................................... 48 5 Areas of Potential Future Development 57 5.1 Flocker Volume Manager........................................ 57 6 FAQ 61 6.1 ZFS.................................................... 61 6.2 Current Functionality........................................... 62 6.3 Future Functionality........................................... 62 7 Authors 63 i ii Flocker Documentation, Release 0.3.0dev1 Flocker is a data volume manager and multi-host Docker cluster management tool. With it you can control your data using the same tools you use for your stateless applications by harnessing the power of ZFS on Linux. This means that you can run your databases, queues and key-value stores in Docker and move them around as easily as the rest of your app. With Flocker’s command line tools and a simple configuration language, you can deploy your Docker-based appli- cations onto one or more Linux hosts. Once deployed, your applications will have access to the volumes you have configured for them. Those volumes will follow your containers when you use Flocker to move them between different hosts in your Flocker cluster. Contents: Contents 1 Flocker Documentation, Release 0.3.0dev1 2 Contents CHAPTER 1 Introduction to Flocker 1.1 Motivation for Building Flocker Flocker lets you move your Docker containers and their data together between Linux hosts. This means that you can run your databases, queues and key-value stores in Docker and move them around as easily as the rest of your app. Even stateless apps depend on many stateful services and currently running these services in Docker containers in production is nearly impossible. Flocker aims to solve this problem by providing an orchestration framework that allows you to port both your stateful and stateless containers between environments. Docker allows for multiple isolated, reproducible application environments on a single node: “containers”. Applica- tion state can be stored on a local disk in “volumes” attached to containers. And containers can talk to each other and the external world via specified ports. But what happens if you have more than one node? • Where do containers run? • How do you talk to the container you care about? • How do containers across multiple nodes talk to each other? • How does application state work if you move containers around? The diagram below provides a high level representation of how Flocker addresses these questions. 3 Flocker Documentation, Release 0.3.0dev1 1.2 Architecture Below is a high-level overview of Flocker’s architecture. For more information, you can follow along with a tutorial that walks you through deploying and migrating MongoDB or read more in our advanced documentation. 1.2.1 Flocker - Orchestration • Flocker can run multiple containers on multiple nodes. • Flocker offers a configuration language to specify what to run and where to run it. 1.2.2 Flocker - Routing • Container configuration includes externally visible TCP port numbers. • Connect to any node on a Flocker cluster and traffic is routed to the node hosting the appropriate container (based on port). • Your external domain (www.example.com) configured to point at all nodes in the Flocker cluster (192.0.2.0, 192.0.2.1) 1.2.3 Flocker - Application State • Flocker manages ZFS filesystems as Docker volumes. It attaches them to your containers. • Flocker provides tools for copying those volumes between nodes. • If an application container is moved from one node to another, Flocker automatically moves the volume with it. 1.2.4 Application Configuration • Application configuration describes what you want to run in a container. – it identifies a Docker image – an optional volume mount point – externally “routed” ports • This configuration is expected to be shared between development, staging, production, etc environments. • Flocker 0.1 does not support automatic re-deployment of application configuration changes. 1.2.5 Deployment Configuration • Deployment configuration describes how you want your containers deployed. – which nodes run which containers. • This configuration can vary between development, staging, production, etc environments. – Developer might want to deploy all of the containers on their laptop. – Production might put database on one node, web server on another node, etc. • Reacting to changes to this configuration is the primary focus of Flocker 0.1. 4 Chapter 1. Introduction to Flocker Flocker Documentation, Release 0.3.0dev1 1.3 Initial Implementation Strategy • This is the 0.1 approach. • Future approaches will be very different; feedback is welcome. • All functionality is provided as short-lived, manually invoked processes. • flocker-deploy connects to each node over SSH and runs flocker-reportstate to gather the cluster state. • flocker-deploy then connects to each node over SSH and runs flocker-changestate to make the necessary deployment changes. • Nodes might connect to each other over SSH to copy volume data to the necessary place. 1.3.1 flocker-changestate • This is installed on nodes participating in the Flocker cluster. • Accepts the desired global configuration and current global state. • Also looks at local state - running containers, configured network proxies, etc. • Makes changes to local state so that it complies with the desired global configuration. – Start or stop containers. – Push volume data to other nodes. – Add or remove routing configuration. 1.3.2 Managing Volumes • Volumes are ZFS filesystems. • Volumes are attached to a Docker “data” container. • Flocker automatically associates the “data” container’s volumes with the actual container. – Association is done based on container names. • Data model * Volumes are owned by a specific node. – Node A can push a copy to node B but node A still owns the volume. Node B may not modify its copy. – Volumes can be “handed off” to another node, i.e. ownership is changed. Node A can hand off the volume to node B. Then node B is now the owner and can modify the volume and node A no longer can. • Volumes are pushed and handed off so as to follow the containers they are associated with. – This happens automatically when flocker-deploy runs with a new deployment configuration. 1.3.3 Managing Routes • Containers claim TCP port numbers with the application configuration that defines them. • Connections to that TCP port on the node that is running the container are proxied (NAT’d) into the container for whatever software is listening for them there. 1.3. Initial Implementation Strategy 5 Flocker Documentation, Release 0.3.0dev1 • Connections to that TCP port on any other node in the Flocker cluster are proxied (NAT’d) to the node that is running the container. • Proxying is done using iptables. 1.4 User Experience • Flocker provides a command-line interface for manually deploying or re-deploying containers across nodes. • The tool operates on two distinct pieces of configuration: – Application – Deployment • Your sysadmin runs a command like flocker-deploy deployment-config.yml application-config.yml on their laptop. 6 Chapter 1. Introduction to Flocker CHAPTER 2 Getting Started Flocker is a lightweight volume and container manager. It lets you: • Define your application as a set of connected Docker containers • Deploy them to one or multiple hosts • Easily migrate them along with their data between hosts The goal of Flocker is to simplify the operational tasks that come along with running databases, key-value stores, queues and other data-backed services in containers. This Getting Started guide will walk you step-by-step through installing Flocker and provide some tutorials that demonstrate the essential features of Flocker. 2.1 Installing Flocker As a user of Flocker you will need to install the flocker-cli package which provides command line tools to control the cluster. This should be installed on a machine with SSH credentials to control the cluster nodes (e.g., if you use our Vagrant setup then the machine which is running Vagrant). There is also a flocker-node package which is installed on each node in the cluster. It contains the flocker-changestate, flocker-reportstate, and flocker-volume utilities. These utilities are called by