Using Manifest files

What is a manifest file?

A manifest files allows you to be more explicit about your application composition 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 make up your application.

These are just some examples of the settings you can control with a manifest file:

• Defining sizes and data center region for your servers
• Specifying the version of a component
• Configuring application components to share a server
• Customizing component-specific configurations

Manifest Tutorial

In this example we are going to modify the configuration of the simple application we used in our Getting started guide.

Updating the Manifest file

Next, deploy your application and the new setting will take effect!

Defining a server for your component

The Manifest file gives you a lot of control over your components. For example, you can use the server settings to specify the exact size and region for your application server. The YAML below is an example of this in action:

• You can find the available values for size and region in our API documentation.
• You can find the key_name for your cloud provider(s) listed on your Dashboard.

The structure of a Manifest file

Manifest files are made up of blocks of settings that define the infrastructural elements of your application. This includes both the “hardware” (virtual or real servers) and the “software” (such as the version of Docker your application uses).

A typical block of settings will contain some combination the following:

• Environment (optional) - the environment to which the settings apply
• Component settings (required) - the settings for the component being configured (e.g. MySQL or an AWS Load Balancer)
• Server definition (optional) - the specifications for the server used by the component defined in the settings above
• Custom log files (optional) - each component can be configured to use custom LiveLog files

You can also control and customize some other elements in your Manifest including:

• Environment variables - you can set environment variables for your app
• Background processes - you can customize the Linux signals used to control your background processes

Environment settings

The (optional) environment setting allows you to use the same manifest.yml for multiple applications with different environments. Some examples are:

• production
• staging
• development

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

Applying settings across all environments

If you would like your manifest setting to apply to all environments, you can simple drop the root level environment node from your YAML. This will ensure a component is always provisioned, regardless of environment.

Component settings

The (mandatory) component settings define how a component is configured. The Manifest file currently supports the following components (click on any component name for details):

Server definitions

Every component defined in the manifest file must be bound to a server. However, if you'd like configurations to apply to all your servers, you don't need to specify a server type.

Servers can be deployed specifically to host a single component, be shared between multiple components (e.g. Rails and MySQL on the same server) or be an external server (e.g. using an external database).

Here is an example of a simple server definition:

rails:
  servers:
  - server:
      unique_name: app

These are the parameters that the server section can take:

A more complex server example

rails:
  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

Specifying a VPC for your application

You can configure a “virtual private cloud” (VPC) for your application if your cloud provider supports it. This is essentially a private network that your instances are able to communicate over. Depending on your cloud provider, adding a VPC requires different steps (see below).

These settings are only applied when an application is first built. To change them, you will need to update the manifest and then clone (rebuild) the application

VPC on AWS

1. Set up a VPC on your AWS account and take note of the VPC and subnet IDs
2. Add these values to the manifest entry for your application settings. For example the settings for a Rails app might be:

rails:
  configuration:
    vpc_id: my-private-vpc
    subnet_id: my-subnet-id

VPC on Microsoft Azure

To set up a VPC on Azure, you can either

• Add a Virtual Network via your Azure dashboard and then add the name to your manifest file

• Specify a VPC name in the application section of your manifest file and we will create one on your behalf using that name

For example:

docker:
  configuration:
    vpc_id: my-private-azure-network

VPC on DigitalOcean

You can either:

• Add a VPC to your DigitalOcean account and then add the name to your manifest file
• Specify a VPC name in the application section of your manifest file and we will create one on your behalf using that name

For example:

docker:
  configuration:
    vpc_id: my-private-do-vpc

VPC on Hetzner Cloud

You can either:

• Add a VPC in your Hetzner account and then add the name to your manifest file
• Specify a VPC name in the application section of your manifest file and we will create one on your behalf using that name

For example:

docker:
  configuration:
    vpc_id: my-private-hetzner-vpc

Specifying an operating system version

Cloud 66 uses Ubuntu as our operating system. By default we use the current LTS version of Ubuntu, but you can explicitly set a component to use an older version if you need to. Be aware that the operating_system setting is a feature of components (e.g. MySQL, Redis or Rails) and not servers.

The operating_system setting is currently available for:

• Application frameworks (Rails, docker etc.)
• ElasticSearch
• MySQL
• MongoDB
• Postgres
• Redis

