Custom service configurations

Overview

Service configuration allows you to be more explicit about your Maestro services and control settings that are not usually available through the user interface or Cloud 66 Toolbelt.

These settings describe the composition of your services. Here are some common examples of service configurations you can define:

For a full list of available options, see the table at the end of this document.

Specifying service configurations

While you’re building your application, custom service configurations can be accessed by clicking on the Advanced tab. This gives you direct access to editing the service.yml for your application.

Once your application has been built, you can access service.yml under Configuration Files in the right menu of your application page.

Service configuration examples

We have taken these examples from our public Samples repository that you can access here. They are not intended for use as anything except examples.

Single service with MySQL database

In this example, we’ll be configuring a service called web, which is pulled from a Git repository and requires a MySQL database.

services:
  web:
    log_folder: "/usr/src/app/log"
    ports:
    - container: 3000
      http: 80
      https: 443
    git_url: https://github.com/cloud66-samples/pilot
    git_branch: master
    dockerfile_path: Dockerfile
databases:
- mysql                            

As you can see above, the web service is pulled from a sample project on Github called Pilot. It specifies both a path for the Dockerfile and a logging folder. Finally, the container is set to listen on port 3000 and uses external ports 80 and 443.

Multiple services and databases

In this example, we’ll be running three services - one called seller, one called buyer and one called dashboard as well as a Redis database.

You can define as many services as you need. The first time you build your application, those services will be started on the first server you build but you can use the UI, Toolbelt or the API to move them around.

services:
  seller:
    git_url: https://github.com/cloud66-samples/acme.git
    git_branch: master
    dockerfile_path: "./Dockerfile"
    build_root: seller
    command: seller --redis redis:6379
  buyer:
    git_url: https://github.com/cloud66-samples/acme.git
    git_branch: master
    dockerfile_path: "./Dockerfile"
    build_root: buyer
    command: buyer --redis redis:6379
  dashboard:
    git_url: https://github.com/cloud66-samples/acme.git
    git_branch: master
    ports:
    - container: 5000
      http: 80
    dockerfile_path: "./Dockerfile"
    build_root: dashboard
    command: "/go/src/dashboard/dashboard --redis redis:6379"
  redis:
    image: redis
    ports:
    - 6379                            

Database configurations

You can specify any required databases in the service configuration. As databases are fairly static components that rarely change without a migration, they aren’t run in containers. This avoids the complexity and overhead of running databases in a container and allows Cloud 66 to perform replication and backups as normal. These databases will be deployed and configured automatically, and their addresses and access credentials will be made available to the containers across the application with environment variables.

The allowed database values are: postgresql, mysql, redis, mongodb, elasticsearch , rabbitmq and glusterfs. For example:

services:
    <service_name>:
databases:
    - mysql
    - elasticsearch

Environment variables

Any environment variable defined in your application will be made available within your service container. You can also define a new environment variable for a service or reference an environment variable in other applications or services using the following syntax:

services:
    <service_name>:
        env_vars:
            # Setting an environment variable
            ENV_NAME1: VALUE

            # Referencing an application-wide variable
            ENV_NAME2: _env(STACK_ENV_VAR_NAME)

            # Referencing an application-wide variable (with default fall-back)
            ENV_NAME3: _env(APP_ENV_VAR_NAME:Default)

            # Referencing a service's variable
            ENV_NAME4: _env(SERVICE[SERVICE_NAME].ENV_VAR_NAME)

            # Referencing a service's variable (with default fall-back)
            ENV_NAME5: _env(SERVICE[SERVICE_NAME].ENV_VAR_NAME:Default)

            # Referencing another application's variable
            ENV_NAME6: _env(STACK[APP_UID].ENV_VAR_NAME)

            # Referencing another application's variable (with default fall-back)
            ENV_NAME7: _env(STACK[APP_UID].ENV_VAR_NAME:Default)

            # Referencing another application's service variable
            ENV_NAME8: _env(STACK[APP_UID].SERVICE[SERVICE_NAME].ENV_VAR_NAME)

            # Referencing another application's service variable (with default fall-back)
            ENV_NAME9: _env(STACK[APP_UID].SERVICE[SERVICE_NAME].ENV_VAR_NAME:Default)

In above example, all defined environment variables except ENV_NAME1 are referenced to other environment variables. You can specify a default value for referenced environment variables that will be set if there is no suitable link value (such as ENV_NAME3).

In addition to this, you can pass environment variables into your Dockerfile during your build process with the $VARIABLE syntax, which will be populated with environment variable(s) set on the application.

Service configuration options

Below is a table of the available configurations for a given service with a brief description. For more detailed information about an option, click the link provided.

Option Description
build_command Specifies the command you would like to run during application build.
build_root Specifies the directory of your repository in which you wish to run your Docker build.
command Specifies the command used to start your container.
constraints Specifies container amount or resource constraints for a service across the cluster.
deploy_command Specifies the command you would like to run during application deploy (runs once per service).
dns_behaviour Specifies the dns behaviour for this service. Accepted values: versioned, non-versioned. Defaults to versioned.
dockerfile_path Specifies the location of the Dockerfile to be used for building this service, eg. docker/Dockerfile.
tags Arbitrary tags for services
git_url The URL for the Git repository from which your Docker image will be built.
git_branch The Git repository branch your Docker image will be based on.
use_habitus Use Habitus build workflow
use_habitus_step The Habitus step to use for the build.
health One of the values: default, none or a hash.
image The image you would typically run docker pull from.
load_balancing Specifies the load balancing method for this service. Accepted values: roundrobin, sticky, closest. Default value is roundrobin
log_folder Folder your services logs to, mounted to /var/log/containers/service on the host filesystem.
ports The ports that are running within the container, as well as their corresponding external ports.
privileged (default: false) Boolean value to indicate whether the container should be run with extended privileges.
pre_start_signal This is a signal that is sent to the existing running containers of the service before the new service containers are started during deployment.
pre_stop_sequence This is a stop sequence that is executed on your running containers before they are shut down.
requires Array of other defined service names that should be started before this service during build and deployment.
restart_on_deploy (default: true) Boolean value to indicate whether the containers of this service should be restarted during deployment.
stop_grace Duration between the Docker TERM and KILL signals when Docker stop is run and a container is stopped.
traffic_matches The automatically configured traffic names in your Nginx config that will route traffic to these containers based on request DNS name. Allows microservices on the same port routes by subdomain for instance.
volumes The volumes that are mounted from your host into your container. Note: must use absolute paths.
work_dir Specifies the working directory in your image for any command to be run.
pre_stop_command This hook is called immediately before a container is terminated.
post_start_command This hook executes immediately after a container is created.