Services

Services are the primary workload type in greyhound. A service defines a long-running container — typically an API server, web frontend, or background worker — that greyhound deploys as a Kubernetes Deployment.

Services vs. Jobs

Services and jobs share most configuration fields but serve different purposes:

	Services	Jobs
Lifecycle	Long-running, always on	Runs to completion, then stops
Use case	API servers, workers, frontends	Migrations, seed scripts, one-off tasks
Restart	Automatically restarted	Configurable restart policy

Use a job for tasks like database migrations that should run once before your services start.

Defining a Service

Every service needs at least a name and an image source. Use image for off-the-shelf images like nginx:

services:
  - name: nginx
    image: nginx:1.27-alpine
    ports:
      - containerPort: 80

To use your own image built from your repository's source code, use image_from_build to reference a build in your greyhound config:

services:
  - name: api
    image_from_build: api-build
    ports:
      - containerPort: 3000

image and image_from_build are mutually exclusive — use one or the other per service.

Environment Variables

Pass configuration to your service via env:

services:
  - name: api
    image_from_build: api-build
    env:
      - name: NODE_ENV
        value: production
      - name: DB_HOST
        value: ${database.my-pool.writer_endpoint}

You can also pull in all keys from a ConfigMap with envFrom:

services:
  - name: api
    image_from_build: api-build
    envFrom:
      - configMapRef:
          name: app-config

See Interpolation Variables for the full list of dynamic values available in env.

Ports

Expose container ports so other services and ingress rules can reach your workload:

services:
  - name: api
    image_from_build: api-build
    ports:
      - containerPort: 3000
      - containerPort: 9090

To route external traffic to a service, pair it with a rule.

Replicas

Control how many pod replicas run for a service:

services:
  - name: api
    image_from_build: api-build
    replicas: 3

Set replicas: 0 for scaled-to-zero services that should be deployed but not running.

Resource Limits

Set CPU and memory for a service. These override any global resources block:

services:
  - name: api
    image_from_build: api-build
    resources:
      limits:
        cpu: '1'
        memory: 2Gi
      requests:
        cpu: '0.5'
        memory: 1Gi

note

requests is optional in greyhound if limits is provided; greyhound will use the same values provided for limits when requests is not provided.

Custom Commands

Override the container entrypoint with command and/or args:

services:
  - name: worker
    image_from_build: api-build
    command:
      - node
      - worker.js
    args:
      - --queue=high-priority

Volumes

Mount shared volumes or ConfigMaps into your service:

services:
  - name: api
    image_from_build: api-build
    volumes:
      - name: data
        mount_path: /app/data
        claim: data-volume

See Shared Volumes for how to define the volume sources.

Service Accounts

Attach a service account to give your pods IAM permissions:

services:
  - name: api
    image_from_build: api-build
    service_account_name: my-runtime

See Infrastructure for setting up IAM roles and service accounts.

Schema Reference

See the Service schema for the full configuration reference.