Skip to Content

References

Fill an app's environment variables from buckets, storages, domains and other apps.

An env value can be a literal, or a reference to an output of another resource. A reference keeps the value in one place: when the bucket's endpoint or the app's host changes, the next apply updates every app that reads it.

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
env:
  LOG_LEVEL: info
  ASSETS_BUCKET:
    from: bucket/assets
    output: name
  ASSETS_ENDPOINT:
    from: bucket/assets
    output: endpoint
  PUBLIC_ORIGIN:
    from: domain/example.com
    output: hostname
    format: "https://{}"
  WORKER_URL:
    from: app/worker
    output: internal_url
  STRIPE_WEBHOOK_SECRET:
    external: true
projects/shop/apps/worker.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/worker:1.4.2
port: 9000
projects/shop/project.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
name: shop
cluster: hetzner-fsn1
buckets:
  - name: assets
    quota_gb: 50
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

The project link manages the assets bucket itself, so api can read it directly. The domain example.com is claimed by the organization's infrastructure link, so the project link needs a grant for it.

The keys

KeyMeaning
from<kind>/<name>: bucket/<name>, storage/<name>, domain/<name> or app/<name>.
outputWhich output to read (below).
formatA template with exactly one {}, which the output replaces. Anything else is refused with ref_bad_format.
portOnly for srv_host: which port's generated host to read.

external: true marks a value that is set outside the repository, in the dashboard or through the API. A sync never writes or removes it. It can't be combined with the other keys.

For database credentials, use a lease instead.

Outputs

KindOutputs
bucketname, endpoint, region, public_url
storageendpoint, bucket, region
domainhostname
appinternal_host, internal_url, port, url, hostname, srv_host

Credentials (a bucket's or storage's access keys, an app's password or connection_url) are never written into an env var by a file: referencing them is refused with secret_output_not_inlinable. Use a storage binding for bucket credentials.

An unknown output is refused with ref_unknown_output, and port on an output other than srv_host with ref_bad_port.

An app/ reference reads an app of the same project. Apps can reference each other in both directions, and an app can reference itself.

In the plan

The plan shows a reference's value when it is known. A value that only exists after the apply, such as the host of an app the same change creates, shows as (known after apply).

If a reference can't be resolved during the apply (ref_unresolved), that app keeps its previous environment and the other apps carry on.

What a link can read

A reference can always read resources the same link manages. Everything else needs a grant:

  • a bucket, storage or domain managed by another link of your organization;
  • one created in the dashboard, which no link manages;
  • an app domain under a verified domain this link doesn't manage.

Grants are given in the dashboard, by an environment admin of the referencing project (an organization admin for an infrastructure link). API keys can't give grants.

A missing grant, a resource of another organization and a resource that doesn't exist all give the same refusal, ref_not_granted, so a reference never reveals what exists outside your reach.

Removing a referenced resource

Removing a bucket, storage or domain from a link while references in the same link still read it is refused with ref_orphaned. Remove or change the references in the same change.

On this page