Building a manifest file

Overview

A manifest file (manifest.yml) allows you to be more explicit about the composition of your application and control settings that are not usually available through the user interface or Cloud 66 Toolbelt.

The file describes the setup of the components that run your application. See Getting started with manifest files for an introduction.

In Maestro there are two opportunities to edit your manifest file:

Once you’re ready, start by going through each section below to build your manifest file.

Important

It is vital that you understand the limits and caveats of manifest settings. Please read our reference guide before you start creating your own manifest files.

Which environment?

The first level of your manifest file is the environment - this allows you to use the same manifest.yml for multiple applications with different environments. Some examples are:

You can also use your own custom environment names in your manifest file.

Which component?

Next, select which component you would like to specify settings for. You can choose from the following:

Docker

Examples

production:
  docker:
    configuration:
      version: 1.7.0
      weave_version: 1.0.3
      vpc_id: vpc-64872001
      root_disk_size: 100
      root_disk_type: ssd
      image_keep_count: 5
      nameservers: ['8.8.8.8', '8.8.4.4']
production:
  docker:
    configuration:
      version: 1.12.0
      weave_version: 1.0.3
      vn_name: your_vn_name
      root_disk_size: 100
      root_disk_type: ssd
      image_keep_count: 15

ElasticSearch

Example

production:
  elasticsearch:
    configuration:
      version: 0.90.7
      root_disk_size: 100
      root_disk_type: ssd

Gateway

Note:

The gateway must be defined and open before you can use it in manifest.

Example

production:
  gateway:
    name: aws_bastion
    username: ec2-user

GlusterFS

Notes

You cannot change replica_count after GlusterFS has been added to your application.

You cannot use the GlusterFS group or any of its servers in mount_targets.

Available settings for a volume are:

After you change the volume list, you need to redeploy your application for new configuration be applied to your application.

Warning

Renaming a volume will delete volume and create a new one.

Example

production:
  glusterfs:
    configuration:
      version: 3.7
      replica_count: 2
      mount_targets: ['app','redis']
      volumes:
      - volume:
        name: images-data
        mount: "/mnt/images"
        access_control:
          read: ['web', 'api']
          write: ['web']
      - volume:
        name: videos
        mount: /mnt-data/videos
        access_control:
          read: ['web']
          write: ['web']

Memcached

production:
  memcached:
    configuration:
      memory: 1024
      port: 11211
      listen_ip: 127.0.0.1

MongoDB

production:
  mongodb:
    configuration:
      version: 2.4.8
      root_disk_size: 100
      root_disk_type: ssd

MySQL

production:
  mysql:
    configuration:
      version: 5.5
      root_disk_size: 100
      root_disk_type: ssd
      engine: percona

Nginx

production:
 docker:
  configuration:
   nginx:
     cors: true
     extra-build-arguments: "--add-module=/path/to/module"
     perfect_forward_secrecy: true # deprecated

CORS configuration

If required, you can also specify the allowed origin (as ‘*’ or a single origin) and methods. For applications created since 21st September 2016, you can also specify a comma-separated list of origins, headers, and whether to allow credentials for CORS.

production:
 docker:
  configuration:
   nginx:
    cors:
     origin: '*'
     methods: 'GET, OPTIONS'
     headers: 'Custom-Header, Another-Header'
     credentials: true

PostgreSQL

production:
  postgresql:
    configuration:
      version: 9.3.4
      postgis: true
      root_disk_size: 100
      root_disk_type: ssd

PostGIS

production:
  postgresql:
    configuration:
      postgis:
        version: 2.1.1

Redis

production:
  redis:
    configuration:
      version: 2.6.10
      root_disk_size: 100
      root_disk_type: ssd

Load balancers

AWS load balancer

Use a manifest file to customize the AWS load balancer deployed by Cloud 66. These changes will only apply when you create a new load balancer.

Available settings:

production:
  load_balancer:
    configuration:
      httpchk: /

GCE load balancer

Use a manifest file to customize the GCE load balancer deployed by Cloud 66. These changes will only apply when you create a new load balancer.

Available settings (refer to the GCE documentation for more information):

production:
  load_balancer:
    configuration:
      httpchk: /
      balance: CLIENT_IP_PROTO

HAProxy

Use a manifest file to configure and define your HAProxy load balancer deployed by Maestro. These changes will be applied when you redeploy an application with more than one server, rebuild HAProxy or edit HAProxy CustomConfig.

