Skip to main content

YAML Schema Reference

This document provides a reference for some of the crucial, reusable YAML definitions used throughout the config.cap.yaml.

Check out the full document at: https://platform.cloudbear.it/schemas/cap.v1.schema.json

Resources

There are two main ways to define resources for your application components: computeResources and resources.

Compute resources

This object is used to define CPU and memory allocation for components like http servers, workers, and cronjobs.

  • cpu: The amount of CPU to allocate. Can be an integer (e.g., 1 for 1 full core) or a string representing millicores (e.g., "500m" for half a core).
  • memory: The amount of memory to allocate. Can be an integer (in bytes) or a string with a unit (e.g., "512Mi", "1Gi").

Example:

http:
  resources:
    cpu: 500m
    memory: 512Mi

Resources

This object is used by stateful services (like databases) that require persistent storage. It includes all the properties of computeResources plus storage.

  • storage: The amount of persistent storage to allocate. Can be an integer (in bytes) or a string with a unit (e.g., "10Gi").

Example:

services:
  db:
    type: mariadb
    resources:
      cpu: 1
      memory: 2Gi
      storage: 20Gi

GitLab environment variables

This object is used within the variables block to reference a secret stored in GitLab's CI/CD project variables.

  • gitlab: The name (key) of the variable in GitLab. Can be a string, or an object with a name property. If null, the name of the environment variable itself is used.

Example:

variables:
  API_KEY:
    gitlab: MY_PRODUCTION_API_KEY
  
  SHARED_SECRET:
    gitlab:
      name: PROJECT_WIDE_SECRET

  SAME_NAME_SECRET:
    gitlab: null                      # looks up SAME_NAME_SECRET in GitLab

Identity tokens

This object is used within the variables block to mount a short-lived identity token for your application. The environment variable holds the path to the token file.

  • token.audience: Required. The service the token is intended for. The receiving service checks that this matches what it expects.
  • token.ttl: How long each issued token is valid for, as seconds or a duration such as 2h. Values below 600 seconds are rejected. Defaults to 3600.

Cannot be combined with value, gitlab, file or build.

The receiving service must verify the signature against the OIDC discovery endpoint for your environment, and check the aud claim. Contact Cloudbear to get that endpoint. See Verifying the token.

Example:

variables:
  BILLING_TOKEN_PATH:
    token:
      audience: billing-api
      ttl: 2h

Cron expressions

This definition is used in the schedule property of cronjobs. It accepts standard cron expressions or a predefined alias.

  • Standard Cron Expression: A five-part string (e.g., "*/5 * * * *" for every 5 minutes).
  • Alias: A string alias for common schedules.
Alias Equivalent Description
@yearly 0 0 1 1 * Run once a year.
@monthly 0 0 1 * * Run once a month.
@weekly 0 0 * * 0 Run once a week.
@daily 0 0 * * * Run once a day (midnight).
@hourly 0 * * * * Run once an hour.

Example:

cronjobs:
  my-task:
    schedule: "*/15 * * * *"
  
  daily-report:
    schedule: "@daily"

Commands

These definitions are used to specify commands for workers and cronjobs.

Command

The command object specifies what to run. It can be one of two properties:

  • command: The full command to run, including the binary (e.g., php, node). Can be a string or an array.
  • subcommand: A command to run with the application type's framework binary (e.g., artisan, bin/console). Can be a string or an array.

Example:

workers:
  full-command-worker:
    command: php /app/my_script.php   # or ["php", "/app/my_script.php"]
  
  subcommand-worker:
    subcommand: queue:work            # php artisan queue:work on Laravel

Task

A task is a combination of a command and computeResources. This is the object used to define a worker or cronjob.

Example:

cronjobs:
  heavy-job:
    schedule: "@hourly"
    subcommand: process:heavy-stuff
    allowConcurrent: true
    resources:
      cpu: 1000m
      memory: 2Gi
Back to top