(aws-synthetics): support customer-managed KMS key for canary environment variable encryption

[shukrash]

Describe the feature

AWS::Synthetics::Canary exposes a top-level KmsKeyArn property that encrypts the
canary's Lambda function environment variables at rest with a customer-managed KMS key.
The Canary L2 construct currently provides no way to set it — users must drop down to
the L1 CfnCanary or use escape hatches.

This is distinct from the existing artifactS3KmsKey prop, which encrypts canary
artifacts in S3 (ArtifactConfig.S3Encryption.KmsKeyArn), not the environment variables.

Use Case

Teams with compliance requirements to use customer-managed keys (CMKs) for all
data-at-rest need to encrypt canary environment variables (which can hold configuration
and sensitive values) with their own KMS key rather than the default AWS-managed key.

Proposed Solution

Add an optional environmentVariablesEncryptionKey?: kms.IKey prop to CanaryProps,
wire it to CfnCanary.kmsKeyArn, and grant the canary execution role kms:Decrypt on
the key so the underlying Lambda can read its environment variables.

Other Information

Follow-up: AWS::Synthetics::Canary also has a per-replica Replicas[].KmsKeyArn for
the multi-location canary feature. That will be addressed in a separate PR once the L2
models Replicas.

A PR implementing the top-level property is already open.

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

AWS CDK Library version (aws-cdk-lib)

2.268.0

AWS CDK CLI version

2.1140.0

Environment details (OS name and version, etc.)

OS: Amazon Linux 2023 (2023.7.20250623) Kernel: Linux 6.1.182-227.379.amzn2023.x86_64 Architecture: x86_64 Node.js: v24.18.0

[pahud]

This is a good catch. I reproduced the API gap on macOS with aws-cdk-lib@2.269.0: environmentVariablesEncryptionKey fails compilation because it is not part of CanaryProps.

For an immediate workaround, both the L1 property and permission grant are required:

const cfnCanary = canary.node.defaultChild as synthetics.CfnCanary;
cfnCanary.kmsKeyArn = key.keyArn;
key.grantDecrypt(canary.role);

I verified this workaround with cdk synth: top-level KmsKeyArn references the key ARN, and the canary role receives kms:Decrypt on the same key.

Current CanaryProps exposes the separate S3 artifact key but not an environment-variable key, and the Canary constructor does not map top-level kmsKeyArn:

aws-cdk/packages/aws-cdk-lib/aws-synthetics/lib/canary.ts

Lines 319 to 353 in a9e36a3

	*/
	readonly artifactsBucketLifecycleRules?: Array<s3.LifecycleRule>;
	/**
	* Canary Artifacts in S3 encryption mode.
	* Artifact encryption is only supported for canaries that use Synthetics runtime
	* version `syn-nodejs-puppeteer-3.3` or later.
	*
	* @default - Artifacts are encrypted at rest using an AWS managed key. `ArtifactsEncryptionMode.KMS` is set if you specify `artifactS3KmsKey`.
	*
	* @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_artifact_encryption.html
	*/
	readonly artifactS3EncryptionMode?: ArtifactsEncryptionMode;
	/**
	* The KMS key used to encrypt canary artifacts.
	*
	* @default - no kms key if `artifactS3EncryptionMode` is set to `S3_MANAGED`. A key will be created if one is not provided and `artifactS3EncryptionMode` is set to `KMS`.
	*/
	readonly artifactS3KmsKey?: kms.IKey;
	/**
	* Specifies whether to perform a dry run before updating the canary.
	*
	* If set to true, CDK will execute a dry run to validate the changes before applying them to the canary.
	* If the dry run succeeds, the canary will be updated with the changes.
	* If the dry run fails, the CloudFormation deployment will fail with the dry run's failure reason.
	*
	* If set to false or omitted, the canary will be updated directly without first performing a dry run.
	*
	* @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/performing-safe-canary-upgrades.html
	*
	* @default undefined - AWS CloudWatch default is false
	*/
	readonly dryRunAndUpdate?: boolean;