Acceptable values are: ubuntu1804, ubuntu2004 or ubuntu2204

For example:

rails:
  configuration:
    ...
    operating_system: ubuntu2204

See below for detailed settings for each of these components.

Deploy to your own server

You can deploy to one of your Registered servers via manifest settings. The server must be registered before deployment.

Example of registered server

redis:
  servers:
  - server:
      unique_name: redis-main
      address: 123.123.123.123

Shared Servers

You can share a server between two components. This allows you to, for example, use a server for both your front-end app and the database server backing it.

Example of shared server

rails:
  servers:
  - server:
      unique_name: my_rails_app
      vendor: aws
      key_name: Default
      region: us-east-1
      size: m3.medium
mongodb:
  servers:
  - server:
      same_as: my_rails_app

External Servers

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

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

mysql:
  servers:
  - server: external

Custom LiveLog files

You can add custom live log files for each component. For example:

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

...or

docker:
  configuration:
    custom_log_files: ["/tmp/dockerlog/*/*.log"]
postgresql:
  configuration:
    custom_log_files: ["/tmp/your-other-log.log"]

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

Environment variables

You can add environment variables to your manifest files, either globally or per environment. For example:

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.

Detailed examples of Manifest files

In this example we're defining a MySQL server with all the bells and whistles:

mysql:
  groups:
    default:
      configuration:
        version: 8.0
        root_disk_size: 1000
        root_disk_type: ssd
        engine: percona
        iam_instance_profile_name: mysql-perms
        custom_log_files: [ "/tmp/mysqllog/*/*.log" ]
      servers:
      - server:
          unique_name: mysql-main
          vendor: aws
          key_name: Default
          region: us-east-1
          size: m3.medium
          subnet_id: subnet-40000000
          availability_zone: us-east-1c

In this example we're defining a Rails app and an accompanying MySQL instance, and applying these settings only in the production environment:

production:
  rails:
    configuration:
      ruby_version: 2.7.2
      asset_pipeline_precompile: true
      do_initial_db_schema_load: false
      reserved_server_memory: 0 #default value
      passenger_process_memory: 200 #default value
      memory_allocator: jemalloc # malloc is default
    servers:
    - server:
      unique_name: rails-main
      vendor: aws
      key_name: Default
      region: us-east-1
      size: m3.medium
      subnet_id: subnet-40000000
      availability_zone: us-east-1c
  mysql:
    groups:
      default: 
        configuration:
          version: 8.0

Notice that we haven't specified a server for the MySQL instance in this YAML. In cases like this the Cloud 66 Dashboard will prompt you to specify a server during the deployment process, and that server will be installed with MySQL V8.0.

Manifest settings for web components

Key to table headings

• Option - the name of the setting as used in the YAML of your Manifest file
• Applied on - the type of deployment required to update this setting. In many cases settings only apply when an application is first built, or when new servers are created or it is cloned. Hover over the names of each condition to see more info.
• Clouds - the cloud providers on which a setting can be used.

Gateway

The following settings are available via the Manifest file:

Example YAML for gateway

gateway:
  name: aws_bastion
  username: ec2-user

Nginx

Nginx is the default webserver & reverse proxy for applications managed by Cloud 66.

The following settings are available via the Manifest file:

Example YAML for Nginx

CORS configuration

If required, you can also specify the allowed origin (as '*' or a single origin) and methods. You can also specify a comma-separated list of origins, headers, and whether to allow credentials for CORS.

Post-deployment availability checks

You can configure your application to automatically run global availability checks against an HTTP endpoint each time it is deployed. Results of these checks are available on your Cloud 66 dashboard under ActiveProtect.

The following settings are available via the Manifest file:

Example YAML for post-deployment global availability checks

Manifest settings for databases

Key to table headings

• Option - the name of the setting as used in the YAML of your Manifest file
• Applied on - the type of deployment required to update this setting. In many cases settings only apply when an application is first built, or when new servers are created or it is cloned. Hover over the names of each condition to see more info.
• Clouds - the cloud providers on which a setting can be used.

ElasticSearch

Elasticsearch is a search engine based on the Lucene library. It provides a distributed, multitenant-capable full-text search engine with an HTTP web interface and schema-free JSON documents.

The following settings are available via the Manifest file:

Example YAML for ElasticSearch

