Manifest

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
  • Installing extra packages
  • Specifying the version of a component
  • Configuring application components to share a server
  • Customizing component-specific configurations

Take care when editing

Be cautious when editing the manifest file for any application particularly if it is running in a production environment. A single stray character or space can cause the application to fail to deploy or to deploy in a degraded state.

Is your yaml valid?

The manifest file is YAML formatted. You can check its validity at YAML Validator or with this command: $ ruby -e "require 'yaml'; YAML.load_file('.cloud66/manifest.yml')"

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:

Existing applications

Editing the manifest file of an existing application may not necessarily result in changes to the deployed instance(s) of that application, even if the application is subsequently redeployed. See the Understanding Manifest Files section below.

Problems upgrading?

If you explicitly set the version of any component in your manifest file, we will respect that setting even if it conflicts with other system changes or upgrades (for example upgrading Ubuntu). If you are having trouble upgrading any component of your application, remember to check your manifest file to ensure you have not previously locked the version of that component or one of its dependents.

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

Locking versions

If you explicitly set the version of any component in your manifest file, we will respect that setting even if it conflicts with other system changes or upgrades (for example upgrading Ubuntu). If you are having trouble upgrading any component of your application, remember to check your manifest file to ensure you have not previously locked the version of that component or one of its dependents.

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:

OptionApplied onDescriptionClouds
availability_zoneAvailability zone of the server instance in AWS EC2 region.AWS
key_nameThe name of the API key for the cloud account where the server will be built. You can see (and edit) all your cloud API key names in your Dashboard Settings. This is used when an account has multiple keys for a given cloud vendor. The default value is Default.All
regionThe data center region where the server will be built.All
root_disk_sizeDefault size of root disk (in GB) for servers used by application. Default value is 50.AWS, Azure, GCE
root_disk_typeDisk type, accepted values being ssd and magnetic. Default is ssd.AWS, GCE
sizeThe size of the server instance to be created.All
subnet_idID or name of the AWS subnet in which you would like to create your servers. If not supplied, we will attempt to identify the single map_public_ip_on_launch set to trueAWS
unique_nameA unique name for this server (Required if you are specifying a server type)All
vendorCloud vendor where the server will be built. Valid values: aws, azure_rm (use azure for older Azure accounts), digitalocean, googlecloud, hetzner, linode, maxihost, ovh, and vultrAll

An app must use a single cloud region

All of the servers for an application must belong to a single cloud vendor and region. Different applications may use different clouds, but a single application cannot use multiple clouds.

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

  • 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.

OptionApplied onDescriptionClouds
addressIP address of the server, only applicable to Registered ServersRegistered servers
unique_nameUnique name for the registered serverRegistered servers

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.

OptionApplied onDescriptionClouds
same_asThe name of another server definition in the same manifest file. This component will use the same server when it is deployed.All

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

Gateway must be defined first

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

The following settings are available via the Manifest file:

OptionApplied onDescriptionClouds
nameSpecify the name of gateway you want to use for your application.All
usernameSpecify the username which should be used to connect to Bastion server.All

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:

OptionApplied onDescriptionClouds
corsEnable Cross Origin Resource SharingAll
nginx/precompiled_urlA URL pointing to a file in tar.gz format that contains a custom version of Nginx that will be used with your application. This Nginx package MUST be compiled using our Cloud 66 compiler. Please read the docs on the Github page for more details.All
extra_build_arguments (deprecated)Extra build argument string that will be added to the nginx build command. If you require additional modules that themselves require specific source to be present, you should use a BEFORE_NGINX deploy hook to ensure that source is present. You can use the cloud66/download snippet to achieve this easily. The following build arguments are currently always added: --with-http_realip_module --with-ipv6 --with-http_v2_module regardless of this value.All
perfect_forward_secrecy (deprecated)Enable Perfect Forward SecrecyAll

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.

Positioning Health Check settings

Note that all of the Health Check settings must be nested under the configurationactiveprotecthealth_check sub-node.

