Skip to content

Sealed secrets#

A sealed secret is a set of named values — a password, an API token, a key file — that Astralyx keeps for a workspace only as ciphertext. Each value is encrypted on your own device, in the console or by astra secrets, before it is sent. Only the workspace's machines that an admin approved can decrypt it, and a machine does so only for the runs placed on it that use the secret. Use sealed secrets when your workspace has no secret manager of its own; when it has one, a credential that references it keeps the value out of Astralyx altogether.

In the console a sealed secret is under Secrets; on the command line it is astra secrets; in the API it is a sealed secret (/sealed-secrets).

How it works#

flowchart LR
    D["Your device<br/>(console or astra)"] -- "values encrypted to<br/>the workspace public key" --> A["Astralyx<br/>stores ciphertext only"]
    D -- "signs a machine's<br/>key fingerprint" --> A
    A -- "ciphertext" --> M["Approved machine<br/>holds the workspace private key"]
    M -- "files and variables" --> W["Worker"]
  • The workspace key. Each workspace (on each cluster) has its own key pair. Astralyx keeps its public half, which your device encrypts values to. Its private half exists only on machines an admin approved; each holds it encrypted to a key of its own that never leaves the machine.
  • The machine key. The machine's credentials agent (astraeus-agent-credentials) makes a key the first time it starts, in /var/lib/astraeus/credentials/sealing.key (mode 0600), and reports only its public half. Its fingerprint is what an admin compares before approving the machine: astraeus-agent credentials --fingerprint prints it on the machine.
  • Approval is a signature. Approving a machine is not a switch in Astralyx: the admin's device — the browser or astra — signs "machine gpu-01 has the key with fingerprint F" with its own approver key. A machine that already holds the workspace key passes it on only to a machine key that an approver signed. The first machine approved in a workspace makes the workspace key.
  • Approver devices. An approver key lives on one device: a browser profile (a key the browser cannot export) or astra (~/.config/astra/approver.p8, readable by you only). The first device to approve a machine becomes the workspace's first approver. Any other device becomes one when an existing approver endorses it.
  • In a run. Creating a sealed secret also creates a credential of the same name. A run names that credential like any other and gets each key of the secret as a file, an environment variable, or both. The machine decrypts the values in memory and writes them to the run's private credential directory, and the run's logs mask them.

What Astralyx can and cannot do#

These are guarantees of the design, not settings.

Astralyx can Astralyx cannot
Store, list and delete your sealed secrets, and refuse to deliver them: deny service, as any provider can. Read a value. It never holds the workspace private key or a machine's key.
See each secret's name, its key names, who changed it and when. See a value's content. A value that is not ciphertext for the workspace's current key is refused, so a plaintext cannot be stored by mistake.
Show you a machine's fingerprint and relay your approval. Give the workspace key to a machine on its own. A machine passes it on only to a machine key an approver's device signed, checked against an approver list that only the workspace key can vouch for.
Register a device as a candidate approver. Make a device an approver. An existing approver's signature is needed, and a machine holding the workspace key checks it.
Move ciphertext around. Make a value open somewhere else. Each value is bound to its workspace, secret, key name and workspace key: moved to another, it no longer decrypts.

What you trust Astralyx for, and what is not defended against an actively malicious Astralyx:

  • The first approver is trusted on first use. Before a workspace has a key, the first device to approve a machine becomes its first approver. Compare the fingerprint the console or astra shows with what the machine prints: a fingerprint that does not match is a machine you do not control.
  • The public key you encrypt to. Your device encrypts to the workspace public key Astralyx serves. A malicious Astralyx could serve a key of its own and read values written afterwards. Your machines would then fail to decrypt those values — the substitution shows as runs waiting with does not open. Values written before stay unreadable to it.

What no encryption prevents:

  • A run that uses a secret receives its value. Code in that run can read it and send it wherever the run may send traffic. Outbound rules bound where that is; log masking catches accidents, not intent.
  • An approved machine holds the workspace key. Someone with root on it can decrypt every value of the workspace that reaches it. Approve only machines you would trust with all of the workspace's secrets.
  • A machine you remove keeps what it already decrypted. Revoking or removing it rotates the workspace key, so it cannot decrypt anything new; values it saw are still known to it. When that matters, change the values at their source and set them again.

Rotation#

Revoking a machine's approval, removing the machine from the cluster, or a machine's key changing (a reinstalled machine) rotates the workspace key: an approved machine that holds the key makes a new one, gives it to every machine still approved, and re-encrypts every sealed secret of the workspace to it. When no value is encrypted to the old key any more, the old key is retired. You can also rotate at any time. Rotation changes the key, not the values.

Sealed secret or credential?#

Sealed secret Credential
Where the value is kept In Astralyx, encrypted to a key only your approved machines hold In your secret manager; Astralyx never sees it
What you need Nothing beyond your machines A secret manager, and an identity for the machines to read it
Who can decrypt Any machine an admin approved for the workspace Any machine whose identity your secret manager allows
Setting a value Console or astra secrets Your secret manager's own tools
In a run A credential of the same name, made for you The credential