elasticsearch:
  configuration:
    iam_instance_profile_name: elastic-perms
    version: 0.90.7
    root_disk_size: 1000
    root_disk_type: ssd

If you need help specifying multiple databases of the same type via your Manifest, please read our guide on Database Groups.

GlusterFS

GlusterFS is a scalable network filesystem suitable for data-intensive tasks such as cloud storage and media streaming.

Restrictions with GlusterFS

• Renaming a volume will actually delete that volume and create a new one.
• After you change the volume list, you need to redeploy your application for new configuration be applied to your application.
• You cannot change replica_count after GlusterFS added to your application.
• You cannot use glusterfs group or any of its servers in mount_targets.

The following settings are available via the Manifest file:

Example YAML for GlusterFS

glusterfs:
  configuration:
    version: 11.0
    replica_count: 2
    mount_targets: ['app','redis']

Memcached

Memcached is a general-purpose distributed memory-caching system. It is often used to speed up dynamic database-driven websites by caching data and objects in RAM to reduce the number of times an external data source must be read.

The following settings are available via the Manifest file :

Example YAML for Memcached

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

MongoDB

MongoDB is a cross-platform document-oriented database program. Classified as a NoSQL database program, MongoDB uses JSON-like documents with optional schemas.

The following settings are available via the Manifest file :

Example YAML for MongoDB

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

If you need help specifying multiple databases of the same type via your Manifest, please read our guide on Database Groups.

MySQL

MySQL is an open-source relational database management system.

The following settings are available via the Manifest file :

Example YAML for MySQL

mysql:
  configuration:
    version: 5.7
    root_disk_size: 100
    root_disk_type: ssd
    engine: percona
    encoding: koi8u
    iam_instance_profile_name: mysql-perms

If you need help specifying multiple databases of the same type via your Manifest, please read our guide on Database Groups.

Postgres

Postgres is a powerful, open source object-relational database system with over 30 years of active development that has earned it a strong reputation for reliability, feature robustness, and performance.

The following settings are available via the Manifest file :

Example YAML for Postgres

postgresql:
  configuration:
    iam_instance_profile_name: psql-perms
    version: 9.3.4
    encoding: ISO_8859_8
    postgis: true
    root_disk_size: 100
    root_disk_type: ssd

If you need help specifying multiple databases of the same type via your Manifest, please read our guide on Database Groups.

Example YAML for PostGIS

postgresql:
  configuration:
    postgis:
      version: 2.1.1

Redis

Redis is an in-memory data structure store, used as a distributed, in-memory key–value database, cache and message broker, with optional durability.

The following settings are available via the Manifest file :

Example YAML for Redis

redis:
  configuration:
    version: 5.0.5
    root_disk_size: 100
    root_disk_type: ssd
    iam_instance_profile_name: redis-perms

If you need help specifying multiple databases of the same type via your Manifest, please read our guide on Database Groups.

Specifying external databases via your manifest

If your app uses databases that aren't managed by Cloud 66 you can still specify them via your Manifest. To set a database as external via your manifest, use the following syntax:

# For example, an external MySQL server
mysql: 
  server: external

Manifest settings for load balancers

Azure load balancer

You can use your Manifest file to customize the Azure load balancer deployed by Cloud 66.

The following settings are available via the Manifest file:

AWS load balancer

You can use your Manifest file to customize the AWS load balancer deployed by Cloud 66.

The following settings are available via the Manifest file:

Example YAML for AWS load balancers

load_balancer:
  configuration:
    httpchk: /
    wait_after_adding_servers: 30 # default is 0
    wait_after_removing_servers: 10 # default is 0         
    alb_ssl_policy: ELBSecurityPolicy-FS-1-2-2019-08 # default
    elb_ssl_policy: ELBSecurityPolicy-TLS-1-2-2017-01 # default  

DigitalOcean Load Balancer

You can use a manifest file to configure Hetzner Cloud Load Balancers deployed by Cloud 66.

The following settings are available via the Manifest file:

Refer to the DigitalOcean documentation for more detail on these settings.

GCE (Google) load balancer

You can use your Manifest file to customize any GCE load balancers deployed by Cloud 66.

The following settings are available via the Manifest file:

Refer to the GCE documentation for more detail on these settings.

Example YAML for GCE load balancers

