kittengrid.yml reference

Kittengrid reads kittengrid.yml (or kittengrid.yaml) from the repository root. The file declares the services that should be started and exposed for a preview environment.

Complete example

services:
  - name: web
    cmd: npm
    args:
      - run
      - dev
    port: 3000
    host: localhost
    env:
      NODE_ENV: development
    health_check:
      interval: 5
      timeout: 5
      retries: 60
      path: /health

Top-level fields

Field	Type	Description
services	array	The services Kittengrid starts for the preview environment.

services entries

Each item in services describes one process and the HTTP port it exposes.

Field	Type	Required	Description
name	string	Yes	A name for the service. It is also used as the command when cmd is omitted.
port	integer	Yes	The port where the service is reachable. Kittengrid exposes this port in the preview environment.
cmd	string	No	Command used to start the process. Defaults to name.
args	array of strings	No	Arguments passed to cmd. Defaults to no arguments.
env	object of string values	No	Environment variables passed to the process. By default, the process inherits the agent environment. Quote non-string values, such as "3000" or "true".
host	string	No	Host where the service can be reached by the Kittengrid agent. Defaults to localhost. Use this when the process runs in another container or host.
health_check	object	No	HTTP health check settings. Without it, Kittengrid does not monitor the service’s health.

health_check

When health_check is set, provide all of its fields. Kittengrid requests http://<host>:<port>/<path> repeatedly while the service is running.

Field	Type	Description
interval	integer	Seconds between health check requests.
timeout	integer	Maximum time in seconds to wait for a response.
retries	integer	Number of failed health checks before the service is marked unhealthy.
path	string	HTTP path to request, for example /health or /.

Examples

A Node.js application

services:
  - name: web
    cmd: npm
    args: [run, dev]
    port: 3000

A service running in a Docker service container

Set host to the container’s network hostname when the port belongs to a container rather than the agent process.

services:
  - name: prometheus
    cmd: docker
    args: [compose, up, --attach, prometheus]
    port: 19090
    host: docker
    health_check:
      interval: 5
      timeout: 5
      retries: 60
      path: /-/ready