feat(core): support Docker asset build secrets

packages/@aws-cdk/aws-ecr-assets/lib/image-asset.ts

@@ -98,6 +98,13 @@ export interface DockerImageAssetInvalidationOptions {
    */
   readonly buildArgs?: boolean;
 
+  /**
+   * Use `buildSecrets` while calculating the asset hash
+   *
+   * @default true
+   */
+  readonly buildSecrets?: boolean;
+
   /**
    * Use `target` while calculating the asset hash
    *
@@ -163,6 +170,15 @@ export interface DockerImageAssetOptions extends FingerprintOptions, FileFingerp
    */
   readonly buildArgs?: { [key: string]: string };
 
+  /**
+   * Build secrets to pass to the `docker build` command.
+   *
+   * Docker BuildKit must be enabled.
+   *
+   * @default - no build secrets are passed
+   */
+  readonly buildSecrets?: { [key: string]: string };
+
   /**
    * Docker target to build to
    *
@@ -267,6 +283,11 @@ export class DockerImageAsset extends Construct implements IAsset {
    */
   private readonly dockerBuildArgs?: { [key: string]: string };
 
+  /**
+   * Build secrets to pass to the `docker build` command.
+   */
+  private readonly dockerBuildSecrets?: { [key: string]: string };
+
   /**
    * Docker target to build to
    */
@@ -325,6 +346,7 @@ export class DockerImageAsset extends Construct implements IAsset {
     const extraHash: { [field: string]: any } = {};
     if (props.invalidation?.extraHash !== false && props.extraHash) { extraHash.user = props.extraHash; }
     if (props.invalidation?.buildArgs !== false && props.buildArgs) { extraHash.buildArgs = props.buildArgs; }
+    if (props.invalidation?.buildSecrets !== false && props.buildSecrets) { extraHash.buildSecrets = props.buildSecrets; }
     if (props.invalidation?.target !== false && props.target) { extraHash.target = props.target; }
     if (props.invalidation?.file !== false && props.file) { extraHash.file = props.file; }
     if (props.invalidation?.repositoryName !== false && props.repositoryName) { extraHash.repositoryName = props.repositoryName; }
@@ -353,11 +375,13 @@ export class DockerImageAsset extends Construct implements IAsset {
     const stack = Stack.of(this);
     this.assetPath = staging.relativeStagedPath(stack);
     this.dockerBuildArgs = props.buildArgs;
+    this.dockerBuildSecrets = props.buildSecrets;
     this.dockerBuildTarget = props.target;
 
     const location = stack.synthesizer.addDockerImageAsset({
       directoryName: this.assetPath,
       dockerBuildArgs: this.dockerBuildArgs,
+      dockerBuildSecrets: this.dockerBuildSecrets,
       dockerBuildTarget: this.dockerBuildTarget,
       dockerFile: props.file,
       sourceHash: staging.assetHash,
@@ -411,6 +435,7 @@ function validateProps(props: DockerImageAssetProps) {
   }
 
   validateBuildArgs(props.buildArgs);
+  validateBuildSecrets(props.buildSecrets);
 }
 
 function validateBuildArgs(buildArgs?: { [key: string]: string }) {
@@ -421,6 +446,14 @@ function validateBuildArgs(buildArgs?: { [key: string]: string }) {
   }
 }
 
+function validateBuildSecrets(buildSecrets?: { [key: string]: string }) {
+  for (const [key, value] of Object.entries(buildSecrets || {})) {
+    if (Token.isUnresolved(key) || Token.isUnresolved(value)) {
+      throw new Error('Cannot use tokens in keys or values of "buildSecrets" since they are needed before deployment');
+    }
+  }
+}
+
 function toSymlinkFollow(follow?: FollowMode): SymlinkFollowMode | undefined {
   switch (follow) {
     case undefined: return undefined;

packages/@aws-cdk/aws-ecr-assets/test/image-asset.test.ts

@@ -125,6 +125,24 @@ describe('image asset', () => {
     })).toThrow(expected);
   });
 
+  test('fails if using tokens in build secrets keys or values', () => {
+    // GIVEN
+    const stack = new Stack();
+    const token = Lazy.string({ produce: () => 'foo' });
+    const expected = /Cannot use tokens in keys or values of "buildSecrets" since they are needed before deployment/;
+
+    // THEN
+    expect(() => new DockerImageAsset(stack, 'MyAsset1', {
+      directory: path.join(__dirname, 'demo-image'),
+      buildSecrets: { [token]: 'value' },
+    })).toThrow(expected);
+
+    expect(() => new DockerImageAsset(stack, 'MyAsset2', {
+      directory: path.join(__dirname, 'demo-image'),
+      buildSecrets: { key: token },
+    })).toThrow(expected);
+  });
+
   testDeprecated('fails if using token as repositoryName', () => {
     // GIVEN
     const stack = new Stack();
@@ -149,13 +167,15 @@ describe('image asset', () => {
     const asset4 = new DockerImageAsset(stack, 'Asset4', { directory, buildArgs: { opt1: '123', opt2: 'boom' } });
     const asset5 = new DockerImageAsset(stack, 'Asset5', { directory, file: 'Dockerfile.Custom', target: 'NonDefaultTarget' });
     const asset6 = new DockerImageAsset(stack, 'Asset6', { directory, extraHash: 'random-extra' });
+    const asset7 = new DockerImageAsset(stack, 'Asset7', { directory, buildSecrets: { a: 'b' } });
 
     expect(asset1.assetHash).toEqual('13248c55633f3b198a628bb2ea4663cb5226f8b2801051bd0c725950266fd590');
     expect(asset2.assetHash).toEqual('36bf205fb9adc5e45ba1c8d534158a0aed96d190eff433af1d90f3b94f96e751');
     expect(asset3.assetHash).toEqual('4c85bd70e73117b7129c2defbe6dc40a8a3872329f4ddca18d75afa671b38276');
     expect(asset4.assetHash).toEqual('8a91219a7bb0f58b3282dd84acbf4c03c49c765be54ffb7b125be6a50b6c5645');
     expect(asset5.assetHash).toEqual('c02bfba13b2e7e1ff5c778a76e10296b9e8d17f7f8252d097f4170ae04ce0eb4');
     expect(asset6.assetHash).toEqual('3528d6838647a5e9011b0f35aec514d03ad11af05a94653cdcf4dacdbb070a06');
+    expect(asset7.assetHash).toEqual('adef40a1e694f03f8b45807d6061af13fa75d08442d4370a6619afb09d0ef254');
 
   });
 

packages/@aws-cdk/cloud-assembly-schema/lib/assets/docker-image-asset.ts

@@ -63,6 +63,15 @@ export interface DockerImageSource {
    */
   readonly dockerBuildArgs?: { [name: string]: string };
 
+  /**
+   * Additional build secrets
+   *
+   * Requires BuildKit to be enabled.
+   *
+   * @default - No additional build secrets
+   */
+  readonly dockerBuildSecrets?: { [name: string]: string };
+
   /**
    * Networking mode for the RUN commands during build. _Requires Docker Engine API v1.25+_.
    *

packages/@aws-cdk/cloud-assembly-schema/lib/cloud-assembly/metadata-schema.ts

@@ -118,6 +118,15 @@ export interface ContainerImageAssetMetadataEntry extends BaseAssetMetadataEntry
    */
   readonly buildArgs?: { [key: string]: string };
 
+  /**
+   * Build secrets to pass to the `docker build` command
+   *
+   * Docker BuildKit must be enabled.
+   *
+   * @default no build secrets are passed
+   */
+  readonly buildSecrets?: { [key: string]: string };
+
   /**
    * Docker target to build to
    *

packages/@aws-cdk/cloud-assembly-schema/schema/assets.schema.json

@@ -155,6 +155,13 @@
                         "type": "string"
                     }
                 },
+                "dockerBuildSecrets": {
+                    "description": "Additional build secrets\n\nRequires BuildKit to be enabled. (Default - No additional build secrets)",
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                },
                 "networkMode": {
                     "description": "Networking mode for the RUN commands during build. _Requires Docker Engine API v1.25+_.\n\nSpecify this property to build images on a specific networking mode. (Default - no networking mode specified)",
                     "type": "string"

packages/@aws-cdk/cloud-assembly-schema/schema/cloud-assembly.schema.json

@@ -218,6 +218,13 @@
                         "type": "string"
                     }
                 },
+                "buildSecrets": {
+                    "description": "Build secrets to pass to the `docker build` command\n\nDocker BuildKit must be enabled. (Default no build secrets are passed)",
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                },
                 "target": {
                     "description": "Docker target to build to (Default no build target)",
                     "type": "string"

packages/@aws-cdk/cloud-assembly-schema/schema/cloud-assembly.version.json

@@ -1 +1 @@
-{"version":"22.0.0"}
+{"version":"23.0.0"}

packages/@aws-cdk/core/lib/assets.ts

@@ -174,6 +174,15 @@ export interface DockerImageAssetSource {
    */
   readonly dockerBuildArgs?: { [key: string]: string };
 
+  /**
+   * Build secrets to pass to the `docker build` command.
+   *
+   * Docker BuildKit must be enabled
+   *
+   * @default - no build secrets are passed
+   */
+  readonly dockerBuildSecrets?: { [key: string]: string };
+
   /**
    * Docker target to build to
    *

packages/@aws-cdk/core/lib/bundling.ts

@@ -277,6 +277,7 @@ export class DockerImage extends BundlingDockerImage {
    */
   public static fromBuild(path: string, options: DockerBuildOptions = {}) {
     const buildArgs = options.buildArgs || {};
+    const buildSecrets = options.buildSecrets || {};
 
     if (options.file && isAbsolute(options.file)) {
       throw new Error(`"file" must be relative to the docker build directory. Got ${options.file}`);
@@ -293,6 +294,7 @@ export class DockerImage extends BundlingDockerImage {
       ...(options.platform ? ['--platform', options.platform] : []),
       ...(options.targetStage ? ['--target', options.targetStage] : []),
       ...flatten(Object.entries(buildArgs).map(([k, v]) => ['--build-arg', `${k}=${v}`])),
+      ...flatten(Object.entries(buildSecrets).map(([k, v]) => ['--secret', `id=${k},src=${v}`])),
       path,
     ];
 
@@ -506,6 +508,13 @@ export interface DockerBuildOptions {
    */
   readonly buildArgs?: { [key: string]: string };
 
+  /**
+   * Build secrets
+   *
+   * @default - no build secrets
+   */
+  readonly buildSecrets?: { [key: string]: string };
+
   /**
    * Name of the Dockerfile, must relative to the docker build path.
    *

packages/@aws-cdk/core/lib/stack-synthesizers/legacy.ts

@@ -130,6 +130,7 @@ export class LegacyStackSynthesizer extends StackSynthesizer {
         path: asset.directoryName,
         sourceHash: asset.sourceHash,
         buildArgs: asset.dockerBuildArgs,
+        buildSecrets: asset.dockerBuildSecrets,
         target: asset.dockerBuildTarget,
         file: asset.dockerFile,
         networkMode: asset.networkMode,

packages/@aws-cdk/core/test/bundling.test.ts

@@ -63,6 +63,9 @@ describe('bundling', () => {
       buildArgs: {
         TEST_ARG: 'cdk-test',
       },
+      buildSecrets: {
+        a: 'b',
+      },
     });
     image.run();
 
@@ -71,12 +74,16 @@ describe('bundling', () => {
       buildArgs: {
         TEST_ARG: 'cdk-test',
       },
+      buildSecrets: {
+        a: 'b',
+      },
     })).digest('hex');
     const tag = `cdk-${tagHash}`;
 
     expect(spawnSyncStub.firstCall.calledWith('docker', [
       'build', '-t', tag,
       '--build-arg', 'TEST_ARG=cdk-test',
+      '--secret', 'id=a,src=b',
       'docker-path',
     ])).toEqual(true);
 

packages/aws-cdk/lib/assets.ts

@@ -120,6 +120,7 @@ async function prepareDockerImageAsset(
   assetManifest.addDockerImageAsset(asset.sourceHash, {
     directory: asset.path,
     dockerBuildArgs: asset.buildArgs,
+    dockerBuildSecrets: asset.buildSecrets,
     dockerBuildTarget: asset.target,
     dockerFile: asset.file,
     networkMode: asset.networkMode,

packages/cdk-assets/lib/private/docker.ts

@@ -15,6 +15,7 @@ interface BuildOptions {
   readonly target?: string;
   readonly file?: string;
   readonly buildArgs?: Record<string, string>;
+  readonly buildSecrets?: Record<string, string>;
   readonly networkMode?: string;
   readonly platform?: string;
 }
@@ -53,6 +54,7 @@ export class Docker {
     const buildCommand = [
       'build',
       ...flatten(Object.entries(options.buildArgs || {}).map(([k, v]) => ['--build-arg', `${k}=${v}`])),
+      ...flatten(Object.entries(options.buildSecrets || {}).map(([k, v]) => ['--secret', `id=${k},src=${v}`])),
       '--tag', options.tag,
       ...options.target ? ['--target', options.target] : [],
       ...options.file ? ['--file', options.file] : [],

packages/cdk-assets/lib/private/handlers/container-images.ts

@@ -167,6 +167,7 @@ class ContainerImageBuilder {
       directory: fullPath,
       tag: localTagName,
       buildArgs: source.dockerBuildArgs,
+      buildSecrets: source.dockerBuildSecrets,
       target: source.dockerBuildTarget,
       file: source.dockerFile,
       networkMode: source.networkMode,