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:
- Defining build and deploy commands
- Specifying a central logging folder
- Setting port definitions for your containers
- Mounting volumes into your containers
- Setting dependencies between your containers
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 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.
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.
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
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:
- Add a
build.yml
to your repository - Set
use_habitus
attribute totrue
in yourservice.yml
- Set the
use_habitus_step
to the step you would like to use for your service in yourservice.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:
service:
web:
image: training/webapp
type: daemon_set
ports:
- 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:
services:
<service_name>:
databases:
- mysql
- elasticsearch
Environment variables
Any environment variable defined in your application will be made available within your service container.
The syntax for calling environment variables in a service definition is:
services:
service_name:
env_vars:
VAR1: _env(VALUE_OF_VARIABLE)
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:
services:
web:
ports:
- 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. |
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 |
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. |
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. |
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. |
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 containing at least one of type, endpoint, protocol, accept or timeout. |
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 | Volumes mounted from host into container. Syntax: Array of absolute paths, with the format HOST_FOLDER:CONTAINER_FOLDER . Optional 'ro' on the end for read-only. e.g.
|
work_dir | Specifies the working directory in your image for any command to be run. |
More help
- Learn how to call environment variables in a service defintion
- Using environment variables in a Dockerfile