> Index of every page on this site: [llms.txt](https://docs.a-line.cloud/llms.txt)

# 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.

```yaml title="projects/shop/apps/api.yaml" iac tree=refs
# 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
```

```yaml title="projects/shop/apps/worker.yaml" iac tree=refs
# 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
```

```yaml title="projects/shop/project.yaml" iac tree=refs
# 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
```

```yaml title="clusters/hetzner-fsn1.yaml" iac tree=refs
# 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](#grants) for it.

## The keys

| Key | Meaning |
| --- | --- |
| `from` | `<kind>/<name>`: `bucket/<name>`, `storage/<name>`, `domain/<name>` or `app/<name>`. |
| `output` | Which output to read (below). |
| `format` | A template with exactly one `{}`, which the output replaces. Anything else is refused with `ref_bad_format`. |
| `port` | Only 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](/iac/databases#consumers) instead.

## Outputs

| Kind | Outputs |
| --- | --- |
| `bucket` | `name`, `endpoint`, `region`, `public_url` |
| `storage` | `endpoint`, `bucket`, `region` |
| `domain` | `hostname` |
| `app` | `internal_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](/iac/data#storage-bindings) 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.
