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

# Environments and secrets

> Declare environments and secret groups in an infrastructure link. Secret values never go in Git.

## Environments

An environment file is `environments/<name>.yaml` in an infrastructure link.
It only needs the version: the file name is the environment's name.

```yaml title="environments/prod.yaml" iac tree=secrets
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
```

Clusters and secret groups name their environment, and projects belong to
their cluster's environment. Environments are applied before everything else
in a sync, so one push can add an environment and the resources that use it.
Removing an environment file is [held](/iac/gitops#held) until someone
confirms it.

## Secret groups

A secret group file is `secrets/<name>.yaml`. It declares the group's
environment, a description and the keys, with how each key reaches the apps.
It never holds a value.

```yaml title="secrets/shop-api.yaml" iac tree=secrets
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
environment: prod
description: Keys for the shop API
keys:
  STRIPE_SECRET_KEY: {}
  SIGNING_KEY:
    mount: /run/secrets/signing.pem
  SMTP_PASSWORD:
    mount: /run/secrets/smtp
    env: true
```

| Key spec | Injected as |
| --- | --- |
| `{}` | An environment variable named after the key. |
| `mount: <path>` | A file at that absolute path. |
| `mount: <path>` plus `env: true` | Both. |

A group lists at most 128 keys. A file that contains `value`, `values` or
`data` is refused: set values in the dashboard or through the API.

### Values

A key listed in the file without a value yet is created as a placeholder.
Apps don't receive it until it has a value, and the link lists it as a key
without a value. Setting the value in the dashboard or through the API
clears the placeholder. Syncs never read or compare supplied values.

### Generated and derived values

A key can get its value from the platform instead, so internal tokens never
have to be typed in. `generate` creates a random value or a key pair on the
first sync. `derive` computes the value from other keys of the environment
and keeps it in step with them.

```yaml title="secrets/shop-core.yaml" iac tree=secrets
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
environment: prod
description: Internal tokens, all generated
keys:
  ENCRYPTION_KEY:
    generate: {encoding: base64, bytes: 32, rotate: false}
  QUEUE_TOKEN:
    generate: {}
  QUEUE_URL:
    derive: {template: 'nats://${QUEUE_TOKEN}@nats:4222'}
  QUEUE_TOKEN_SHA256:
    derive: {sha256: QUEUE_TOKEN}
  TOKEN_KEY:
    generate: {keypair: p256}
    mount: /run/secrets/signing.pem
  TOKEN_PUBLIC_KEY:
    derive: {public_key: TOKEN_KEY}
```

| Field | Meaning |
| --- | --- |
| `generate.encoding` | `hex` (default), `base64` or `base64url`. |
| `generate.bytes` | Random bytes, 16 to 512 (default 32). |
| `generate.keypair: p256` | A P-256 private key (PKCS#8 PEM) instead of random bytes. |
| `generate.rotate: false` | Rotation is refused (use it for encryption keys). |
| `derive.sha256: KEY` | The lowercase hex sha256 of `KEY`. |
| `derive.public_key: KEY` | The public half (SPKI PEM) of the P-256 key in `KEY`. |
| `derive.template` | Text with each `${KEY}` replaced by that key's value. |
| `derive.egress_cidrs` | The public IPv4 `/32` and IPv6 `/64` of every node in the environment's clusters, plus the CIDRs in `KEY` with `{plus: KEY}`, sorted, deduplicated and comma-separated. Kept up to date as nodes come and go; a node stays listed until it is deleted. |

- A generated value is created once and stays the same on later syncs.
  Rotate it from the dashboard or the API to replace it. Keys derived from
  it follow, and the old values are kept as earlier versions.
- A derived key can read a key of another group in the same environment, but
  not another derived key. It cannot be rotated, and a value set by hand is
  recomputed on the next sync.
- A key that already has a value keeps it. Switching an existing key to
  `generate` never replaces the value it holds, and a derived key is
  computed from the values its sources already hold.
- A key shared by several groups must be declared the same way in each.

Changing a key's `mount` or `env` setting updates the apps that use the
group.

### Write-only keys

`write_only: true` makes a key write-only: its value can be set, replaced
or deleted, but nobody can read it back, not in the dashboard and not
through the API (it answers `403`, "this key is write-only"). Apps still
receive it. It combines with the other key options:

```yaml title="secrets/payments.yaml" iac tree=secrets
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
environment: prod
description: Payment provider keys nobody needs to read back
keys:
  STRIPE_SECRET_KEY: {write_only: true}
  WEBHOOK_SIGNING_KEY:
    generate: {}
    write_only: true
```

- The flag is one-way. Removing `write_only: true` from the file does not
  make the key readable again: the sync reports that it stays write-only.
  Delete the key and create it again to get a readable one.
- The sync reports a key becoming write-only, and the activity log records
  it. Plans and reports never show values.

### Version history

Replacing a key's value (by hand, a rotation, an import or a sync) archives
the old one. The secret's **Versions** tab lists the archived versions with
their size; Members can reveal one (audited, never for a write-only key),
restore it as a new version, or destroy it. Every stored version is billed
like the current value.

`keep_versions` sets how many archived versions a key keeps, 1 to 100
(default 10). Older ones are destroyed for good, right away when you lower
it:

```yaml title="secrets/api.yaml" iac tree=secrets
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
environment: prod
description: API keys with a short history
keys:
  API_TOKEN: {keep_versions: 3}
```

Leaving `keep_versions` out keeps whatever is set (also from the
dashboard). Two groups that set a different `keep_versions` for the same
key fail the sync.

### Using a group in an app

An app lists the groups it uses in `secrets`. The group must belong to the
environment of the app's project.

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

```yaml title="projects/shop/project.yaml" iac tree=secrets
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
name: shop
cluster: hetzner-fsn1
```

```yaml title="clusters/hetzner-fsn1.yaml" iac tree=secrets
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
provider: hetzner
region: fsn1
environment: prod
pools:
  - name: control-plane
    role: control_plane
  - name: general
```

`secrets: []` unlinks every group; leaving `secrets` out leaves the app's
groups as they are.

## What removing does

Removing a key from a group file removes it from the group:

- A key without a value leaves the group on the next sync.
- A key with a value waits for a confirmation in the dashboard (it needs
  step-up and the key's name). Once confirmed it leaves the group, and its
  value is deleted unless another group injects the same key.
- Both are recorded in the activity log.

Keys added to the group outside Git (in the dashboard or through the API)
are not removed: they keep being injected and the sync reports them as
unmanaged. Deleting a group file does not delete the group or its keys
either; the sync reports the group as not in Git.

A group file has no keys that delete: `allow_delete` and
`delete_unlisted_keys` don't exist, and like any unknown key they are
refused. Remove keys and groups in the dashboard.

See the [secret group file reference](/iac/reference/secret-group-file) and
the [environment file reference](/iac/reference/environment-file).
