fix(toolkit-lib): make default environment resolution optional (#689)

This PR makes the default environment resolution optional in the
toolkit-lib. It allows avoiding unnecessary STS calls when the
environment is explicitly specified or when local actions are performed
without internet access.

Then uses the new feature in `integ-runner` to disable the default env
lookup in the toolkit-lib engine. The existing engine doesn't provide
the env variables either, so it's clearly not needed. We don't want to
add to this contract at this time and also resolving the account adds an
unnecessary delay.

---
By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache-2.0 license

Co-authored-by: Rico Hermans <rix0rrr@gmail.com>

Author: mrgrain

packages/@aws-cdk/integ-runner/lib/engines/toolkit-lib.ts

@@ -84,6 +84,7 @@ export class ToolkitLibRunnerEngine implements ICdk {
       outdir: options.output ? path.join(this.options.workingDirectory, options.output) : undefined,
       contextStore: new MemoryContext(options.context),
       lookups: false,
+      resolveDefaultEnvironment: false,
       env: {
         ...this.options.env,
         ...options.env,
@@ -209,6 +210,7 @@ export class ToolkitLibRunnerEngine implements ICdk {
       workingDirectory: this.options.workingDirectory,
       outdir,
       lookups: options.lookups,
+      resolveDefaultEnvironment: false, // not part of the integ-runner contract
       contextStore: new MemoryContext(options.context),
       env: this.options.env,
       synthOptions: {

packages/@aws-cdk/integ-runner/test/engines/toolkit-lib.test.ts

@@ -73,6 +73,7 @@ describe('ToolkitLibRunnerEngine', () => {
         contextStore: expect.any(Object),
         lookups: false,
         env: { TEST: 'true' },
+        resolveDefaultEnvironment: false,
         synthOptions: {
           versionReporting: false,
           pathMetadata: false,

packages/@aws-cdk/toolkit-lib/lib/api/cloud-assembly/private/prepare-source.ts

@@ -20,6 +20,22 @@ import type { Context, Env } from '../environment';
 import { prepareDefaultEnvironment, spaceAvailableForContext, guessExecutable, synthParametersFromSettings } from '../environment';
 import type { AppSynthOptions, LoadAssemblyOptions } from '../source-builder';
 
+export interface ExecutionEnvironmentOptions {
+  /**
+   * The directory the cloud assembly will be written to.
+   *
+   * @default - use a temporary directory as output directory, this will be cleaned up when this object is disposed
+   */
+  readonly outdir?: string;
+
+  /**
+   * Resolve and add environment variables for the app's default environment.
+   *
+   * This will make a call to STS, which is not always desirable e.g. if the env is explicitly specified.
+   */
+  readonly resolveDefaultAppEnv: boolean;
+}
+
 export class ExecutionEnvironment implements AsyncDisposable {
   /**
    * Create an ExecutionEnvironment
@@ -33,18 +49,39 @@ export class ExecutionEnvironment implements AsyncDisposable {
    * If `markSuccessful()` is called, the writer lock is converted to a reader lock
    * and temporary directories will not be cleaned up anymore.
    */
-  public static async create(services: ToolkitServices, props: { outdir?: string } = {}) {
-    let tempDir = false;
-    let dir = props.outdir;
+  public static async create(services: ToolkitServices, options: ExecutionEnvironmentOptions) {
+    let outDirIsTemporary = false;
+    let dir = options.outdir;
     if (!dir) {
-      tempDir = true;
+      outDirIsTemporary = true;
       dir = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), 'cdk.out'));
     }
-
     const lock = await new RWLock(dir).acquireWrite();
-    return new ExecutionEnvironment(services, dir, tempDir, lock);
+
+    const opts = {
+      outdir: dir,
+      resolveDefaultAppEnv: options.resolveDefaultAppEnv,
+    };
+
+    return new ExecutionEnvironment(services, opts, {
+      lock,
+      outDirIsTemporary,
+    });
+  }
+
+  /**
+   * Should the outdir be disposed of.
+   */
+  public get shouldDisposeOutDir(): boolean {
+    return this.shouldClean;
   }
 
+  /**
+   * The directory the cloud assembly will be written to.
+   */
+  public readonly outdir: string;
+
+  private readonly options: Required<ExecutionEnvironmentOptions>;
   private readonly ioHelper: IoHelper;
   private readonly sdkProvider: SdkProvider;
   private readonly debugFn: (msg: string) => Promise<void>;
@@ -53,21 +90,25 @@ export class ExecutionEnvironment implements AsyncDisposable {
 
   private constructor(
     services: ToolkitServices,
-    public readonly outdir: string,
-    public readonly outDirIsTemporary: boolean,
-    lock: IWriteLock,
+    options: Required<ExecutionEnvironmentOptions>,
+    { lock, outDirIsTemporary }: {
+      readonly outDirIsTemporary: boolean;
+      readonly lock: IWriteLock;
+    },
   ) {
     this.ioHelper = services.ioHelper;
     this.sdkProvider = services.sdkProvider;
     this.debugFn = (msg: string) => this.ioHelper.defaults.debug(msg);
     this.lock = lock;
     this.shouldClean = outDirIsTemporary;
+    this.outdir = options.outdir;
+    this.options = options;
   }
 
   public async [Symbol.asyncDispose]() {
     await this.lock?.release();
 
-    if (this.shouldClean) {
+    if (this.shouldDisposeOutDir) {
       await fs.rm(this.outdir, { recursive: true, force: true });
     }
   }
@@ -136,7 +177,7 @@ export class ExecutionEnvironment implements AsyncDisposable {
    */
   public async defaultEnvVars(): Promise<Env> {
     const debugFn = (msg: string) => this.ioHelper.notify(IO.CDK_ASSEMBLY_I0010.msg(msg));
-    const env = await prepareDefaultEnvironment(this.sdkProvider, debugFn);
+    const env = this.options.resolveDefaultAppEnv ? await prepareDefaultEnvironment(this.sdkProvider, debugFn) : {};
 
     env[cxapi.OUTDIR_ENV] = this.outdir;
     await debugFn(format('outdir:', this.outdir));

packages/@aws-cdk/toolkit-lib/lib/api/cloud-assembly/source-builder.ts

@@ -118,6 +118,18 @@ export interface AssemblySourceProps {
    * @default - `true` if `outdir` is not given, `false` otherwise
    */
   readonly disposeOutdir?: boolean;
+
+  /**
+   * Resolve the current default environment an provide as environment variables to the app.
+   *
+   * This will make a (cached) call to STS to resolve the current account using
+   * base credentials. The behavior is not always desirable and can add
+   * unnecessary delays, e.g. when an app specifies an environment explicitly
+   * or when local actions are be performed without internet access.
+   *
+   * @default true
+   */
+  readonly resolveDefaultEnvironment?: boolean;
 }
 
 /**
@@ -324,7 +336,10 @@ export abstract class CloudAssemblySourceBuilder {
     return new ContextAwareCloudAssemblySource(
       {
         produce: async () => {
-          await using execution = await ExecutionEnvironment.create(services, { outdir });
+          await using execution = await ExecutionEnvironment.create(services, {
+            outdir,
+            resolveDefaultAppEnv: props.resolveDefaultEnvironment ?? true,
+          });
 
           const synthParams = parametersFromSynthOptions(props.synthOptions);
 
@@ -368,7 +383,7 @@ export abstract class CloudAssemblySourceBuilder {
             : await assemblyFromDirectory(assembly.directory, services.ioHelper, props.loadAssemblyOptions);
 
           const success = await execution.markSuccessful();
-          const deleteOnDispose = props.disposeOutdir ?? execution.outDirIsTemporary;
+          const deleteOnDispose = props.disposeOutdir ?? execution.shouldDisposeOutDir;
           return new ReadableCloudAssembly(asm, success.readLock, { deleteOnDispose });
         },
       },
@@ -462,19 +477,16 @@ export abstract class CloudAssemblySourceBuilder {
     return new ContextAwareCloudAssemblySource(
       {
         produce: async () => {
-          // @todo build
-          // const build = this.props.configuration.settings.get(['build']);
-          // if (build) {
-          //   await execInChildProcess(build, { cwd: props.workingDirectory });
-          // }
-
           try {
             fs.mkdirpSync(outdir);
           } catch (e: any) {
             throw new ToolkitError(`Could not create output directory at '${outdir}' (${e.message}).`);
           }
 
-          await using execution = await ExecutionEnvironment.create(services, { outdir });
+          await using execution = await ExecutionEnvironment.create(services, {
+            outdir,
+            resolveDefaultAppEnv: props.resolveDefaultEnvironment ?? true,
+          });
 
           const commandLine = await execution.guessExecutable(app);
 
@@ -521,7 +533,7 @@ export abstract class CloudAssemblySourceBuilder {
           const asm = await assemblyFromDirectory(outdir, services.ioHelper, props.loadAssemblyOptions);
 
           const success = await execution.markSuccessful();
-          const deleteOnDispose = props.disposeOutdir ?? execution.outDirIsTemporary;
+          const deleteOnDispose = props.disposeOutdir ?? execution.shouldDisposeOutDir;
           return new ReadableCloudAssembly(asm, success.readLock, { deleteOnDispose });
         },
       },

packages/@aws-cdk/toolkit-lib/test/api/cloud-assembly/source-builder.test.ts

@@ -2,6 +2,7 @@ import * as path from 'path';
 import { App } from 'aws-cdk-lib/core';
 import * as fs from 'fs-extra';
 import { MemoryContext } from '../../../lib';
+import * as environment from '../../../lib/api/cloud-assembly/environment';
 import { RWLock } from '../../../lib/api/rwlock';
 import * as contextproviders from '../../../lib/context-providers';
 import { Toolkit } from '../../../lib/toolkit/toolkit';
@@ -157,6 +158,39 @@ describe('fromAssemblyBuilder', () => {
     expect(await (lock! as any)._currentWriter()).toBeUndefined();
     expect(await (lock! as any)._currentReaders()).toEqual([]);
   });
+
+  describe('resolveDefaultEnvironment', () => {
+    let prepareDefaultEnvironmentSpy: jest.SpyInstance;
+    beforeEach(() => {
+      // Mock the prepareDefaultEnvironment function to avoid actual STS calls
+      prepareDefaultEnvironmentSpy = jest.spyOn(environment, 'prepareDefaultEnvironment')
+        .mockImplementation(async () => {
+          return {
+            CDK_DEFAULT_ACCOUNT: '123456789012',
+            CDK_DEFAULT_REGION: 'us-east-1',
+          };
+        });
+    });
+
+    afterEach(() => {
+      prepareDefaultEnvironmentSpy.mockRestore();
+    });
+
+    test.each([[true, 1], [false, 0], [undefined, 1]])('respects resolveDefaultEnvironment=%s', async (resolveDefaultEnvironment, callCount) => {
+      // WHEN
+      const cx = await toolkit.fromAssemblyBuilder(async () => {
+        const app = new App();
+        return app.synth();
+      }, {
+        resolveDefaultEnvironment,
+      });
+
+      await using _ = await cx.produce();
+
+      // THEN
+      expect(prepareDefaultEnvironmentSpy).toHaveBeenCalledTimes(callCount);
+    });
+  });
 });
 
 describe('fromCdkApp', () => {
@@ -290,6 +324,45 @@ describe('fromCdkApp', () => {
     expect(await (lock! as any)._currentWriter()).toBeUndefined();
     expect(await (lock! as any)._currentReaders()).toEqual([]);
   });
+
+  describe('resolveDefaultEnvironment', () => {
+    let prepareDefaultEnvironmentSpy: jest.SpyInstance;
+    beforeEach(() => {
+      // Mock the prepareDefaultEnvironment function to avoid actual STS calls
+      prepareDefaultEnvironmentSpy = jest.spyOn(environment, 'prepareDefaultEnvironment')
+        .mockImplementation(async () => {
+          return {
+            CDK_DEFAULT_ACCOUNT: '123456789012',
+            CDK_DEFAULT_REGION: 'us-east-1',
+          };
+        });
+    });
+
+    afterEach(() => {
+      prepareDefaultEnvironmentSpy.mockRestore();
+    });
+
+    test.each([[true, 1], [false, 0], [undefined, 1]])('respects resolveDefaultEnvironment=%s', async (resolveDefaultEnvironment, callCount) => {
+      // GIVEN
+      await using synthDir = autoCleanOutDir();
+
+      // WHEN
+      const cx = await toolkit.fromCdkApp('node -e "console.log(JSON.stringify(process.env))"', {
+        workingDirectory: process.cwd(),
+        outdir: synthDir.dir,
+        resolveDefaultEnvironment,
+      });
+
+      try {
+        await using _ = await cx.produce();
+      } catch {
+        // we expect this app to throw
+      }
+
+      // THEN
+      expect(prepareDefaultEnvironmentSpy).toHaveBeenCalledTimes(callCount);
+    });
+  });
 });
 
 describe('fromAssemblyDirectory', () => {