feat(toolkit-lib): bootstrap action

packages/@aws-cdk/tmp-toolkit-helpers/src/util/directories.ts

@@ -1,6 +1,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { ToolkitError } from '../api/toolkit-error';
 
 /**
  * Return a location that will be used as the CDK home directory.
@@ -34,3 +35,30 @@ export function cdkHomeDir() {
 export function cdkCacheDir() {
   return path.join(cdkHomeDir(), 'cache');
 }
+
+/**
+ * From the start location, find the directory that contains the bundled package's package.json
+ *
+ * You must assume the caller of this function will be bundled and the package root dir
+ * is not going to be the same as the package the caller currently lives in.
+ */
+export function bundledPackageRootDir(start: string): string;
+export function bundledPackageRootDir(start: string, fail: true): string;
+export function bundledPackageRootDir(start: string, fail: false): string | undefined;
+export function bundledPackageRootDir(start: string, fail?: boolean) {
+  function _rootDir(dirname: string): string | undefined {
+    const manifestPath = path.join(dirname, 'package.json');
+    if (fs.existsSync(manifestPath)) {
+      return dirname;
+    }
+    if (path.dirname(dirname) === dirname) {
+      if (fail ?? true) {
+        throw new ToolkitError('Unable to find package manifest');
+      }
+      return undefined;
+    }
+    return _rootDir(path.dirname(dirname));
+  }
+
+  return _rootDir(start);
+}

packages/@aws-cdk/toolkit-lib/CODE_REGISTRY.md

@@ -26,6 +26,9 @@
 | CDK_TOOLKIT_I7010 | Confirm destroy stacks | info | n/a |
 | CDK_TOOLKIT_E7010 | Action was aborted due to negative confirmation of request | error | n/a |
 | CDK_TOOLKIT_E7900 | Stack deletion failed | error | n/a |
+| CDK_TOOLKIT_I9000 | Provides bootstrap times | info | n/a |
+| CDK_TOOLKIT_I9900 | Bootstrap results on success | info | n/a |
+| CDK_TOOLKIT_E9900 | Bootstrap failed | error | n/a |
 | CDK_ASSEMBLY_I0042 | Writing updated context | debug | n/a |
 | CDK_ASSEMBLY_I0241 | Fetching missing context | debug | n/a |
 | CDK_ASSEMBLY_I1000 | Cloud assembly output starts | debug | n/a |

packages/@aws-cdk/toolkit-lib/build-tools/bundle.mjs

@@ -16,11 +16,11 @@ await Promise.all([
   copyFromCli(['build-info.json']),
   copyFromCli(['/db.json.gz']),
   copyFromCli(['lib', 'index_bg.wasm']),
+  copyFromCli(['lib', 'api', 'bootstrap', 'bootstrap-template.yaml']),
 ]);
 
 // # Copy all resources that aws_cdk/generate.sh produced, and some othersCall the generator for the
 // cp -R $aws_cdk/lib/init-templates ./lib/
