feat(toolkit-lib): bootstrap action

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/lib/actions/bootstrap/index.ts

@@ -0,0 +1,210 @@
+import { Tag } from '../../api/aws-cdk';
+
+/**
+ * Options for Bootstrap
+ */
+export interface BootstrapOptions {
+
+  /**
+   * Bootstrap environment parameters for CloudFormation used when deploying the bootstrap stack
+   * @default BootstrapEnvironmentParameters.onlyExisting()
+   */
+  readonly parameters?: BootstrapEnvironmentParameters;
+
+  /**
+   * The template source of the bootstrap stack
+   *
+   * @default BootstrapSource.default()
+   */
+  readonly source?: BootstrapSource;
+
+  /**
+   * 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;
+
+  /**
+   * Use previous values for unspecified parameters
+   *
+   * If not set, all parameters must be specified for every deployment
+   *
+   * @default true
+   */
+  usePreviousParameters?: boolean;
+}
+
+/**
+ * Parameter values for the bootstrapping template
+ */
+export interface BootstrapParameterValues {
+  /**
+   * 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 for the bootstrapping template with flexible configuration options
+ */
+export class BootstrapEnvironmentParameters {
+  /**
+   * Use only existing parameters on the stack.
+   */
+  public static onlyExisting() {
+    return new BootstrapEnvironmentParameters({}, true);
+  }
+
+  /**
+   * Use exactly these parameters and remove any other existing parameters from the stack.
+   */
+  public static exactly(params: BootstrapParameterValues) {
+    return new BootstrapEnvironmentParameters(params, false);
+  }
+
+  /**
+   * Define additional parameters for the stack, while keeping existing parameters for unspecified values.
+   */
+  public static withExisting(params: BootstrapParameterValues) {
+    return new BootstrapEnvironmentParameters(params, true);
+  }
+
+  /**
+   * The parameters as a Map for easy access and manipulation
+   */
+  public readonly parameters?: BootstrapParameterValues;
+  public readonly keepExistingParameters: boolean;
+
+  private constructor(params?: BootstrapParameterValues, usePreviousParameters = true) {
+    this.keepExistingParameters = usePreviousParameters;
+    this.parameters = params;
+  }
+}
+
+/**
+ * Source configuration for bootstrap operations
+ */
+export class BootstrapSource {
+  /**
+   * Use the default bootstrap template
+   */
+  static default(): BootstrapSource {
+    return new BootstrapSource('default');
+  }
+
+  /**
+   * Use a custom bootstrap template
+   */
+  static customTemplate(templateFile: string): BootstrapSource {
+    return new BootstrapSource('custom', templateFile);
+  }
+
+  private readonly source: 'default' | 'custom';
+  private readonly templateFile?: string;
+  private constructor(source: 'default' | 'custom', templateFile?: string) {
+    this.source = source;
+    this.templateFile = templateFile;
+  }
+
+  public render() {
+    return {
+      source: this.source,
+      ...(this.templateFile ? { templateFile: this.templateFile } : {}),
+    } as { source: 'default' } | { source: 'custom'; templateFile: string };
+  }
+}

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/errors';
+
+/**
+ * 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/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' };
   }
 }