|
| 1 | +# Encryption |
| 2 | + |
| 3 | +Talm provides built-in encryption support using [age](https://age-encryption.org/) encryption. Sensitive files are encrypted with their values stored in SOPS format (`ENC[AGE,data:...]`), while YAML keys remain unencrypted for better readability. |
| 4 | + |
| 5 | +## Encrypting files |
| 6 | + |
| 7 | +To encrypt all sensitive files (secrets.yaml, talosconfig, kubeconfig): |
| 8 | + |
| 9 | +```bash |
| 10 | +talm init --encrypt |
| 11 | +# or |
| 12 | +talm init -e |
| 13 | +``` |
| 14 | + |
| 15 | +This command will: |
| 16 | +- Generate `talm.key` if it doesn't exist |
| 17 | +- Encrypt `secrets.yaml` → `secrets.encrypted.yaml` |
| 18 | +- Encrypt `talosconfig` → `talosconfig.encrypted` |
| 19 | +- Encrypt `kubeconfig` → `kubeconfig.encrypted` (if exists) |
| 20 | +- Encrypt `values-secret.yaml` → `values-secret.encrypted.yaml` (if exists) |
| 21 | +- Update `.gitignore` with sensitive files |
| 22 | + |
| 23 | +## Decrypting files |
| 24 | + |
| 25 | +To decrypt all encrypted files: |
| 26 | + |
| 27 | +```bash |
| 28 | +talm init --decrypt |
| 29 | +# or |
| 30 | +talm init -d |
| 31 | +``` |
| 32 | + |
| 33 | +This command will: |
| 34 | +- Decrypt `secrets.encrypted.yaml` → `secrets.yaml` |
| 35 | +- Decrypt `talosconfig.encrypted` → `talosconfig` |
| 36 | +- Decrypt `kubeconfig.encrypted` → `kubeconfig` (if exists) |
| 37 | +- Decrypt `values-secret.encrypted.yaml` → `values-secret.yaml` (if exists) |
| 38 | +- Update `.gitignore` with sensitive files |
| 39 | + |
| 40 | +## Encrypted user values |
| 41 | + |
| 42 | +Beyond Talos' own PKI/tokens, you can store **arbitrary secret values that chart templates consume** (a registry password, a KMS plugin's secret-id, etc.) encrypted at rest with the same `talm.key`: |
| 43 | + |
| 44 | +1. Author the secrets in plaintext `values-secret.yaml` (git-ignored), e.g.: |
| 45 | + |
| 46 | + ```yaml |
| 47 | + registryPassword: hunter2 |
| 48 | + ``` |
| 49 | +
|
| 50 | +2. Encrypt them with `talm init --encrypt` → produces the committable `values-secret.encrypted.yaml` (per-value `ENC[AGE,...]` envelopes; keys stay readable). |
| 51 | + |
| 52 | +3. Reference the **encrypted** file from `Chart.yaml`: |
| 53 | + |
| 54 | + ```yaml |
| 55 | + templateOptions: |
| 56 | + valueFiles: |
| 57 | + - values-secret.encrypted.yaml |
| 58 | + ``` |
| 59 | + |
| 60 | +`talm template` and `talm apply` decrypt it **in memory** via `talm.key` — the plaintext never has to be present at render time. Both commands honor the full value-source set (`--values`, `--set`, `--set-string`, `--set-file`, `--set-json`, `--set-literal`) plus `templateOptions.*`, so a value renders identically whether you preview with `template` or push with `apply`. |
| 61 | + |
| 62 | +Secret values are kept out of committed and printed output: |
| 63 | + |
| 64 | +- `talm template -I` **omits** secret-bearing fields from the rendered `nodes/*.yaml`; the real value is re-injected only at `apply` (which re-renders from the encrypted file). |
| 65 | +- `talm template` (stdout) and `talm apply` (drift preview) **redact** them to `***` by default. Reveal verbatim with `talm template --show-secrets` / [`talm apply --show-secrets-in-drift`](../operations/safety-gates.md) (debugging only). |
| 66 | + |
| 67 | +!!! danger "Put the encrypted file in Chart.yaml, not only on the command line" |
| 68 | + |
| 69 | + Reference the encrypted file from `Chart.yaml templateOptions.valueFiles` (as shown above), NOT only via `template --values`. The node-file modeline does not persist value files, so `apply` only re-reads what is in `Chart.yaml` (plus its own `--values`). If an encrypted file is passed solely to `template -I`, the omitted secret is absent from the node file AND never re-rendered at apply — silently lost from the applied config. `template -I` prints a warning when it omits secrets from a file that is not in `Chart.yaml`. |
| 70 | + |
| 71 | +!!! warning "Encrypt only high-entropy values" |
| 72 | + |
| 73 | + Sealing matches by exact value across the whole rendered config, so do not encrypt low-entropy values that collide with ordinary config strings (e.g. a bare port, or a password literally set to `controlplane`) — that unrelated field would be sealed too. Prefer high-entropy secrets. Secret values must be strings (quote them in `values-secret.yaml`); the encryption only covers string leaves. |
| 74 | + |
| 75 | +## Key management |
| 76 | + |
| 77 | +The `talm.key` file is generated in age keygen format and contains: |
| 78 | +- Creation timestamp |
| 79 | +- Public key (for sharing) |
| 80 | +- Private key (keep secure!) |
| 81 | + |
| 82 | +!!! danger "Back up talm.key" |
| 83 | + |
| 84 | + Always backup your `talm.key` file! Without it, you won't be able to decrypt your encrypted secrets. The key file is automatically added to `.gitignore` to prevent accidental commits. |
| 85 | + |
| 86 | +Encrypted files (`*.encrypted.yaml`, `*.encrypted`) can be safely committed to Git, while plain files (`secrets.yaml`, `talosconfig`, `kubeconfig`, `talm.key`) are ignored. |
0 commit comments