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:
  grpc:
    build: .
    port: grpc:5551
    grpcHealthEnabled: true

services:
  web:
    agent: false
    annotations:
      - test.annotation.org/value=foobar
    build:
      manifest: Dockerfile
      path: .
    certificate:
      duration: 2160h 
    command: bin/web
    deployment:
      minimum: 25
      maximum: 100
    domain: ${WEB_HOST}
    drain: 10
    dnsConfig:
      ndots: 5
    environment:
      - FOO
      - BAR=qux
    health:
      grace: 10
      interval: 5
      path: /check
      timeout: 3
    liveness:
      path: /liveness/check
      grace: 15
      interval: 5
      timeout: 3
      successThreshold: 1
      failureThreshold: 3
    internal: false
    ingressAnnotations:
      - nginx.ingress.kubernetes.io/limit-rpm=10
    labels:
      convox.com/test: true
    lifecycle:
      preStop: "sleep 10"
      postStart: "sleep 10"
    port: 5000
    ports:
      - 5001
      - 5002
    privileged: false
    scale:
      count: 1-3
      limit:
        cpu: 256
        memory: 1024
      cpu: 128
      memory: 512
      targets:
        cpu: 50
        memory: 80
        external:
          - name: "datadogmetric@default:web-requests"
            averageValue: 200
    singleton: false
    sticky: true
    termination:
      grace: 45
    test: make test
    timeout: 180
    tls:
      redirect: true
    whitelist: 10.0.0.128/16,192.168.0.1/32

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

*annotations

You can use annotations to attach arbitrary non-identifying metadata to objects. Clients such as tools and libraries can retrieve this metadata. On Convox, annotations will reflect in pods and service accounts.

Here are some examples of information that can be recorded in annotations:

• Build, release, or image information like timestamps, release IDs, git branch, PR numbers, image hashes, and registry address.
• Fields managed by a declarative configuration layer. Attaching these fields as annotations distinguishes them from default values set by clients or servers, and from auto-generated fields and fields set by auto-sizing or auto-scaling systems.
• User or tool/system provenance information, such as URLs of related objects from other ecosystem components.
• Configure a service to assume an IAM Role(AWS and GCP only). For example:

environment:
  - PORT=3000
services:
  web:
    annotations:
      - eks.amazonaws.com/role-arn=arn:aws:iam::accountID:role/yourOwnIAMRole
    domain: ${HOST}
    build: .
    port: 3000

accessControl

services:
  web:
    ...
    accessControl:
      awsPodIdentity:
        policyArns:
         - "arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly"
         - "arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess"
  ...

accessControl.awsPodIdentity

Pod identity must be enabled on rack before specifying this.

build

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

certificate

deployment

dnsConfig

ingressAnnotations

This accepts list of strings where in each string annotation key and value is separated by = sign:

services:
  web:
    ...
    ingressAnnotations:
      - nginx.ingress.kubernetes.io/limit-rpm=10
      - nginx.ingress.kubernetes.io/enable-access-log=false
  ...

Reserved annotation keys:

• alb.ingress.kubernetes.io/scheme
• cert-manager.io/cluster-issuer
• cert-manager.io/duration
• nginx.ingress.kubernetes.io/backend-protocol
• nginx.ingress.kubernetes.io/proxy-connect-timeout
• nginx.ingress.kubernetes.io/proxy-read-timeout
• nginx.ingress.kubernetes.io/proxy-send-timeout
• nginx.ingress.kubernetes.io/server-snippet
• nginx.ingress.kubernetes.io/affinity
• nginx.ingress.kubernetes.io/session-cookie-name
• nginx.ingress.kubernetes.io/ssl-redirect
• nginx.ingress.kubernetes.io/whitelist-source-range

initContainer

It takes inputs just like a container and runs before main container. It supports all these arguments-

• Setting a command is necessary for creation of initContainer.

lifecycle

health

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

liveness

If you want to enable liveness check, you have to specify path and others are optional

scale

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

scale.gpu

Specifying gpu as a number will set the count and leave the vendor as default. Specifying a gpu value and not specifying the cpu or memory to reserve will remove their defaults to purely reserve based on GPU. You should ensure that your Rack is running on GPU enabled instances (of the correct vendor) before specifying the gpu section in your convox.yml

scale.targets

scale.limit

scale.targets.[]external

services:
  web:
    build: .
    port: 3000
    scale:
      count: 1-3
      targets:
        external:
          - name: "datadogmetric@default:web-requests"
            averageValue: 200

termination

tls

[]volumeOptions

[]volumeOptions.emptyDir

environment:
  - PORT=3000
services:
  web:
    build: .
    port: 3000
    volumeOptions:
      - emptyDir:
          id: "test-vol"
          mountPath: "/my/test/vol"

[]volumeOptions.awsEfs

environment:
  - PORT=3000
services:
  web:
    build: .
    port: 3000
    volumeOptions:
      - awsEfs:
          id: "efs-1"
          accessMode: ReadWriteMany
          mountPath: "/my/data/"

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.