aws-cdk/packages/aws-cdk-lib/aws-synthetics/lib/canary.ts

Lines 558 to 598 in a9e36a3

	if (props.vpc) {
	// Security Groups are created and/or appended in `createVpcConfig`.
	this._connections = new ec2.Connections({});
	}
	this.validateDryRunAndUpdate(props.runtime, props.dryRunAndUpdate);
	this.validateBrowserConfigs(props.runtime, props.browserConfigs);
	const resource: CfnCanary = new CfnCanary(this, 'Resource', {
	artifactS3Location: this.artifactsBucket.s3UrlForObject(props.artifactsBucketLocation?.prefix),
	executionRoleArn: this.role.roleArn,
	startCanaryAfterCreation: props.startAfterCreation ?? true,
	runtimeVersion: props.runtime.name,
	name: this.physicalName,
	schedule: this.createSchedule(props),
	failureRetentionPeriod: props.failureRetentionPeriod?.toDays(),
	successRetentionPeriod: props.successRetentionPeriod?.toDays(),
	code: this.createCode(props),
	runConfig: this.createRunConfig(props),
	vpcConfig: this.createVpcConfig(props),
	artifactConfig: this.createArtifactConfig(props),
	provisionedResourceCleanup: props.provisionedResourceCleanup !== undefined
	? props.provisionedResourceCleanup
	? 'AUTOMATIC'
	: 'OFF'
	: undefined,
	dryRunAndUpdate: props.dryRunAndUpdate,
	browserConfigs: props.browserConfigs?.map(browserType => ({
	browserType,
	})),
	resourcesToReplicateTags: props.resourcesToReplicateTags,
	});
	this._resource = resource;
	if (props.resourcesToReplicateTags?.length === 0) {
	// Silence a CloudFormation-Validate warning that it would emit about an empty array here
	cdk.Validations.of(resource).acknowledge({
	id: 'CloudFormation-Validate::F3032',
	reason: 'An empty list of resources to replicate tags is historically supported by this construct.',
	});
	}

The approach in PR #38750 looks appropriate: it accepts an IKey, maps keyArn, and grants decrypt to the execution role.

aws-cdk/packages/aws-cdk-lib/aws-synthetics/lib/canary.ts

Lines 319 to 349 in 55a6ba2

	*/
	readonly artifactsBucketLifecycleRules?: Array<s3.LifecycleRule>;
	/**
	* Canary Artifacts in S3 encryption mode.
	* Artifact encryption is only supported for canaries that use Synthetics runtime
	* version `syn-nodejs-puppeteer-3.3` or later.
	*
	* @default - Artifacts are encrypted at rest using an AWS managed key. `ArtifactsEncryptionMode.KMS` is set if you specify `artifactS3KmsKey`.
	*
	* @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_artifact_encryption.html
	*/
	readonly artifactS3EncryptionMode?: ArtifactsEncryptionMode;
	/**
	* The KMS key used to encrypt canary artifacts.
	*
	* @default - no kms key if `artifactS3EncryptionMode` is set to `S3_MANAGED`. A key will be created if one is not provided and `artifactS3EncryptionMode` is set to `KMS`.
	*/
	readonly artifactS3KmsKey?: kms.IKey;
	/**
	* The customer-managed KMS key used to encrypt the canary's Lambda function
	* environment variables at rest.
	*
	* The canary's execution role is granted permission to decrypt using this key
	* so that the underlying Lambda function can read its environment variables.
	*
	* @default - Lambda uses an AWS managed key to encrypt the environment variables at rest.
	*/
	readonly environmentVariablesEncryptionKey?: kms.IKey;

aws-cdk/packages/aws-cdk-lib/aws-synthetics/lib/canary.ts