The following settings are available via the Manifest file:

OptionApplied onDescriptionClouds
endpointThe endpoint to that will be queried during the checkAll
acceptThe set of HTTP codes we will accept as valid from the endpoint (as an array)All
timeoutThe timeout limit in seconds of the endpoint (limit: 10)All
max_redirectsThe number of acceptable HTTP redirects (limit: 10)All
cooldownThe delay between the end of the deployment process and the start of the test, in seconds. (limit: 1800)All

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:

OptionApplied onDescriptionClouds
groupsUsed to define multiple separate database groups (of the same type), each with their own configuration. The name of each group in your Manifest must match the names in your Dashboard.All
iam_instance_profile_nameThe name of the IAM instance profile that should be used when provisioning this server.AWS
instance_service_account_nameThe name of the GCE Service Account that should be used when provisioning this server.GCE
operating_systemThe version of Ubuntu to install on the server that hosts ElasticSearch. Accepted values ubuntu1804, ubuntu2004, ubuntu2204All
root_disk_sizeDefault size of root disk (in GB) for servers used by ElasticSearch. Default value is 50.AWS, Azure, GCE
root_disk_typeDisk type for servers used by ElasticSearch, accepted values being ssd and magnetic. Default value is ssd.AWS, GCE
tagsAppend the listed tags to any servers created for this component. See our tagging guide for more info on tag syntax and support.AWS, Azure, DigitalOcean, Hetzner
versionThe version of ElasticSearch you want to install. NOTE: You can use database groups to run different versions of the same database in parallel with each other.All

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:

OptionApplied onDescriptionClouds
iam_instance_profile_nameThe name of the IAM instance profile that should be used when provisioning this server.AWS
instance_service_account_nameThe name of the GCE Service Account that should be used when provisioning this server.GCE
mount_targetsList of servers and server groups on which GlusterFS should be mounted. You can specify the name of the server or server group (e.g. rails or mysql). You can also use app and db keywords: app is your main app server group (e.g. rails) and db is your database server groups (e.g. mysql or redis). The default value is app.All
replica_countThe number of nodes in the GlusterFS cluster to which data will be replicated (e.g. 2 means your data exist on two nodes). Default value is 1.All
root_disk_sizeDefault size of root disk (in GB) for servers used by GlusterFS. Default value is 50.AWS, Azure, GCE
root_disk_typeDisk type for servers used by GlusterFS, accepted values being ssd and magnetic. Default value is ssd.AWS, GCE
tagsAppend the listed tags to any servers created for this component. See our tagging guide for more info on tag syntax and support.AWS, Azure, DigitalOcean, Hetzner
versionThe version of GlusterFS you wish to install.NOTE: You can use database groups to run different versions of the same database in parallel with each other.All

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 :

OptionApplied onDescriptionClouds
listen_ipSpecify which IP address to listen on (default value is 0.0.0.0)All
memorySpecify maximum memory (in MB) that can be used (default is 64)All
portSpecify connection port (default is 11211)All

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 :

OptionApplied onDescriptionClouds
groupsUsed to define multiple separate database groups (of the same type), each with their own configuration. The name of each group in your Manifest must match the names in your Dashboard.All
iam_instance_profile_nameThe name of the IAM instance profile that should be used when provisioning this server.AWS
instance_service_account_nameThe name of the GCE Service Account that should be used when provisioning this server.GCE
operating_systemThe version of Ubuntu to install on the server that hosts MongoDB. Accepted values ubuntu1804, ubuntu2004,ubuntu2204All
root_disk_sizeDefault size of root disk (in GB) for servers used by MongoDB. Default value is 50.AWS, Azure, GCE
root_disk_typeDisk type for servers used by MongoDB, accepted values being ssd and magnetic. Default value is ssd.AWS, GCE
tagsAppend the listed tags to any servers created for this component. See our tagging guide for more info on tag syntax and support.AWS, Azure, DigitalOcean, Hetzner
tamper_with_ymlDetermines whether Cloud 66 can automatically update your database configuration (username, password and server address). Default is yes.All
versionSpecify the version of MongoDB you want to install. NOTE: You can use database groups to run different versions of the same database in parallel with each other.All

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 :

