Skip to Content

Projects and apps

Describe a project, its apps, where their containers come from and how they scale and deploy.

A project link reads project.yaml and one file per app in apps/. The app file's name is the app's name.

The project file

projects/shop/project.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
name: shop
display_name: Shop
cluster: hetzner-fsn1
quotas:
  pods: 40
clusters/hetzner-fsn1.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
provider: hetzner
region: fsn1
pools:
  - name: control-plane
    role: control_plane
  - name: general
KeyMeaning
name, display_nameThe project's name and the name shown in the dashboard.
clusterThe cluster the project runs on. Required when the project is created, and fixed while it has apps. The project belongs to the cluster's environment.
quotasResource limits for the whole project. {} removes them all.
isolatedIsolate the project's apps from each other. Changing it switches an existing project; leaving it out keeps the current setting.
network_policies, egressTraffic between projects and out of the cluster, see networking.

See the project file reference for every key.

Where the container comes from

source takes exactly one of image, git or template. Creating an app needs a source. Leaving source out of an existing app's file leaves its source as it is.

A prebuilt image:

projects/shop/apps/api.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/api:1.4.2
port: 8080

With pin: release, the image is set once when the app is created. After that, release deploys own it: the sync neither reports drift for it nor locks it.

projects/shop/apps/worker.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/api:1.4.2
  pin: release
port: 8080

A build from a GitHub repository reachable through one of your organization's GitHub installations:

projects/shop/apps/web.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  git:
    repo: example/shop-web
    branch: main
    dockerfile: Dockerfile
    context: .
port: 3000
triggers:
  on: push

A managed template, with its version:

projects/shop/apps/db.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  template: postgres
  version: "16"
instances: 1

registry_credential names a registry credential for pulling a private image.

What deploys the app

triggers.on decides which events deploy a git app:

  • push: every push to the branch.
  • prerelease or release: a matching tag or release. tag_pattern narrows which tags count.
  • manual: only deploys you start.

Without a triggers block a new git app deploys on push, like an app made in the console: the branch head builds as soon as the app is created and on every push after that. Set on: manual to deploy only when you start a deploy. A trigger already set on the app, such as manual picked in the console, is kept. Static sites follow the same default.

github_environment names the GitHub environment deployments are reported to.

Ports and health checks

port is the app's single port. For several ports, use ports; the first one is the primary port.

projects/shop/apps/gateway.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/api:1.4.2
ports:
  - port: 8080
    name: http
  - port: 9090
    name: metrics
health_path: /healthz
health_port: 8080

Scaling

  • replicas: a fixed number of replicas.
  • autoscaling: min and max replicas and the triggers that scale between them (such as cpu, memory, http or cron). scale_to_zero needs min: 0.
  • instances: the instance count of a template that sizes by instances (Postgres, Valkey, ClickHouse and others), within the template's bounds and counted against the project quota.
  • replica_mode: fixed (the default) runs instances as given. per_node runs instances on every running node of the app's pool, so the total grows with the pool. An app without a pool runs instances as given.
projects/shop/apps/storefront.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/web:2.0.0
port: 3000
autoscaling:
  min: 2
  max: 10
  triggers:
    - type: cpu

Rollouts

projects/shop/apps/checkout.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/api:1.4.2
port: 8080
deploy:
  strategy: rolling
  max_surge: 1
  max_unavailable: "25%"
  rollback_on_failure: true

strategy is rolling, recreate or safe_replace. max_surge and max_unavailable take a count or a percentage.

Placement

  • pool: the node pool the app runs on. It must be a pool of the project's cluster, and not a control-plane pool. pool: null unpins the app. Apps must name a reserved pool to run on it.
  • isolation: standard (the default) or sandboxed, which runs the app under Kata Containers where the pool offers it and gVisor otherwise.
  • require_kata: true: require Kata, with no gVisor fallback. Implies sandboxed.
  • gpu_count: the number of GPUs the app needs.

Environment variables and secrets

env maps names to values. A value is a literal, a reference to another resource's output, a database lease, or {external: true} for a value you set in the dashboard. A sync never writes or removes an external key.