Lines 577 to 607 in 55a6ba2

	const resource: CfnCanary = new CfnCanary(this, 'Resource', {
	artifactS3Location: this.artifactsBucket.s3UrlForObject(props.artifactsBucketLocation?.prefix),
	executionRoleArn: this.role.roleArn,
	startCanaryAfterCreation: props.startAfterCreation ?? true,
	runtimeVersion: props.runtime.name,
	name: this.physicalName,
	schedule: this.createSchedule(props),
	failureRetentionPeriod: props.failureRetentionPeriod?.toDays(),
	successRetentionPeriod: props.successRetentionPeriod?.toDays(),
	code: this.createCode(props),
	runConfig: this.createRunConfig(props),
	vpcConfig: this.createVpcConfig(props),
	artifactConfig: this.createArtifactConfig(props),
	provisionedResourceCleanup: props.provisionedResourceCleanup !== undefined
	? props.provisionedResourceCleanup
	? 'AUTOMATIC'
	: 'OFF'
	: undefined,
	dryRunAndUpdate: props.dryRunAndUpdate,
	browserConfigs: props.browserConfigs?.map(browserType => ({
	browserType,
	})),
	resourcesToReplicateTags: props.resourcesToReplicateTags,
	kmsKeyArn: props.environmentVariablesEncryptionKey?.keyArn,
	});
	this._resource = resource;
	// The canary's execution role is used by the underlying Lambda function to
	// decrypt its environment variables. Grant decrypt permissions on the
	// customer-managed key so the function can start successfully.
	props.environmentVariablesEncryptionKey?.grantDecrypt(this.role);

A property mixin alone would be incomplete here because it would not model the IKey or add the required IAM grant. From my view, this fits p2; the existing feature-request and @aws-cdk/aws-synthetics labels are correct. PR #38750 is open and mergeable, but behind main and awaiting maintainer/further review. Thanks for putting together the contribution and tests; updating the branch and following it through review and CI should be the next step.

[pahud]

Until Canary exposes this as an L2 prop, the CDK Mixins mechanism (GA in aws-cdk-lib) gives a clean, reusable way to set KmsKeyArn today — the property already exists on the L1 CfnCanary.

Verified with aws-cdk-lib@2.270.0 (compiles under strict TS, synthesizes, and the property appears on the AWS::Synthetics::Canary resource):

import { Mixin, Mixins } from 'aws-cdk-lib';
import { IConstruct } from 'constructs';
import * as synthetics from 'aws-cdk-lib/aws-synthetics';
import * as kms from 'aws-cdk-lib/aws-kms';

class CanaryEncryptionKey extends Mixin {
  constructor(private readonly key: kms.IKey) {
    super();
  }
  supports(construct: IConstruct): boolean {
    return synthetics.CfnCanary.isCfnCanary(construct);
  }
  applyTo(construct: IConstruct): void {
    if (!this.supports(construct)) return;
    (construct as synthetics.CfnCanary).kmsKeyArn = this.key.keyArn;
  }
}

const key = new kms.Key(this, 'CanaryKey');
const canary = new synthetics.Canary(this, 'Canary', {
  runtime: synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_9_1,
  test: synthetics.Test.custom({
    code: synthetics.Code.fromInline('exports.handler = async () => {};'),
    handler: 'index.handler',
  }),
});

Mixins.of(canary).requireAny().apply(new CanaryEncryptionKey(key));

Synthesized output on the canary:

"KmsKeyArn": { "Fn::GetAtt": ["CanaryKey53D2D0D1", "Arn"] }

Note the mixin only sets the property — you still need to grant the canary's execution role kms:Decrypt/kms:GenerateDataKey on the key (key.grantEncryptDecrypt(canary.role)), which is also the part a proper L2 prop should automate. That, plus applying it fleet-wide via Mixins.of(stack), is where the L2 integration would add real value over the workaround.

Let me know if it works for you.

[github-actions]

This issue has not received a response in a while. If you want to keep this issue open, please leave a comment below and auto-close will be canceled.

[github-actions]

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.