Service

A Service is a horizontally-scalable collection of durable Processes.

Processes that belong to a Service are automatically restarted upon termination.

Services can be scaled to a static count or autoscaled in a range based on metrics.

Definition

services:
  web:
    build: .
    health: /check
    port: 5000
    scale: 3

services:
  web:
    agent: false
    annotations:
      - test.annotation.org/value=foobar
    build:
      manifest: Dockerfile
      path: .
    command: bin/web
    deployment:
      minimum: 25
      maximum: 100
    domain: ${WEB_HOST}
    drain: 10
    environment:
      - FOO
      - BAR=qux
    health:
      grace: 10
      interval: 5
      path: /check
      timeout: 3
    internal: false
    port: 5000
    ports:
      - 5001
      - 5002
    privileged: false
    scale:
      count: 1-3
      cpu: 128
      memory: 512
      targets:
        cpu: 50
        memory: 80
    singleton: false
    sticky: true
    termination:
      grace: 45
    test: make test
    timeout: 180
    tls:
      redirect: true

Attribute	Type	Default	Description
agent	boolean	false	Set to true to declare this Service as an Agent
annotations	list		A list of annotation keys and values to populate the metadata for the deployed pods and their serviceaccounts
build	string/map	.	Build definition (see below)
command	string	CMD of Dockerfile	The command to run to start a Process for this Service
deployment	map		Manual control over deployment parameters
domain	string		A custom domain(s) (comma separated) to route to this Service
drain	number		The number of seconds to wait for connections to drain when terminating a Process of this Service
environment	list		A list of environment variables (with optional defaults) to populate from the Release environment
health	string/map	/	Health check definition (see below)
image	string		An external Docker image to use for this Service (supercedes build)
internal	boolean	false	Set to true to make this Service only accessible inside the Rack
port	string		The port that the default Rack balancer will use to route incoming traffic
ports	list		A list of ports available for internal service discovery or custom Balancers
privileged	boolean	true	Set to false to prevent Processes of this Service from running as root inside their container
scale	map	1	Define scaling parameters (see below)
singleton	boolean	false	Set to true to prevent extra Processes of this Service from being started during deployments
sticky	boolean	false	Set to true to enable sticky sessions
termination	map		Termination related configuration
test	string		A command to run to test this Service when running convox test
timeout	number	60	Timeout period (in seconds) for reading/writing requests to/from your service
tls	map		TLS-related configuration

Environment variables declared on convox.yml will be populated for a Service.

build

Attribute	Type	Default	Description
manifest	string	Dockerfile	The filename of the Dockerfile
path	string	.	The path (relative to convox.yml) to build for this Service

Specifying build as a string will set the path and leave the other values as defaults.

deployment

Attribute	Type	Default	Description
maximum	number	200	The maximum percentage of Processes to allow during rolling deploys
minimum	number	50	The minimum percentage of healthy Processes to keep alive during rolling deploys

health

Attribute	Type	Default	Description
grace	number	5	The number of seconds to wait for a Process to start before starting health checks
interval	number	5	The number of seconds between health checks
path	string	/	The path to request for health checks
timeout	number	4	The number of seconds to wait for a successful response

Specifying health as a string will set the path and leave the other values as defaults.

scale

Attribute	Type	Default	Description
count	number	1	The number of Processes to run for this Service. For autoscaling use a range, e.g. 1-5
cpu	number	128	The number of CPU units to reserve for Processes of this Service where 1024 units is a full CPU
memory	number	256	The number of MB of RAM to reserve for Processes of this Service
targets	map		Target metrics to trigger autoscaling

Specifying scale as a number will set the count and leave the other values as defaults.

scale.targets

Attribute	Type	Default	Description
cpu	number		The percentage of CPU utilization to target for Processes of this Service
memory	number		The percentage of memory utilization to target for Processes of this Service

termination

Attribute	Type	Default	Description
grace	number	30	The number of seconds to wait for Processes to gracefully exit before killing them

tls

Attribute	Type	Default	Description
redirect	boolean	true	Whether or not HTTP requests should be redirected to HTTPS using a 308 response code

Command Line Interface

Listing Services

    $ convox services -a myapp
    SERVICE  DOMAIN                                PORTS
    web      web.convox.0a1b2c3d4e5f.convox.cloud  443:5000

Scaling a Service

    $ convox scale web --count 3 --cpu 256 --memory 1024 -a myapp`1
    Scaling web... OK

Restarting a Service

    $ convox services restart web -a myapp
    Restarting web... OK

Restarting a Service will begin a rolling restart with graceful termination of each Process of the Service.