Configuring Flocker

Flocker operates on two configuration files: application and deployment. Together these configurations define a deployment.

The configuration is represented using yaml syntax.

Application Configuration

The application configuration consists of a version and short, human-meaningful application names and the parameters necessary to run those applications.

The required parameters are version and applications. For now the version must be 1.

The parameters required to define an application are:

  • image

    This is the name of the Docker image which will be used to start the container which will run the application. Optionally, this may include a tag using the <name>:<tag> syntax.

    For example, an application which is meant to use version 1.0 of ClusterHQ’s flocker-dev Docker image is configured like this:

    "image": "clusterhq/flocker-dev:v1.0"
    

The following parameters are optional when defining an application:

  • ports

    This is an optional list of port mappings to expose to the outside world. Connections to the external port on the host machine are forwarded to the internal port in the container.

    "ports":
    - "internal": 80
      "external": 8080
    
  • links

    This is an optional list of links to make to other containers, providing a mechanism by which your containers can communicate even when they are located on different hosts. Linking containers in Flocker works by populating a number of environment variables in the application specifying a link.

    The environment variables generated are named for the specified alias and local port, while their values will point to the configured remote port. For example, given an application configuration containing a links section as follows:

    "links":
    - "local_port": 80
      "remote_port": 8080
      "alias": "apache"
    

    The above configuration will produce environment variables in that application using the same format as generated by Docker:

    APACHE_PORT_80_TCP=tcp://example.com:8080
    APACHE_PORT_80_TCP_PROTO=tcp
    APACHE_PORT_80_TCP_ADDR=example.com
    APACHE_PORT_80_TCP_PORT=8080
    

    Warning

    As you may have noticed in the example above, unlike Docker links, the destination port will not be the port used to create the environment variable names. Flocker implements linking via the ports exposed to the network, whereas Docker creates an internal tunnel between linked containers, an approach that is not compatible with the deployment of links across multiple nodes.

    Note

    Only TCP links are supported by Flocker, therefore the TCP portion of the environment variable names and the tcp value of the _PROTO and _TCP variables are not configurable.

  • volume

    This specifies that the application container requires a volume. It also allows you to specify where in the container the volume will be mounted via the mountpoint key. The value for this key must be a string giving an absolute path.

    "volume":
      "mountpoint": "/var/www/data"
    
  • environment

    This is an optional mapping of key/value pairs for environment variables that will be applied to the application container. Keys and values for environment variables must be strings and only ASCII characters are supported at this time.

    "environment":
      "foo": "bar"
      "baz": "qux"
    

Here’s an example of a simple but complete configuration defining one application:

"version": 1
"applications":
  "site-clusterhq.com":
    "image": "clusterhq/clusterhq-website"
    "environment":
      "WP_ADMIN_USERNAME": "administrator"
      "WP_ADMIN_PASSWORD": "password"
    "ports":
    - "internal": 80
      "external": 8080
    "volume":
      "mountpoint": "/var/mysql/data"

Deployment Configuration

The deployment configuration specifies which applications are run on what nodes. It consists of a version and a mapping from node names to application names.

The required parameters are version and applications. For now the version must be 1.

Here’s an example of a simple but complete configuration defining a deployment of one application on one host:

"version": 1
"nodes":
  "node017.example.com":
    "site-clusterhq.com"