OptionApplied onDescriptionClouds
encodingSpecify the encoding (AKA charset) for the database. Valid values can be found in the MySQL charset docs.All
engineSpecify the MySQL engine you want to install. Valid values are mysql and perconaAll
groupsUsed to define multiple separate database groups (of the same type), each with their own configuration. The name of each group in your Manifest must match the names in your Dashboard.All
iam_instance_profile_nameThe name of the IAM instance profile that should be used when provisioning this server.AWS
instance_service_account_nameThe name of the GCE Service Account that should be used when provisioning this server.GCE
operating_systemThe version of Ubuntu to install on the server that hosts MySQL. Accepted values ubuntu1804, ubuntu2004,ubuntu2204All
root_disk_sizeDefault size of root disk (in GB) for servers used by MySQL. Default value is 50.AWS, Azure, GCE
root_disk_typeDisk type for servers used by MySQL, accepted values being ssd and magnetic. Default value is ssd.AWS, GCE
tagsAppend the listed tags to any servers created for this component. See our tagging guide for more info on tag syntax and support.AWS, Azure, DigitalOcean, Hetzner
tamper_with_ymlDetermines whether Cloud 66 can automatically update your database configuration (username, password and server address). Default is yes.All
versionSpecify the version of MySQL you want to install. Valid values are 5.7 or 8.0 NOTE: You can use database groups to run different versions of the same database in parallel with each other.All

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 :

OptionApplied onDescriptionClouds
encodingSpecify the encoding (AKA charset) for the database. Valid values can be found in the Postgres character set docs.All
groupsUsed to define multiple separate database groups (of the same type), each with their own configuration. The name of each group in your Manifest must match the names in your Dashboard.All
iam_instance_profile_nameThe name of the IAM instance profile that should be used when provisioning this server.AWS
instance_service_account_nameThe name of the GCE Service Account that should be used when provisioning this server.GCE
operating_systemThe version of Ubuntu to install on the server that hosts Postgres. Accepted values ubuntu1804, ubuntu2004, ubuntu2204All
postgisSpecify whether to include PostGISAll
postgis / versionSpecify the version of PostGIS you want to install. Must be nested in postgres settingsAll
root_disk_sizeDefault size of root disk (in GB) for servers used by Postgres. Default value is 50.AWS, Azure, GCE
root_disk_typeDisk type for servers used by Postgres, accepted values being ssd and magnetic. Default value is ssd.AWS, GCE
tagsAppend the listed tags to any servers created for this component. See our tagging guide for more info on tag syntax and support.AWS, Azure, DigitalOcean, Hetzner
tamper_with_ymlDetermines whether Cloud 66 can automatically update your database configuration (username, password and server address). Default is yes.All
versionSpecify the version of Postgres you want to install. NOTE: You can use database groups to run different versions of the same database in parallel with each other.All

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 :

OptionApplied onDescriptionClouds
iam_instance_profile_nameThe name of the IAM instance profile that should be used when provisioning this server.AWS
instance_service_account_nameThe name of the GCE Service Account that should be used when provisioning this server.GCE
groupsUsed to define multiple separate database groups (of the same type), each with their own configuration. The name of each group in your Manifest must match the names in your Dashboard.All
operating_systemThe version of Ubuntu to install on the server that hosts Redis. Accepted values ubuntu1804, ubuntu2004,ubuntu2204All
root_disk_sizeDefault size of root disk (in GB) for servers used by Redis. Default value is 50.AWS, Azure, GCE
root_disk_typeDisk type for servers used by Redis, accepted values being ssd and magnetic. Default value is ssd.AWS, GCE
tagsAppend the listed tags to any servers created for this component. See our tagging guide for more info on tag syntax and support.AWS, Azure, DigitalOcean, Hetzner
versionSpecify the version of Redis you want to install. NOTE: You can use database groups to run different versions of the same database in parallel with each other.All

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

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:

OptionApplied onDescription
alb_ssl_policyThe SSL policy to associate with your ALB when performing SSL termination. See the official AWS docs for available ALB SSL policies. (Applies only to Application Load Balancers)
elb_ssl_policyThe SSL policy to associate with your ELB when performing SSL termination. See the official AWS docs for available ELB SSL policies. (Applies only to Classic Load Balancers)
httpchkThe URL visited to check your server health
wait_after_adding_serversThe time (in seconds) we will wait after adding a server back to the load balancer before we begin routing traffic to that server. Read our in-depth guide on configuration lag for more details.
wait_after_removing_serversThe time (in seconds) we will wait after adding a server back to the load balancer before we begin routing traffic to that server. Read our in-depth guide on configuration lag for more details.

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:

OptionApplied onDescription
httpchkThe URL visited to check your server health
wait_after_adding_serversThe time (in seconds) we will wait after adding a server back to the load balancer before we begin routing traffic to that server. Read our in-depth guide on configuration lag for more details.
wait_after_removing_serversThe time (in seconds) we will wait after adding a server back to the load balancer before we begin routing traffic to that server. Read our in-depth guide on configuration lag for more details.

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:

OptionApplied onDescription
balanceThe load balancing strategy. Valid values: NONE, CLIENT_IP or CLIENT_IP_PROTO
httpchkThe URL visited to check your server health
wait_after_adding_serversThe time (in seconds) we will wait after adding a server back to the load balancer before we begin routing traffic to that server. Read our in-depth guide on configuration lag for more details.
wait_after_removing_serversThe time (in seconds) we will wait after adding a server back to the load balancer before we begin routing traffic to that server. Read our in-depth guide on configuration lag for more details.

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 :

Server optionsApplied onDescription
key_nameDefault
regionDigitalOcean's region
sizeThe size of the instance
unique_nameName of the instance

The following HAproxy settings are available via the Manifest file:

OptionApplied onDescription
balanceThe load balancing strategy. Valid values: roundrobin, leastconn or source
errorfile_*ERROR_CODE*Location of your own custom error page(s) to serve in the case of receiving a HTTP error code on the load balancer. You can configure one page per error code.
haproxy_passwordThe password for your HAproxy stats interface.
haproxy_usernameThe username for your HAproxy stats interface.
httpchkThe URL visited to check your server health
wait_after_adding_serversThe time (in seconds) we will wait after adding a server back to the load balancer before we begin routing traffic to that server. Read our in-depth guide on configuration lag for more details.
wait_after_removing_serversThe time (in seconds) we will wait after adding a server back to the load balancer before we begin routing traffic to that server. Read our in-depth guide on configuration lag for more details.

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:

OptionApplied onDescription
balanceThe load balancing strategy. Valid values: round_robin or least_connections
httpchkThe URL visited to check your server health
wait_after_adding_serversThe time (in seconds) we will wait after adding a server back to the load balancer before we begin routing traffic to that server. Read our in-depth guide on configuration lag for more details.
wait_after_removing_serversThe time (in seconds) we will wait after adding a server back to the load balancer before we begin routing traffic to that server. Read our in-depth guide on configuration lag for more details.

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:

OptionApplied onDescription
balanceThe load balancing strategy. Valid values: roundrobin, leastconn or source
httpchkThe URL visited to check your server health
wait_after_adding_serversThe time (in seconds) we will wait after adding a server back to the load balancer before we begin routing traffic to that server. Read our in-depth guide on configuration lag for more details.
wait_after_removing_serversThe time (in seconds) we will wait after adding a server back to the load balancer before we begin routing traffic to that server. Read our in-depth guide on configuration lag for more details.

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
Previous
Cloud 66 Toolbelt commands