load_balancer:
  configuration:
    httpchk: /
    balance: CLIENT_IP_PROTO
    wait_after_adding_servers: 30 # default is 0
    wait_after_removing_servers: 10 # default is 0

HAProxy

You can use your Manifest file to configure and define any HAProxy load balancers deployed by Cloud 66. These changes will be either be applied when you redeploy an application with more than one server, rebuild HAProxy or edit HAProxy CustomConfig.

Because HAProxy load balancers are not "cloud native", you will need to specify the server configuration in the same YAML node as your HAproxy settings. The server configuration settings are :

The following HAproxy settings are available via the Manifest file:

Refer to the HAProxy documentation for more information

Example YAML for HAproxy load balancers

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_500: /etc/haproxy/errors/500.http
    errorfile_504: /etc/haproxy/errors/504.https
    wait_after_adding_servers: 30 # default is 0
    wait_after_removing_servers: 10 # default is 0

Hetzner Cloud Load Balancer

You can use a manifest file to configure Hetzner Cloud Load Balancers deployed by Cloud 66.

The following settings are available via the Manifest file:

Refer to the Hetzner documentation for more detail on these settings.

Linode Nodebalancer

You can use a manifest file to configure Linode Nodebalancers deployed by Cloud 66.

The following settings are available via the Manifest file:

Refer to the Linode documentation for more detail on these settings.

Example YAML for Linode Nodebalancer

load_balancer:
  configuration:
    httpchk: /
    balance: leastconn
    wait_after_adding_servers: 30 # default is 0
    wait_after_removing_servers: 10 # default is 0

Understanding manifest files

Classes of manifest file settings

Although manifest files are a powerful tool for defining the composition of an application, it is vital to understand their limits and exceptions.

There are three broad classes of settings in manifest files:

1. Settings that only apply when an application is deployed for the first time (e.g. how much RAM your server should have)
2. Settings that only apply after a specific action is taken (e.g. using Toolbelt to force Nginx to refresh its configuration)
3. Settings that apply each time an application is redeployed

Class 1: Once-off settings

These are almost exclusively confined to the server settings. For instance, changing the cloud vendor in your manifest will not automatically migrate your server to that provider.

Class 1 settings include:

• Disk size
• Disk type
• Vendor
• Region
• Size

Class 2: Sticky settings

These are settings that require a specific action to trigger their roll-out.

For example, in order to implement changes to cross-origin scripting (CORS) settings in Nginx, you need to use the reconfigure.nginx command in Cloud 66 Toolbelt to force the settings to propagate.

Class 3: Flexible settings

These are settings which will be applied as soon as the application is re-deployed following a change to its manifest file. This includes all the settings that don't fall into classes 1 or 2 above.

Manifest file structure

Manifest files have a strict hierarchical structure that determines which part of an application is being addressed by the configuration variables. It's vital to ensure that each line of your configuration falls into the correct place in this hierarchy.

First level: Environment

The optional first level of manifest.yml is the application environment. This allows you to use the same manifest.yml for multiple applications with different environments. Some examples are:

• production
• staging
• development

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

Second level: Component type

Component type defines which component of the application is being configured by that section of manifest.yml.

Available options are:

• rails
• docker
• elasticsearch
• gateway
• glusterfs
• load_balancer
• memcached
• mongodb
• mysql
• nginx
• postgis
• postgresql
• redis
• sinatra

Third Level (1): Configurations

The third level of the manifest file determines the specific settings for the component specified in level 2.

For example, this is how to set the version of Ruby used in a Rails application:

production:
  rails:
    configuration:
      ruby_version: 2.5.1

Third Level (2): Servers

You can also specify settings for your servers in your manifest.yml by using the servers section.

In our example below you can see that we're using DigitalOcean as our vendor and that we've opted for a 2GB instance in the London region.

key_name is optional and is used to select the named vendor cloud key in the case where there are multiple accounts available for the same cloud provider.

Example of complex manifest file

rails:
  configuration:
    ruby_version: 2.5.1
    nameservers: ['8.8.8.8', '8.8.4.4']
  servers:
  - server:
      same_as: master
redis:
  configuration:
    version: 4.0.9
  servers:
  - server:
      unique_name: master
      size: s-2vcpu-2gb
      region: lon1
      vendor: digitalocean
      key_name: My_Key