Docs

Customer-managed keys in a deployment

Customer-managed keys in a deployment (bring your own key, or BYOK) mean a deployment's buckets, databases, and volumes encrypt under a key the customer owns and can revoke. Enterprise customers ask for it even when the data already sits in their own cloud; one alien.Key in alien.ts adds it.

This page is for a deployment in the customer's cloud, one path of Customer-managed keys. If your product runs in your own cloud, see Add customer-managed keys to your product.

alien.ts
import * as alien from "@alienplatform/core"

// The customer's key. The admin creates it at initial setup, in their own key service.
const customerKey = new alien.Key("customer-key").build()

// Each store names the key. The choice can't change after the resource exists.
const files = new alien.Storage("files").encryptionKey(customerKey).build()
const db = new alien.Postgres("db").encryptionKey(customerKey).build()

const api = new alien.Container("api")
  .code({ type: "image", image: "ghcr.io/acme/api:1.4.0" })
  .cpu(1)
  .memory("2Gi")
  .port(8080)
  .persistentStorage("100Gi", { encryptionKey: customerKey })
  .link(files)
  .link(db)
  .permissions("api")
  .build()

export default new alien.Stack("acme-data-plane")
  .platforms(["aws"])
  .add(customerKey, "frozen")
  .add(files, "frozen")
  .add(db, "frozen")
  .add(api, "live")
  .permissions({
    profiles: {
      api: { files: ["storage/data-read", "storage/data-write"] },
    },
  })
  .build()

Architecture diagram. Left: Your side containing Alien, Releases, Deployments. Right: customer-1's cloud containing customer-key (KMS); Deployment containing files (S3); db (Aurora); api volume (EBS).

The key and every store that uses it live in the customer's account. Alien checks whether the key is available; it never holds key material.

If the customer revokes the key, the data becomes unreadable until they restore it. The customer, not you, decides whether their data can be read.

  • The customer's admin creates the key during the initial setup, with their own credentials.
  • Your workloads read and write data through the cloud services, which call the key.
  • During ongoing management, Alien's management identity only checks whether the key is available.

Declare the key

These resources accept a key:

ResourceOptionPlatforms
Storage.encryptionKey(key)AWS (S3), Google Cloud (Cloud Storage), Azure (Blob Storage)
Postgres.encryptionKey(key)AWS (Aurora)
Container volume.persistentStorage(size, { encryptionKey })AWS (EBS volumes and their snapshots)

encryptionKey must reference an alien.Key in the same stack. A build fails if a stack uses a key on a platform that doesn't support it, so the example above targets AWS only.

Add the Key, and any Storage that uses it, as "frozen". A frozen resource is one that only the initial setup creates or changes, with the admin's credentials.

  • You can't add, remove, or replace the key on a resource that already exists. Decide before the first deployment.
  • On Azure, the key applies to the whole storage account, so a stack that encrypts Storage with a key can contain only one Storage resource.

See Key for each provider's mapping.

Use the key from your backend

Your hosted backend can also encrypt application records with the deployment's key through the Encrypt/Decrypt API. Add the key with remoteAccess, and select the deployment with X-Alien-Deployment-ID:

alien.ts
export default new alien.Stack("acme-keys")
  .add(customerKey, "frozen", { remoteAccess: true })
  .add(files, "frozen")
  .build()

The Encrypt/Decrypt API accepts a deployment whose only remote-access resource is one running Key.

What the customer controls

The initial setup creates the key in the customer's account, with the admin's credentials: an AWS KMS key, a Google Cloud KMS key, or an Azure Key Vault key. On AWS, initial setup with Terraform can use an existing KMS key in the same account and region instead.

The key stays in the customer's account, and only initial setup creates or deletes it. Alien's management identity checks whether the key is available.

A stack with a Key deploys only through the CloudFormation or Terraform setup method. The CLI setup method, including alien deploy, refuses it before creating anything, with SETUP_METHOD_CANNOT_INSTALL_RESOURCES.

Revoke and restore

When the customer disables the key or removes access to it:

  • The deployment shows Customer key unavailable, with the hint that resources are preserved and recover automatically.
  • Alien stops changing the resources that use the key. It never deletes or replaces them to work around a missing key.
  • Each cloud service stops reading the data on its own schedule. In AWS tests, the deployment reported the key unavailable about 5 minutes after revocation.
  • A running Aurora cluster stopped serving after about 26 minutes, because a running database keeps its data key in memory for a while.

When the customer restores access, the same database, bucket, and volumes recover with their data. Alien never recreates them.

Design the rest of your product for this state. Show a revoked key to the customer as an expected condition, and don't fall back to a copy of their data elsewhere.

Deployments in your account

A single-tenant deployment in your own AWS account can use the same alien.ts with a key the customer controls. The key can live in the customer's AWS KMS, Google Cloud KMS, or Azure Key Vault. It covers Aurora, S3, and persistent EBS volumes.

For AWS resources you run outside Alien, an AWS Virtual Key gives you an ordinary KMS key ARN backed by the customer's key. See AWS Virtual Keys.

Test it

Deploy the stack to a cloud account you control, as your own test customer:

alien onboard "Test customer" --external-id org_test

Open the printed link and run initial setup. Then, for each cloud you offer:

  1. Write data through your workload, and confirm it lands in the encrypted bucket, database, or volume.
  2. Disable the key in the cloud console and wait longer than 5 minutes.
  3. Confirm the deployment shows Customer key unavailable in the dashboard and your product shows the state to the customer.
  4. Restore the key and confirm the same resources recover with their data.

Next

AWS Virtual Keys

Encrypt S3, Aurora, DynamoDB, or EBS in your own AWS account with a key your customer holds, through an ordinary AWS KMS key ARN.

Data and keys

What Alien receives, what the customer's key controls, what must match at decrypt time, and what your application must do.

On this page

Declare the keyUse the key from your backendWhat the customer controlsRevoke and restoreDeployments in your accountTest itNext