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
# 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# 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| Key | Meaning |
|---|---|
name, display_name | The project's name and the name shown in the dashboard. |
cluster | The 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. |
quotas | Resource limits for the whole project. {} removes them all. |
isolated | Isolate the project's apps from each other. Changing it switches an existing project; leaving it out keeps the current setting. |
network_policies, egress | Traffic 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:
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
image: ghcr.io/example/api:1.4.2
port: 8080With 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.
# 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: 8080A build from a GitHub repository reachable through one of your organization's GitHub installations:
# 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: pushA managed template, with its version:
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
template: postgres
version: "16"
instances: 1registry_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.prereleaseorrelease: a matching tag or release.tag_patternnarrows 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.
# 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: 8080Scaling
replicas: a fixed number of replicas.autoscaling:minandmaxreplicas and thetriggersthat scale between them (such ascpu,memory,httporcron).scale_to_zeroneedsmin: 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) runsinstancesas given.per_noderunsinstanceson every running node of the app'spool, so the total grows with the pool. An app without a pool runsinstancesas given.
# 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: cpuRollouts
# 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: truestrategy 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: nullunpins the app. Apps must name a reserved pool to run on it.isolation:standard(the default) orsandboxed, which runs the app under Kata Containers where the pool offers it and gVisor otherwise.require_kata: true: require Kata, with no gVisor fallback. Impliessandboxed.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.
# 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-apiNumbers 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.
# 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:
# 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| Key | Meaning |
|---|---|
egress_internet | Whether the namespace's pods may reach the public internet. Private ranges stay blocked. |
egress_allow_fqdns, egress_allow_cidrs | Hosts and address ranges they may reach. |
max_pod_seconds | The longest deadline a pod or job may set; when set, every pod and job must set one. |
quota_cpu_millis, quota_memory_mib, quota_pods | The namespace's resource quotas. |
isolate_pods | Block traffic between the namespace's own pods; each talks only to the app, DNS and allowed egress. |
enabled | false turns the namespace off; true (or any other key) on an app whose namespace is off asks to turn it on. |
runtime | The 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_namespacefor an app, the app's workload namespace settings can't be edited in the console or API, includingenabledandruntime(409field_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. SeePodSettings.auto_update: watch a public image for updates.build_size: the build machine size for agitsource: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) or20xlarge(160 vCPU, 320 GiB). A size that doesn't exist or exceeds your organization's build quota is refused withinvalid_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.