Custom service configurations


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 are defined in the service.yml file.

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.

Accessing service.yml

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

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.

  log_folder: "/usr/src/app/log"
   - container: 3000
      http: 80
      https: 443
   git_branch: master
   dockerfile_path: Dockerfile
- 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.

  git_branch: master
  dockerfile_path: "./Dockerfile"
  build_root: seller
  command: seller --redis redis:6379
  git_branch: master
  dockerfile_path: "./Dockerfile"
  build_root: buyer
  command: buyer --redis redis:6379
  git_branch: master
  - container: 5000
     http: 80
  dockerfile_path: "./Dockerfile"
  build_root: dashboard
  command: "/go/src/dashboard/dashboard --redis redis:6379"
  image: redis
  - 6379

Using Habitus for builds

Habitus is a build workflow tool for Docker-based applications. It allows you to create a build workflow consisting of multiple steps for your Maestro application. Maestro fully supports Habitus. To enable Habitus on your Maestro application, you need to do the following:

  1. Add a build.yml to your repository
  2. Set use_habitus attribute to true in your service.yml
  3. Set the use_habitus_step to the step you would like to use for your service in your service.yml

You can edit your service.yml directly from the Dashboard by clicking Edit service and then clicking the Advanced tab.

A Habitus build usually has multiple steps and each step can generate a Docker image. Using use_habitus_step attribute you can specify which step’s results you would like to use as the image for the container.

Check out the Habitus website for more information about generating a build.yml.

Adding a DaemonSet

A DaemonSet ensures that a (single) copy of a specific Pod is added to every Node. This is useful for running background processes (aka daemons) but has many other uses. For more detail pleased read our explanatory doc on the subject.

To create a DaemonSet we simply set the type of any service to daemon_set. For example:

  image: training/webapp
  type: daemon_set
  - container: 5000
     http: 80

This will use the image called “webapp” to spawn a single Pod called “web” on every Node in your Cluster.

Database configurations

The first time you deploy an application, you can specify any required databases in the service configuration. 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.

Once your application has been deployed, you can still add databases, but you need to do so using our database Add-Ins feature.

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.

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

  - mysql
  - elasticsearch

Environment variables

Any environment variable defined in your application will be made available within your service container.

The syntax for defining environment variables in a service definition is:


You can also reference environment variable in other applications or services. For more info please read our detailed guide to the sharing env vars between apps and services.

Setting a Service Account name

Kubernetes relies on its “Service Accounts” feature to manage the identity of processes running inside Pods.

By default all services belong to a service account named default. Normally this provides sufficient access for your application. However, should you require elevated access (e.g. to allow for log collection or metrics gathering), you can set a custom Service Account for any service using the service_account_name. For example:

  - container: 3000
    http: 80
 service_account_name: public-front-end

This will make the service named “web” run under the “public-front-end” Service Account in Kubernetes.

Bear in mind that this service account will first need to be created on your cluster (with associated access bindings) before it will function correctly. Please read the Kubernetes guide to configuring Service Accounts for more detail.

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
annotations Annotations for your services in key/value format - these will also become annotations on your Kubernetes resources
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 Limits the number of containers or the resource usage of a service across the cluster, or allocates services to nodes based on names and/or tags.
constraints/tolerations This is an optional hash for advanced configuration of Kubernetes Tolerations.
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.
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. Use this to configure Readiness, Liveness, and Startup probes
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.
service_account_name Assigns the service to a specific Kubernetes Service Account. The default value is default
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.
security_context This is an optional hash for advanced configuration of Kubernetes Security Context. Valid keys are: fs_group, host_ipc, host_network, host_pid, privileged, run_as_group, run_as_non_root, run_as_user, supplemental_groups.
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.
tags Arbitrary text tags for your services - these will also become labels on your Kubernetes resources
type Specifies the type of service being defined. Accepted values: service, deployment, daemon_set
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.

More help