Skip to Content

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.

environments/prod.yaml
# 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 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.

secrets/shop-api.yaml
# 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 specInjected as
{}An environment variable named after the key.
mount: <path>A file at that absolute path.
mount: <path> plus env: trueBoth.

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.

secrets/shop-core.yaml
# 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}
FieldMeaning
generate.encodinghex (default), base64 or base64url.
generate.bytesRandom bytes, 16 to 512 (default 32).
generate.keypair: p256A P-256 private key (PKCS#8 PEM) instead of random bytes.
generate.rotate: falseRotation is refused (use it for encryption keys).
derive.sha256: KEYThe lowercase hex sha256 of KEY.
derive.public_key: KEYThe public half (SPKI PEM) of the P-256 key in KEY.
derive.templateText with each ${KEY} replaced by that key's value.
derive.egress_cidrsThe 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:

secrets/payments.yaml
# 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:

secrets/api.yaml
# 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.

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
secrets:
  - shop-api
projects/shop/project.yaml
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
name: shop
cluster: hetzner-fsn1
clusters/hetzner-fsn1.yaml
# 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 and the environment file reference.

On this page