projects/shop/apps/orders.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/api:1.4.2
port: 8080
env:
  LOG_LEVEL: info
  WORKERS: 4
  STRIPE_KEY:
    external: true
secrets:
  - shop-api

Numbers and booleans are stored as text. secrets links secret groups of the environment to the app; [] unlinks them all.

Sidecar and init container secrets

A sidecar or init container under pod can take secret groups of its own. Their values reach that container only, as environment variables; the app container never sees them. Use this for a key only a helper needs, such as a download licence.

projects/shop/apps/catalog.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/api:1.4.2
port: 8080
pod:
  volumes:
    - { name: data, size_limit: 1Gi }
  mounts:
    - { volume: data, path: /data, read_only: true }
  sidecars:
    - name: fetcher
      image: ghcr.io/example/fetcher:2.0.0
      secrets: [shop-fetcher]
      mounts:
        - { volume: data, path: /data }

The groups must exist in the app's environment; a deploy naming an unknown group fails. Only members delivered as environment variables are passed; a group value replaces a plain env entry of the same name on that container. An init container runs to completion before the app starts, and a sidecar keeps running next to it, so an init container that fetches a file once plus a sidecar that refreshes it means the app starts with the file present.

Workload namespace

An app with a workload namespace can start its own pods through the Kubernetes API. Turning the namespace on is done in the dashboard only, because it grants that API access. Its egress policy and quotas can be set in the file:

projects/shop/apps/runner.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/runner:1.0.0
workload_namespace:
  egress_internet: false
  egress_allow_fqdns: [api.example.com]
  max_pod_seconds: 3600
  quota_cpu_millis: 4000
  quota_memory_mib: 8192
  quota_pods: 20
  isolate_pods: true
KeyMeaning
egress_internetWhether the namespace's pods may reach the public internet. Private ranges stay blocked.
egress_allow_fqdns, egress_allow_cidrsHosts and address ranges they may reach.
max_pod_secondsThe longest deadline a pod or job may set; when set, every pod and job must set one.
quota_cpu_millis, quota_memory_mib, quota_podsThe namespace's resource quotas.
isolate_podsBlock traffic between the namespace's own pods; each talks only to the app, DNS and allowed egress.
enabledfalse turns the namespace off; true (or any other key) on an app whose namespace is off asks to turn it on.
runtimeThe runtime workload pods run under: kata, or runc in dev environments only.
  • DNS egress is managed by the platform.
  • Keys you leave out keep their current values.
  • Turning the namespace on or changing its settings is never applied by the sync alone. It is held until an environment admin confirms it with step-up. Turning it off narrows access, so the sync applies it directly.
  • While a file sets workload_namespace for an app, the app's workload namespace settings can't be edited in the console or API, including enabled and runtime (409 field_managed_in_git). Change the file instead.

Removing an app

Deleting an app's file holds the app as a pending deletion until someone confirms it. delete_data.buckets: true also deletes the app's buckets with it. Backups are never deleted with their app.

Other keys

  • pod: low-level pod settings such as command, args, resources, probes, sidecars and init containers. See PodSettings.
  • auto_update: watch a public image for updates.
  • build_size: the build machine size for a git source: small (1 vCPU, 2 GiB), medium (2 vCPU, 4 GiB, the default), large (4 vCPU, 8 GiB), xlarge (8 vCPU, 16 GiB), 2xlarge (16 vCPU, 32 GiB), 4xlarge (32 vCPU, 64 GiB), 8xlarge (64 vCPU, 128 GiB), 16xlarge (128 vCPU, 256 GiB) or 20xlarge (160 vCPU, 320 GiB). A size that doesn't exist or exceeds your organization's build quota is refused with invalid_build_size. While the key is set, the size picker in the console is locked. When machines of a size are busy, its builds wait in the queue instead of failing. Leaving the key out keeps the current size.
  • http, domains, connections, egress: see networking.
  • volumes, volume_mounts, backup, backup_policies, cron_jobs: see volumes, backups and cron jobs.
  • databases, roles, lease_files: see databases and leases.

See the app file reference for every key.

On this page