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-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1Clusters 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.
# 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-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
generatenever 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-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: truefrom 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-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-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-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
name: shop
cluster: hetzner-fsn1# 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: generalsecrets: [] 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.