Available settings (refer to the HAProxy documentation for more information):

Server definitions:

Configuration:

Example

production:
  load_balancer:
    servers:
    - server:
        unique_name: bananana
        size: 1gb
        region: ams2
        vendor: digitalocean
        key_name: Default
    configuration:
      httpchk: HEAD / HTTP/1.1\r\nHost:haproxy  #default value
      balance: roundrobin #default value
      errorfile_400: /etc/haproxy/errors/400.http
      errorfile_403: /etc/haproxy/errors/403.http
      errorfile_408: /etc/haproxy/errors/408.http
      errorfile_500: /etc/haproxy/errors/500.http
      errorfile_502: /etc/haproxy/errors/502.http
      errorfile_503: /etc/haproxy/errors/503.http
      errorfile_504: /etc/haproxy/errors/504.https

Linode Nodebalancer

Use a manifest file to the Linode Nodebalancer deployed by Cloud 66. These changes will only apply when you create a new load balancer.

Available settings (refer to the Linode documentation for more information):

Example

production:
  load_balancer:
    configuration:
      httpchk: /
      balance: leastconn

Rackspace load balancer

Use a manifest file to customize the Rackspace load balancer deployed by Cloud 66. These changes will only apply when you create a new load balancer.

Available settings (refer to the Rackspace documentation for more information):

Example

production:
  load_balancer:
    configuration:
      balance: LEAST_CONNECTIONS

CloudA load balancer

Use a manifest file to customize the CloudA load balancer deployed by Cloud 66. These changes will only apply when you create a new load balancer.

production:
  load_balancer:
    configuration:
      balance: ROUND_ROBIN

Which server?

Every application defined in the manifest file must be bound to a server. However, if you’d like configurations to apply to all servers in an application type, you don’t need to specify a server type. Servers can be deployed specifically to host that application, be shared between multiple applications (eg. Docker and MySQL on the same server) or be an external server (eg. using an external database).

Here is an example of a server definition:

production:
  docker:
    servers:
    - server:
      unique_name: app

The server section has the following available parameters:

Important!

Only a single cloud vendor and region is supported for servers running an application.

production:
  docker:
    servers:
      server:
        unique_name: app
        vendor: aws
        key_name: Default
        region: us-east-1
        size: m3.medium
        root_disk_size: 100
        root_disk_type: ssd
        subnet_id: subnet-40000000
        availability_zone: us-east-1c

Deploy to your own server

production:
  docker:
    server:
      unique_name: frontend
      address: 123.123.123.123

Shared Servers

You can share a server between two components, for example using the same server for both your Maestro app and the MySQL server supporting it.

Each shared server definition specifies the name of another server definition in the manifest file for which the applications will then share the physical server:

production:
  docker:
    server:
      same_as: *another_existing_servers_unique_name*

External Servers

If you would like to use an external server for an application (like using your own MySQL or AWS RDS for example), you can define that server as external.

External server definitions specify that the application is hosted on a server external to Cloud 66. This is not a valid target for your main application (ie. Maestro) but may be appropriate for another application type (ie. MongoDB):

production:
  mysql:
    server: external

Important!

You are required to specify a server for application types, whereas configurations are optional.

Specify environment variables

You can add your environment variables to your manifest files.

Here is an example:

production:
  environment_variables:
    SOME_VARIABLE: value
    ANOTHER_ONE: another_value
    THIRD_ONE: AUTO_GENERATE
    LONG_ONE: AUTO_GENERATE_15

If you need to auto-generate a value, you can use the AUTO_GENERATE keyword. It generates a 10 character long random string unless you specify the length after it: AUTO_GENERATE_15 which generates a 15 character random string.

Environment variables set in your manifest file will only apply during the initial build of your application. Please refer to our documentation on environment variables if you’d like to set them beyond this point.

Any environment variable that is generated by the result of the code analysis (like database addresses) will override any value specified in the manifest file. In other words, you cannot specify a value like MYSQL_ADDRESS in your manifest file as it will be ignored.

Specify additional LiveLog files

Each application type supports the additional partial configuration to add custom live log files for that application type:

production:
  docker:
    configuration:
      custom_log_files: ["/tmp/mylog/*/*.log"]

For more information about LiveLogs and additional examples, please see the LiveLogs help page.

Test experimental features

You can use some features that are still in beta by adding them to experiments section of your manifest file, for example:

production:
  experiments:
    docker_storage: overlay

These are the parameters that the experiments section currently accepts: