Fjall Docs — deploy AWS infrastructure into your own account

Overview

CustomerManagedKey provisions an AWS KMS customer-managed key (CMK) for protecting data at rest. It creates the key and its alias together, turns on automatic rotation, and resolves the key’s removal policy from the required protects prop.

Resource class

import { CustomerManagedKey } from "@fjall/components-infrastructure/lib/resources/aws/secrets/kms";

CustomerManagedKey, KEY_PROTECTION_SCOPES and the KeyProtectionScope type are exported. The props interface is not, so pass an inline object literal, or type a helper parameter with KeyProtectionScope.

Basic usage

const key = new CustomerManagedKey(this, "ApiKey", {
  protects: "stack-scoped",
  description: "API encryption key",
  aliasName: "alias/api/encryption",
});

Configuration options

Property	Type	Description	Default
`protects`	`"stack-scoped" \| "outlives-stack"`	Whether anything the key encrypts survives the stack	required
`description`	`string`	Key description	`${id} KMS Key`
`aliasName`	`string`	Key alias	`cmk/${id}`, deployed `alias/cmk/${id}`
`removalPolicy`	`RemovalPolicy`	Explicit override of what `protects` would resolve to	resolved from `protects`

CDK prefixes an alias with alias/ when the value omits it, so the default alias reaches AWS as alias/cmk/<id>. That is the string aws kms describe-key --key-id expects.

Choosing `protects`

protects is required and has no default, because the two answers fail in opposite directions and only one of the failures is visible.

"stack-scoped" means everything the key encrypts is deleted along with the stack that created it: an SSM SecureString parameter, a Secrets Manager secret, RDS performance-insights data. The key then follows the same env-aware default as every other Fjall wrapper, RETAIN in production, DESTROY everywhere else.
"outlives-stack" means at least one encrypted resource survives the stack: an RDS final snapshot, a retained audit bucket, a Backup vault’s recovery points. The key is RETAIN in every environment.

A key destroyed while something it encrypted still exists makes that thing permanently unreadable, and nothing detects it. The survivor stays listed, sized and restorable-looking right up to the moment you try to restore it. When in doubt pass "outlives-stack": a key costs a few dollars a month, and the failure in the other direction cannot be undone.

`protects`	production	staging / development / platform / compliance / root
`"stack-scoped"`	`RETAIN`	`DESTROY`, with a 30-day pending window
`"outlives-stack"`	`RETAIN`	`RETAIN`

An unrecognised ENVIRONMENT throws at synth rather than guessing, since guessing DESTROY deletes data and guessing RETAIN leaks it. An explicit removalPolicy overrides the table and skips that check entirely.

Default features

Every CustomerManagedKey includes:

Automatic rotation: enableKeyRotation is always on. AWS rotates the backing key material annually. The construct exposes no option to turn it off.
Removal policy: resolved from protects (see the table above), or taken verbatim from an explicit removalPolicy.
Pending deletion window: 30 days whenever the key resolves to DESTROY. The key is disabled immediately and stays recoverable until the window elapses, long enough to cover the 30-day recovery window of a deleted Secrets Manager secret.
Retention marker tag: fjall:kms:retention, valued with the protects scope, on every key that resolves to RETAIN. Tags outlive the stack, so a posture scan can tell a key retained on purpose from one that was forgotten.
Automatic alias: created with the supplied or default name.
CloudFormation outputs: key ARN and alias ARN, both exported under a stack-scoped name.

Key components

The KMS key

const cmk = new CustomerManagedKey(this, "DataKey", {
  protects: "stack-scoped",
  description: "Data encryption key",
});

const key = cmk.key;
const keyArn = key.keyArn;
const keyId = key.keyId;

The key alias

const cmk = new CustomerManagedKey(this, "WebKey", {
  protects: "stack-scoped",
  aliasName: "alias/web/encryption",
});

const alias = cmk.alias;
const aliasName = alias.aliasName;
const aliasArn = alias.aliasArn;

Key rotation

Rotation is on for every key the construct creates. No configuration is needed, and there is no prop to disable it. AWS rotates the key material once a year and keeps every previous version, so ciphertext written under an older version stays decryptable. Rotation is billed. See Cost considerations before creating a key per resource.

Removal policy

protects decides the policy (see Choosing protects). Pass removalPolicy only to override that, either to keep a non-production key that would otherwise be destroyed, or to destroy one in an environment the library cannot resolve.

import { RemovalPolicy } from "aws-cdk-lib";

// Overrides the production RETAIN this key would otherwise resolve to.
const ephemeralKey = new CustomerManagedKey(this, "EphemeralKey", {
  protects: "stack-scoped",
  description: "Disposable environment key",
  removalPolicy: RemovalPolicy.DESTROY,
});

Whenever the key resolves to RemovalPolicy.DESTROY, from protects or from an explicit override, the construct sets a 30-day pending window. AWS disables the key immediately, then deletes it after the window elapses. You can cancel the deletion during that window to recover the key and any data it protects. Prefer binding removalPolicy to the policy of the thing being encrypted rather than choosing independently. The CloudTrail construct passes the same storagePolicy to its bucket and its key precisely so the two cannot drift apart.

Outputs

The construct creates two CloudFormation outputs. <Id> below is the construct id run through toPascalCase, which strips the hyphens and underscores CloudFormation rejects in an output key.

Output key	Value	Export name
`<Id>Arn`	`this.key.keyArn`	`${stackName}<Id>KeyArn`
`<Id>AliasArn`	`this.alias.aliasArn`	`${stackName}<Id>KeyAliasArn`

Export names are unique per account per region, so a name built only from a construct id collides between two applications that happen to share the id. Prefixing with the emitting stack’s name makes each export globally unique and puts the application name in it. Build a cross-stack import from the full stack-scoped name:

import { Fn } from "aws-cdk-lib";

// Stack "AcmeApiSecrets", construct id "DataKey"
const keyArn = Fn.importValue("AcmeApiSecretsDataKeyKeyArn");

Common patterns

Database encryption

RDS constructs create their own keys only when you ask for a CMK with the USE_CMK marker. The storage key is created "outlives-stack" (an RDS stack teardown leaves a final snapshot behind) and the performance-insights key "stack-scoped".

import { USE_CMK } from "@fjall/components-infrastructure/lib/utils/databaseTypes";

const database = new RdsAurora(this, "Database", {
  databaseName: "api",
  vpc,
  encryption: { storageKey: USE_CMK },
});

To share one key across resources, create it yourself and pass it in:

const dbKey = new CustomerManagedKey(this, "DatabaseKey", {
  protects: "outlives-stack",
  description: "RDS encryption key",
  aliasName: "alias/rds/api",
});

const database = new RdsAurora(this, "Database", {
  databaseName: "api",
  vpc,
  encryption: { storageKey: dbKey.key },
});

S3 bucket encryption

const bucketKey = new CustomerManagedKey(this, "BucketKey", {
  protects: "outlives-stack",
  description: "S3 bucket encryption key",
  aliasName: "alias/s3/uploads",
});

const bucket = new s3.Bucket(this, "UploadsBucket", {
  encryption: s3.BucketEncryption.KMS,
  encryptionKey: bucketKey.key,
  bucketKeyEnabled: true, // Cuts KMS request charges
});

Secrets Manager integration

The Secret construct creates its own "stack-scoped" key and exposes it as secretsCustomerManagedKey. The property is undefined when the secret was imported with importExisting: true, since an imported secret keeps the key of the stack that owns it.

const secret = new Secret(this, "ApiConfig", {
  secretName: "api-config",
});

const secretKey = secret.secretsCustomerManagedKey?.key;

EBS volume encryption

const volumeKey = new CustomerManagedKey(this, "VolumeKey", {
  protects: "stack-scoped",
  description: "EBS volume encryption",
  aliasName: "alias/ebs/data-volumes",
});

volumeKey.key.grantEncryptDecrypt(new ServicePrincipal("ec2.amazonaws.com"));

Key policies

Default key policy

The default policy grants the account root full access, so IAM policies in the same account govern who can use and administer the key.

Granting access

const key = new CustomerManagedKey(this, "ApiKey", {
  protects: "stack-scoped",
  description: "API encryption key",
});

// Encrypt and decrypt
key.key.grantEncryptDecrypt(apiTaskRole);

// Decrypt only
key.key.grantDecrypt(reportingRole);

// Administer the key
key.key.grantAdmin(adminRole);

// Specific actions
key.key.grant(dashboardRole, "kms:Decrypt", "kms:DescribeKey");

Granting read on an encrypted resource usually carries the KMS permissions with it, so grant on the resource first and reach for key.key.grant* only for principals the resource grant does not cover:

bucket.grantRead(role); // Includes kms:Decrypt on the bucket's key

Cross-account access

const sharedKey = new CustomerManagedKey(this, "SharedKey", {
  protects: "outlives-stack",
  description: "Cross-account shared key",
  aliasName: "alias/shared/data",
});

sharedKey.key.grantEncryptDecrypt(new AccountPrincipal("123456789012"));

Service integration

With Lambda

const lambdaKey = new CustomerManagedKey(this, "LambdaKey", {
  protects: "stack-scoped",
  description: "Lambda environment encryption",
});

const fn = new lambda.Function(this, "ProcessorFunction", {
  environmentEncryption: lambdaKey.key,
  environment: {
    TABLE_NAME: table.tableName,
  },
});

With CloudWatch Logs

const logKey = new CustomerManagedKey(this, "LogKey", {
  protects: "stack-scoped",
  description: "CloudWatch Logs encryption",
  aliasName: "alias/logs/api",
});

const logGroup = new logs.LogGroup(this, "ApiLogs", {
  encryptionKey: logKey.key,
  retention: logs.RetentionDays.ONE_YEAR,
});

Cost considerations

Pricing

Charge	Amount
Key	$1.00 per month
Rotated key versions	$1.00 per month each, capped at the first two
Requests	$0.03 per 10,000

Because rotation is always on, a key that has rotated twice converges on about **

3.00 per month**. Budget for that figure, not for

1.00, when deciding how many keys an application needs.

Cost optimisation

Share one key across resources with the same lifetime and the same audience.

const sharedKey = new CustomerManagedKey(this, "SharedBucketKey", {
  protects: "outlives-stack",
  description: "Shared S3 encryption key",
});

const uploadsBucket = new s3.Bucket(this, "UploadsBucket", {
  encryptionKey: sharedKey.key,
  bucketKeyEnabled: true,
});

const exportsBucket = new s3.Bucket(this, "ExportsBucket", {
  encryptionKey: sharedKey.key,
  bucketKeyEnabled: true,
});

Turn on S3 bucket keys. bucketKeyEnabled: true collapses per-object KMS calls into one call per bucket key, cutting request charges by up to 99%. Cache decrypted values in Lambda outside the handler so a warm invocation skips the KMS call.

let decryptedValue: string | undefined;

export const handler = async () => {
  decryptedValue ??= await decrypt(process.env.SECRET);
  return use(decryptedValue);
};

Complete example

import { CustomerManagedKey } from "@fjall/components-infrastructure/lib/resources/aws/secrets/kms";
import { BackupVault } from "@fjall/components-infrastructure/lib/resources/aws/backup/backupVault";
import { Role, ServicePrincipal } from "aws-cdk-lib/aws-iam";
import { CfnOutput, Tags } from "aws-cdk-lib";

// Survives the stack: the bucket is retained and RDS leaves a final snapshot.
const dataKey = new CustomerManagedKey(this, "DataKey", {
  protects: "outlives-stack",
  description: "Data layer encryption",
  aliasName: `alias/${props.appName}/data`,
});

// Dies with the stack: the secrets it protects die with it too.
const secretsKey = new CustomerManagedKey(this, "SecretsKey", {
  protects: "stack-scoped",
  description: "Secrets Manager encryption",
  aliasName: `alias/${props.appName}/secrets`,
});

const backupKey = new CustomerManagedKey(this, "BackupKey", {
  protects: "outlives-stack",
  description: "Backup encryption key",
  aliasName: `alias/${props.appName}/backups`,
});

const appRole = new Role(this, "AppRole", {
  assumedBy: new ServicePrincipal("ecs-tasks.amazonaws.com"),
});

dataKey.key.grantEncryptDecrypt(appRole);
secretsKey.key.grantDecrypt(appRole);

const dataBucket = new s3.Bucket(this, "DataBucket", {
  encryption: s3.BucketEncryption.KMS,
  encryptionKey: dataKey.key,
  bucketKeyEnabled: true,
});

const appSecret = new secretsmanager.Secret(this, "AppSecret", {
  encryptionKey: secretsKey.key,
});

const vault = new BackupVault(this, "Vault", {
  vaultName: `${props.appName}-vault`,
  encryptionKey: backupKey,
});

for (const cmk of [dataKey, secretsKey, backupKey]) {
  Tags.of(cmk).add("Application", props.appName);
  Tags.of(cmk).add("Purpose", "Encryption");
}

new CfnOutput(this, "DataKeyId", {
  value: dataKey.key.keyId,
  description: "Data KMS key ID",
});

Best practices