-// mkdir -p ./lib/api/bootstrap/ && cp $aws_cdk/lib/api/bootstrap/bootstrap-template.yaml ./lib/api/bootstrap/
 
 await esbuild.build({
   outdir: 'lib',

packages/@aws-cdk/toolkit-lib/lib/actions/bootstrap/index.ts

@@ -0,0 +1,229 @@
+import * as cxapi from '@aws-cdk/cx-api';
+import { environmentsFromDescriptors } from './private';
+import type { Tag } from '../../api/aws-cdk';
+import type { ICloudAssemblySource } from '../../api/cloud-assembly';
+import { ALL_STACKS } from '../../api/cloud-assembly/private';
+import { assemblyFromSource } from '../../toolkit/private';
+
+/**
+ * Create manage bootstrap environments
+ */
+export class BootstrapEnvironments {
+  /**
+   * Create from a list of environment descriptors
+   * List of strings like `['aws://012345678912/us-east-1', 'aws://234567890123/eu-west-1']`
+   */
+  static fromList(environments: string[]): BootstrapEnvironments {
+    return new BootstrapEnvironments(environmentsFromDescriptors(environments));
+  }
+
+  /**
+   * Create from a cloud assembly source
+   */
+  static fromCloudAssemblySource(cx: ICloudAssemblySource): BootstrapEnvironments {
+    return new BootstrapEnvironments(async () => {
+      const assembly = await assemblyFromSource(cx);
+      const stackCollection = assembly.selectStacksV2(ALL_STACKS);
+      return stackCollection.stackArtifacts.map(stack => stack.environment);
+    });
+  }
+
+  private constructor(private readonly envProvider: cxapi.Environment[] | (() => Promise<cxapi.Environment[]>)) {
+  }
+
+  async getEnvironments(): Promise<cxapi.Environment[]> {
+    if (Array.isArray(this.envProvider)) {
+      return this.envProvider;
+    }
+    return this.envProvider();
+  }
+}
+
+/**
+ * Options for Bootstrap
+ */
+export interface BootstrapOptions {
+
+  /**
+   * Bootstrap environment parameters for CloudFormation used when deploying the bootstrap stack
+   * @default BootstrapEnvironmentParameters.onlyExisting()
+   */
+  readonly parameters?: BootstrapStackParameters;
+
+  /**
+   * The template source of the bootstrap stack
+   *
+   * @default BootstrapSource.default()
+   */
+  readonly source?: { source: 'default' } | { source: 'custom'; templateFile: string };
+
+  /**
+   * Whether to execute the changeset or only create it and leave it in review
+   * @default true
+   */
+  readonly execute?: boolean;
+
+  /**
+   * Tags for cdktoolkit stack
+   *
+   * @default []
+   */
+  readonly tags?: Tag[];
+
+  /**
+   * Whether the stacks created by the bootstrap process should be protected from termination
+   * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-protect-stacks.html
+   * @default true
+   */
+  readonly terminationProtection?: boolean;
+}
+
+/**
+ * Parameter values for the bootstrapping template
+ */
+export interface BootstrapParameters {
+  /**
+   * The name to be given to the CDK Bootstrap bucket
+   * By default, a name is generated by CloudFormation
+   *
+   * @default - No value, optional argument
+   */
+  readonly bucketName?: string;
+
+  /**
+   * The ID of an existing KMS key to be used for encrypting items in the bucket
+   * By default, the default KMS key is used
+   *
+   * @default - No value, optional argument
+   */
+  readonly kmsKeyId?: string;
+
+  /**
+   * Whether or not to create a new customer master key (CMK)
+   *
+   * Only applies to modern bootstrapping
+   * Legacy bootstrapping will never create a CMK, only use the default S3 key
+   *
+   * @default false
+   */
+  readonly createCustomerMasterKey?: boolean;
+
+  /**
+   * The list of AWS account IDs that are trusted to deploy into the environment being bootstrapped
+   *
+   * @default []
+   */
+  readonly trustedAccounts?: string[];
+
+  /**
+   * The list of AWS account IDs that are trusted to look up values in the environment being bootstrapped
+   *
+   * @default []
+   */
+  readonly trustedAccountsForLookup?: string[];
+
+  /**
+   * The list of AWS account IDs that should not be trusted by the bootstrapped environment
+   * If these accounts are already trusted, they will be removed on bootstrapping
+   *
+   * @default []
+   */
+  readonly untrustedAccounts?: string[];
+
+  /**
+   * The ARNs of the IAM managed policies that should be attached to the role performing CloudFormation deployments
+   * In most cases, this will be the AdministratorAccess policy
+   * At least one policy is required if `trustedAccounts` were passed
+   *
+   * @default []
+   */
+  readonly cloudFormationExecutionPolicies?: string[];
+
+  /**
+   * Identifier to distinguish multiple bootstrapped environments
+   * The default qualifier is an arbitrary but unique string
+   *
+   * @default - 'hnb659fds'
+   */
+  readonly qualifier?: string;
+
+  /**
+   * Whether or not to enable S3 Staging Bucket Public Access Block Configuration
+   *
+   * @default true
+   */
+  readonly publicAccessBlockConfiguration?: boolean;
+
+  /**
+   * Flag for using the default permissions boundary for bootstrapping
+   *
+   * @default - No value, optional argument
+   */
+  readonly examplePermissionsBoundary?: boolean;
+
+  /**
+   * Name for the customer's custom permissions boundary for bootstrapping
+   *
+   * @default - No value, optional argument
+   */
+  readonly customPermissionsBoundary?: string;
+}
+
+/**
+ * Parameters of the bootstrapping template with flexible configuration options
+ */
+export class BootstrapStackParameters {
+  /**
+   * Use only existing parameters on the stack.
+   */
+  public static onlyExisting() {
+    return new BootstrapStackParameters({}, true);
+  }
+
+  /**
+   * Use exactly these parameters and remove any other existing parameters from the stack.
+   */
+  public static exactly(params: BootstrapParameters) {
+    return new BootstrapStackParameters(params, false);
+  }
+
+  /**
+   * Define additional parameters for the stack, while keeping existing parameters for unspecified values.
+   */
+  public static withExisting(params: BootstrapParameters) {
+    return new BootstrapStackParameters(params, true);
+  }
+
+  /**
+   * The parameters as a Map for easy access and manipulation
+   */
+  public readonly parameters?: BootstrapParameters;
+  public readonly keepExistingParameters: boolean;
+
+  private constructor(params?: BootstrapParameters, usePreviousParameters = true) {
+    this.keepExistingParameters = usePreviousParameters;
+    this.parameters = params;
+  }
+}
+
+/**
+ * Source configuration for bootstrap operations
+ */
+export class BootstrapSource {
+  /**
+   * Use the default bootstrap template
+   */
+  static default(): BootstrapOptions['source'] {
+    return { source: 'default' };
+  }
+
+  /**
+   * Use a custom bootstrap template
+   */
+  static customTemplate(templateFile: string): BootstrapOptions['source'] {
+    return {
+      source: 'custom',
+      templateFile,
+    };
+  }
+}

packages/@aws-cdk/toolkit-lib/lib/actions/bootstrap/private/helpers.ts

@@ -0,0 +1,24 @@
+import * as cxapi from '@aws-cdk/cx-api';
+import { ToolkitError } from '../../../api/shared-public';
+
+/**
+ * Given a set of "<account>/<region>" strings, construct environments for them
+ */
+export function environmentsFromDescriptors(envSpecs: string[]): cxapi.Environment[] {
+  const ret = new Array<cxapi.Environment>();
+
+  for (const spec of envSpecs) {
+    const parts = spec.replace(/^aws:\/\//, '').split('/');
+    if (parts.length !== 2) {
+      throw new ToolkitError(`Expected environment name in format 'aws://<account>/<region>', got: ${spec}`);
+    }
+
+    ret.push({
+      name: spec,
+      account: parts[0],
+      region: parts[1],
+    });
+  }
+
+  return ret;
+}

packages/@aws-cdk/toolkit-lib/lib/actions/bootstrap/private/index.ts

@@ -0,0 +1 @@
+export * from './helpers';

packages/@aws-cdk/toolkit-lib/lib/actions/index.ts

@@ -1,3 +1,4 @@
+export * from './bootstrap';
 export * from './deploy';
 export * from './destroy';
 export * from './list';

packages/@aws-cdk/toolkit-lib/lib/api/aws-cdk.ts

@@ -5,11 +5,12 @@ export { formatSdkLoggerContent, SdkProvider } from '../../../../aws-cdk/lib/api
 export { Context, PROJECT_CONTEXT } from '../../../../aws-cdk/lib/api/context';
 export { Deployments, type SuccessfulDeployStackResult } from '../../../../aws-cdk/lib/api/deployments';
 export { Settings } from '../../../../aws-cdk/lib/api/settings';
-export { tagsForStack, Tag } from '../../../../aws-cdk/lib/api/tags';
+export { type Tag, tagsForStack } from '../../../../aws-cdk/lib/api/tags';
 export { DEFAULT_TOOLKIT_STACK_NAME } from '../../../../aws-cdk/lib/api/toolkit-info';
 export { ResourceMigrator } from '../../../../aws-cdk/lib/api/resource-import';
 export { CloudWatchLogEventMonitor, findCloudWatchLogGroups } from '../../../../aws-cdk/lib/api/logs';
 export { type WorkGraph, WorkGraphBuilder, AssetBuildNode, AssetPublishNode, StackNode, Concurrency } from '../../../../aws-cdk/lib/api/work-graph';
+export { Bootstrapper } from '../../../../aws-cdk/lib/api/bootstrap';
 
 // Context Providers
 export * as contextproviders from '../../../../aws-cdk/lib/context-providers';

packages/@aws-cdk/toolkit-lib/lib/api/io/private/codes.ts

@@ -190,6 +190,21 @@ export const CODES = {
   }),
 
   // 9: Bootstrap
+  CDK_TOOLKIT_I9000: codeInfo({
+    code: 'CDK_TOOLKIT_I9000',
+    description: 'Provides bootstrap times',
+    level: 'info',
+  }),
+  CDK_TOOLKIT_I9900: codeInfo({
+    code: 'CDK_TOOLKIT_I9900',
+    description: 'Bootstrap results on success',
+    level: 'info',
+  }),
+  CDK_TOOLKIT_E9900: codeInfo({
+    code: 'CDK_TOOLKIT_E9900',
+    description: 'Bootstrap failed',
+    level: 'error',
+  }),
 
   // Assembly codes
   CDK_ASSEMBLY_I0042: codeInfo({

packages/@aws-cdk/toolkit-lib/lib/api/io/private/timer.ts

@@ -37,7 +37,7 @@ export class Timer {
    * Ends the current timer as a specified timing and notifies the IoHost.
    * @returns the elapsed time
    */
-  public async endAs(ioHost: ActionAwareIoHost, type: 'synth' | 'deploy' | 'rollback' | 'destroy') {
+  public async endAs(ioHost: ActionAwareIoHost, type: 'synth' | 'deploy' | 'rollback' | 'destroy' | 'bootstrap') {
     const duration = this.end();
     const { code, text } = timerMessageProps(type);
 
@@ -49,7 +49,7 @@ export class Timer {
   }
 }
 
-function timerMessageProps(type: 'synth' | 'deploy' | 'rollback'| 'destroy'): {
+function timerMessageProps(type: 'synth' | 'deploy' | 'rollback'| 'destroy' | 'bootstrap'): {
   code: CodeInfo;
   text: string;
 } {
@@ -58,5 +58,6 @@ function timerMessageProps(type: 'synth' | 'deploy' | 'rollback'| 'destroy'): {
     case 'deploy': return { code: CODES.CDK_TOOLKIT_I5000, text: 'Deployment' };
     case 'rollback': return { code: CODES.CDK_TOOLKIT_I6000, text: 'Rollback' };
     case 'destroy': return { code: CODES.CDK_TOOLKIT_I7000, text: 'Destroy' };
+    case 'bootstrap': return { code: CODES.CDK_TOOLKIT_I9000, text: 'Bootstrap' };
   }
 }