Customizing service life-cycle management

Orchestration engine

Maestro provides an orchestration engine to roll out Docker images to your servers and initialize containers from them. This includes:

Note

In the case of Maestro Version 2 this engine is Kubernetes. In the case of Version 1 it is Cloud 66's own engine.

Deploying your application

The above can be summarized as the life-cycle management of your containers, which occurs with each new deployment of your application. This is what happens when you redeploy your application:

  1. Your latest code is pulled from Git and new images are built
  2. These images are rolled out to your server(s)
  3. Containers are initialized from these images, with all relevant environment variables and internal networking made available to them.
  4. If and when your health checks are successful, your old containers are gracefully drained and traffic is switched to the new containers (on the specified port(s)).

Configuration

Below are all the directives you can set in your service configuration (service.yml) to customize your container life-cycle management.

(Read our guide to using service.yml for more help on customizing your service configuration.)

Health

The health option allows you to specify different types of checks on your containers - readiness checks, liveness checks, and startup checks. These checks define a set of rules that determine whether your application is currently healthy. For instance, you can check whether an application is responding on an HTTP endpoint, or if a post-initialization file is present.

Readiness checks test whether newly started containers are ready to replace old containers. Until the new containers are ready, the old containers will not be killed, and the new containers will not be served traffic. This effectively provides zero down-time deployments.

Liveness checks continuously monitor your application while it is running. If your application fails a liveness check, it will be restarted. This is useful for issues that cannot be resolved otherwise.

Startup checks detect when a container has started. An active startup check will disable liveness and readiness checks until it succeeds. This prevents other checks from interrupting application startup. This is particularly useful for slow starting containers, because otherwise liveness checks might cause them to be killed before they are up and running. Requires Kubernetes v1.16 or greater.

Please see the official Kubernetes documentation regarding these checks.

The options below are available for all health checks. Note that you aren't required to configure all the options. Any options not configured will use their default values.

  • type (string, defaults to 'http'): Accepted values are http, https, tcp, and exec.
  • endpoint (string, defaults to '/'): The endpoint tested for status. Only for the http, and the https types.
  • command (string, no default): The command executed to test for status. Must return exit-code 0. Only for the exec type.
  • timeout (integer, defaults to 5): Maximum time in seconds to wait for a health check to complete.
  • success_threshold (integer, defaults to 1): Number of consecutive successes to be considered healthy.
  • failure_threshold (integer, defaults to 1): Number of consecutive failures to be considered unhealthy.
  • initial_delay (integer, defaults to 1): Time in seconds to wait after container has started before starting liveness checks.
  • period (integer, defaults to 5): Number of seconds between each consecutive health check.
  • port (integer, defaults to container port): The port to run the health check against. Only for the http, https, and tcp types.
  • http_headers (array, defaults to []): Custom headers to add for HTTP traffic. Only for the http, and https types. Contains an array of hashes with the name and value keys, both of string type.

services:
    [service_name]:
        health:
            ready:
                type: exec
                command: 'cat /tmp/initialization_complete'
            alive:
                type: http
                endpoint: /healthz
                success_threshold: 2
                failure_threshold: 2
                initial_delay: 10
                period: 30
                http_headers:
                - name: 'X-ID-Header'
                  value: 'john-smith'
            startup:
                type: exec
                command: 'cat /tmp/app_started'                  

You can also use the default health rules with health: default, or explicitly disable health checking by leaving the health option out or specifying health: none.


Pre-start command

This is a command that executes immediately after a container is created.

Pre-stop command

This is a command that executes immediately before a container is terminated.

Pre-start signal

This command is not supported by Maestro Version 2.


Pre-stop sequence

This command is not supported by Maestro Version 2.


Requires

In some cases, you may want to make sure that a service is only started if another, related service is also started. The requires option allows you to set such dependencies. For example:

services:
    [service_name]:
        image: cloud66/sample
        requires:
          - "my_api"

Restart on deploy

A boolean value to indicate whether the containers of this service should be restarted during deployment (set to true by default). For example:

services:
    [service_name]:
        restart_on_deploy: false

Stop grace

Sets the duration between the Docker TERM and KILL signals when Docker stop is run and a container is stopped. For example:

services:
    [service_name]:
        stop_grace: 30