Pick protects from the lifetime of the data, not the key. If anything the key encrypts can outlive the stack, pass "outlives-stack".
Separate keys by purpose (data, secrets, logs) so a grant to one audience does not reach another.
Share a key across resources with the same lifetime to keep the per-key charge down.
Use aliases so a rotated or replaced key does not require a config change.
Grant least privilege. grantDecrypt for readers, grantEncryptDecrypt for writers, grantAdmin only for operators.
Monitor key usage with CloudTrail. Every KMS API call is logged.
Tag keys for cost allocation and posture scanning.

Security considerations

Key deletion protection

// "outlives-stack" retains in every environment, production or not.
const key = new CustomerManagedKey(this, "ProtectedKey", {
  protects: "outlives-stack",
  description: "Retained in every environment",
});

// Additional protection: deny scheduled deletion outright.
key.key.addToResourcePolicy(
  new PolicyStatement({
    sid: "PreventDeletion",
    effect: Effect.DENY,
    principals: [new AnyPrincipal()],
    actions: ["kms:ScheduleKeyDeletion"],
    resources: ["*"],
  }),
);

Restricting a key to specific services

Deny every use that does not arrive through the services you expect, so a leaked credential cannot call KMS directly.

hipaaKey.key.addToResourcePolicy(
  new PolicyStatement({
    sid: "DenyOutsideApprovedServices",
    effect: Effect.DENY,
    principals: [new AnyPrincipal()],
    actions: ["kms:*"],
    resources: ["*"],
    conditions: {
      StringNotEquals: {
        "kms:ViaService": [
          `s3.${this.region}.amazonaws.com`,
          `rds.${this.region}.amazonaws.com`,
        ],
      },
    },
  }),
);

Troubleshooting

Symptom	Cause	Fix
`AccessDeniedException`	The caller is missing a grant, or the key policy denies it	Add the grant with `key.key.grant*`, then check the resource policy
`NotFoundException`	Alias missing its `alias/` prefix	The default alias deploys as `alias/cmk/<id>`, not `cmk/<id>`
`No export named …`	Import built from a bare id	Use the stack-scoped name, `${stackName}<Id>KeyArn`
`ThrottlingException`	Per-key request rate exceeded	Turn on `bucketKeyEnabled` for S3, cache decrypted values, back off
Synth throws on removal policy	The target account resolved to no recognised environment	Set the account’s environment in the organisation config, or pass an explicit `removalPolicy`

Inspecting a key

Run AWS commands against a connected account with Fjall-minted credentials. fjall target list shows the available targets.

# Describe the key behind an alias
fjall aws exec --target production-use1 -- \
  aws kms describe-key --key-id alias/cmk/DataKey

# Read the key policy
fjall aws exec --target production-use1 -- \
  aws kms get-key-policy --key-id alias/cmk/DataKey --policy-name default

# Confirm rotation is on
fjall aws exec --target production-use1 -- \
  aws kms get-key-rotation-status --key-id alias/cmk/DataKey

Next Steps

Secrets Manager

Store and rotate secrets encrypted with a customer-managed key.

S3 Bucket

Encrypt object storage at rest with your KMS key.

RDS Aurora

Provision an Aurora cluster with KMS storage and backup encryption.

IAM Role

Grant roles least-privilege encrypt and decrypt permissions.

​Overview

​Resource class

​Basic usage

​Configuration options

​Choosing protects

​Default features

​Key components

​The KMS key

​The key alias

​Key rotation

​Removal policy

​Outputs

​Common patterns

​Database encryption

​S3 bucket encryption

​Secrets Manager integration

​EBS volume encryption

​Key policies

​Default key policy

​Granting access

​Cross-account access

​Service integration

​With Lambda

​With CloudWatch Logs

​Cost considerations

​Pricing

​Cost optimisation

​Complete example

​Best practices

​Security considerations

​Key deletion protection

​Restricting a key to specific services

​Troubleshooting

​Inspecting a key

​Next Steps

Secrets Manager

S3 Bucket

RDS Aurora

IAM Role

Overview

Resource class

Basic usage

Configuration options

Choosing `protects`

Default features

Key components

The KMS key

The key alias

Key rotation

Removal policy

Outputs

Common patterns

Database encryption

S3 bucket encryption

Secrets Manager integration

EBS volume encryption

Key policies

Default key policy

Granting access

Cross-account access

Service integration

With Lambda

With CloudWatch Logs

Cost considerations

Pricing

Cost optimisation

Complete example

Best practices

Security considerations

Key deletion protection

Restricting a key to specific services

Troubleshooting

Inspecting a key

Next Steps