feat(core): stack synthesizer that uses CLI credentials (#18963)

Clarify documentation of stack synthesizers a bit more, it was very
short. Also add `CliCredentialStackSynthesizer`. Many corporate users
have requested to be able to NOT use the default bootstrap roles,
because they want to rely on user credentials to do authorization.

We now have the following 3 synthesizers:

- `LegacyStackSynthesizer`: asset parameters, no roles.
- `CliCredentialsStackSynthesizer`: conventional assets, no roles.
- `DefaultStackSynthesizer`: conventional assets, conventional roles.

(note: asset parameters, conventional roles does not seem like a
sensible option).

This will give people all the flexibility they need.

Closes #16888.

----

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

Author: rix0rrr

packages/@aws-cdk/core/README.md

@@ -57,6 +57,45 @@ organize their deployments with. If you want to vend a reusable construct,
 define it as a subclasses of `Construct`: the consumers of your construct
 will decide where to place it in their own stacks.
 
+## Stack Synthesizers
+
+Each Stack has a *synthesizer*, an object that determines how and where
+the Stack should be synthesized and deployed. The synthesizer controls
+aspects like:
+
+- How does the stack reference assets? (Either through CloudFormation
+  parameters the CLI supplies, or because the Stack knows a predefined
+  location where assets will be uploaded).
+- What roles are used to deploy the stack? These can be bootstrapped
+  roles, roles created in some other way, or just the CLI's current
+  credentials.
+
+The following synthesizers are available:
+
+- `DefaultStackSynthesizer`: recommended. Uses predefined asset locations and
+  roles created by the modern bootstrap template. Access control is done by
+  controlling who can assume the deploy role. This is the default stack
+  synthesizer in CDKv2.
+- `LegacyStackSynthesizer`: Uses CloudFormation parameters to communicate
+  asset locations, and the CLI's current permissions to deploy stacks. The
+  is the default stack synthesizer in CDKv1.
+- `CliCredentialsStackSynthesizer`: Uses predefined asset locations, and the
+  CLI's current permissions.
+
+Each of these synthesizers takes configuration arguments. To configure
+a stack with a synthesizer, pass it as one of its properties:
+
+```ts
+new MyStack(app, 'MyStack', {
+  synthesizer: new DefaultStackSynthesizer({
+    fileAssetsBucketName: 'my-orgs-asset-bucket',
+  }),
+});
+```
+
+For more information on bootstrapping accounts and customizing synthesis,
+see [Bootstrapping in the CDK Developer Guide](https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html).
+
 ## Nested Stacks
 
 [Nested stacks](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-nested-stacks.html) are stacks created as part of other stacks. You create a nested stack within another stack by using the `NestedStack` construct.

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

@@ -256,13 +256,19 @@ export interface FileAssetLocation {
   /**
    * The HTTP URL of this asset on Amazon S3.
    *
+   * This value suitable for inclusion in a CloudFormation template, and
+   * may be an encoded token.
+   *
    * Example value: `https://s3-us-east-1.amazonaws.com/mybucket/myobject`
    */
   readonly httpUrl: string;
 
   /**
    * The S3 URL of this asset on Amazon S3.
    *
+   * This value suitable for inclusion in a CloudFormation template, and
+   * may be an encoded token.
+   *
    * Example value: `s3://mybucket/myobject`
    */
   readonly s3ObjectUrl: string;
@@ -285,6 +291,16 @@ export interface FileAssetLocation {
    * key via the bucket and no additional parameters have to be granted anymore.
    */
   readonly kmsKeyArn?: string;
+
+  /**
+   * Like `s3ObjectUrl`, but not suitable for CloudFormation consumption
+   *
+   * If there are placeholders in the S3 URL, they will be returned unreplaced
+   * and un-evaluated.
+   *
+   * @default - This feature cannot be used
+   */
+  readonly s3ObjectUrlWithPlaceholders?: string;
 }
 
 /**

packages/@aws-cdk/core/lib/stack-synthesizers/_asset-manifest-builder.ts

@@ -0,0 +1,219 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+import * as cxschema from '@aws-cdk/cloud-assembly-schema';
+import { FileAssetSource, FileAssetLocation, FileAssetPackaging, DockerImageAssetSource, DockerImageAssetLocation } from '../assets';
+import { Fn } from '../cfn-fn';
+import { ISynthesisSession } from '../construct-compat';
+import { Stack } from '../stack';
+import { resolvedOr } from './_shared';
+
+/**
+ * Build an manifest from assets added to a stack synthesizer
+ */
+export class AssetManifestBuilder {
+  private readonly files: NonNullable<cxschema.AssetManifest['files']> = {};
+  private readonly dockerImages: NonNullable<cxschema.AssetManifest['dockerImages']> = {};
+
+  public addFileAssetDefault(
+    asset: FileAssetSource,
+    stack: Stack,
+    bucketName: string,
+    bucketPrefix: string,
+    role?: RoleOptions,
+  ): FileAssetLocation {
+    validateFileAssetSource(asset);
+
+    const extension =
+      asset.fileName != undefined ? path.extname(asset.fileName) : '';
+    const objectKey =
+      bucketPrefix +
+      asset.sourceHash +
+      (asset.packaging === FileAssetPackaging.ZIP_DIRECTORY
+        ? '.zip'
+        : extension);
+
+    // Add to manifest
+    this.files[asset.sourceHash] = {
+      source: {
+        path: asset.fileName,
+        executable: asset.executable,
+        packaging: asset.packaging,
+      },
+      destinations: {
+        [this.manifestEnvName(stack)]: {
+          bucketName: bucketName,
+          objectKey,
+          region: resolvedOr(stack.region, undefined),
+          assumeRoleArn: role?.assumeRoleArn,
+          assumeRoleExternalId: role?.assumeRoleExternalId,
+        },
+      },
+    };
+
+    const { region, urlSuffix } = stackLocationOrInstrinsics(stack);
+    const httpUrl = cfnify(
+      `https://s3.${region}.${urlSuffix}/${bucketName}/${objectKey}`,
+    );
+    const s3ObjectUrlWithPlaceholders = `s3://${bucketName}/${objectKey}`;
+
+    // Return CFN expression
+    //
+    // 's3ObjectUrlWithPlaceholders' is intended for the CLI. The CLI ultimately needs a
+    // 'https://s3.REGION.amazonaws.com[.cn]/name/hash' URL to give to CloudFormation.
+    // However, there's no way for us to actually know the URL_SUFFIX in the framework, so
+    // we can't construct that URL. Instead, we record the 's3://.../...' form, and the CLI
+    // transforms it to the correct 'https://.../' URL before calling CloudFormation.
+    return {
+      bucketName: cfnify(bucketName),
+      objectKey,
+      httpUrl,
+      s3ObjectUrl: cfnify(s3ObjectUrlWithPlaceholders),
+      s3ObjectUrlWithPlaceholders,
+      s3Url: httpUrl,
+    };
+  }
+
+  public addDockerImageAssetDefault(
+    asset: DockerImageAssetSource,
+    stack: Stack,
+    repositoryName: string,
+    dockerTagPrefix: string,
+    role?: RoleOptions,
+  ): DockerImageAssetLocation {
+    validateDockerImageAssetSource(asset);
+    const imageTag = dockerTagPrefix + asset.sourceHash;
+
+    // Add to manifest
+    this.dockerImages[asset.sourceHash] = {
+      source: {
+        executable: asset.executable,
+        directory: asset.directoryName,
+        dockerBuildArgs: asset.dockerBuildArgs,
+        dockerBuildTarget: asset.dockerBuildTarget,
+        dockerFile: asset.dockerFile,
+        networkMode: asset.networkMode,
+      },
+      destinations: {
+        [this.manifestEnvName(stack)]: {
+          repositoryName: repositoryName,
+          imageTag,
+          region: resolvedOr(stack.region, undefined),
+          assumeRoleArn: role?.assumeRoleArn,
+          assumeRoleExternalId: role?.assumeRoleExternalId,
+        },
+      },
+    };
+
+    const { account, region, urlSuffix } = stackLocationOrInstrinsics(stack);
+
+    // Return CFN expression
+    return {
+      repositoryName: cfnify(repositoryName),
+      imageUri: cfnify(
+        `${account}.dkr.ecr.${region}.${urlSuffix}/${repositoryName}:${imageTag}`,
+      ),
+    };
+  }
+
+  /**
+   * Write the manifest to disk, and add it to the synthesis session
+   *
+   * Reutrn the artifact Id
+   */
+  public writeManifest(
+    stack: Stack,
+    session: ISynthesisSession,
+    additionalProps: Partial<cxschema.AssetManifestProperties> = {},
+  ): string {
+    const artifactId = `${stack.artifactId}.assets`;
+    const manifestFile = `${artifactId}.json`;
+    const outPath = path.join(session.assembly.outdir, manifestFile);
+
+    const manifest: cxschema.AssetManifest = {
+      version: cxschema.Manifest.version(),
+      files: this.files,
+      dockerImages: this.dockerImages,
+    };
+
+    fs.writeFileSync(outPath, JSON.stringify(manifest, undefined, 2));
+
+    session.assembly.addArtifact(artifactId, {
+      type: cxschema.ArtifactType.ASSET_MANIFEST,
+      properties: {
+        file: manifestFile,
+        ...additionalProps,
+      },
+    });
+
+    return artifactId;
+  }
+
+  private manifestEnvName(stack: Stack): string {
+    return [
+      resolvedOr(stack.account, 'current_account'),
+      resolvedOr(stack.region, 'current_region'),
+    ].join('-');
+  }
+}
+
+export interface RoleOptions {
+  readonly assumeRoleArn?: string;
+  readonly assumeRoleExternalId?: string;
+}
+
+function validateFileAssetSource(asset: FileAssetSource) {
+  if (!!asset.executable === !!asset.fileName) {
+    throw new Error(`Exactly one of 'fileName' or 'executable' is required, got: ${JSON.stringify(asset)}`);
+  }
+
+  if (!!asset.packaging !== !!asset.fileName) {
+    throw new Error(`'packaging' is expected in combination with 'fileName', got: ${JSON.stringify(asset)}`);
+  }
+}
+
+function validateDockerImageAssetSource(asset: DockerImageAssetSource) {
+  if (!!asset.executable === !!asset.directoryName) {
+    throw new Error(`Exactly one of 'directoryName' or 'executable' is required, got: ${JSON.stringify(asset)}`);
+  }
+
+  check('dockerBuildArgs');
+  check('dockerBuildTarget');
+  check('dockerFile');
+
+  function check<K extends keyof DockerImageAssetSource>(key: K) {
+    if (asset[key] && !asset.directoryName) {
+      throw new Error(`'${key}' is only allowed in combination with 'directoryName', got: ${JSON.stringify(asset)}`);
+    }
+  }
+}
+
+/**
+ * Return the stack locations if they're concrete, or the original CFN intrisics otherwise
+ *
+ * We need to return these instead of the tokenized versions of the strings,
+ * since we must accept those same ${AWS::AccountId}/${AWS::Region} placeholders
+ * in bucket names and role names (in order to allow environment-agnostic stacks).
+ *
+ * We'll wrap a single {Fn::Sub} around the final string in order to replace everything,
+ * but we can't have the token system render part of the string to {Fn::Join} because
+ * the CFN specification doesn't allow the {Fn::Sub} template string to be an arbitrary
+ * expression--it must be a string literal.
+ */
+function stackLocationOrInstrinsics(stack: Stack) {
+  return {
+    account: resolvedOr(stack.account, '${AWS::AccountId}'),
+    region: resolvedOr(stack.region, '${AWS::Region}'),
+    urlSuffix: resolvedOr(stack.urlSuffix, '${AWS::URLSuffix}'),
+  };
+}
+
+/**
+ * If the string still contains placeholders, wrap it in a Fn::Sub so they will be substituted at CFN deployment time
+ *
+ * (This happens to work because the placeholders we picked map directly onto CFN
+ * placeholders. If they didn't we'd have to do a transformation here).
+ */
+function cfnify(s: string): string {
+  return s.indexOf('${') > -1 ? Fn.sub(s) : s;
+}

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

@@ -1,7 +1,12 @@
 import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
 import * as cxschema from '@aws-cdk/cloud-assembly-schema';
+import * as cxapi from '@aws-cdk/cx-api';
+import { FileAssetSource, FileAssetPackaging } from '../assets';
 import { ConstructNode, IConstruct, ISynthesisSession } from '../construct-compat';
 import { Stack } from '../stack';
+import { Token } from '../token';
 
 /**
  * Shared logic of writing stack artifact to the Cloud Assembly
@@ -122,4 +127,60 @@ export function assertBound<A>(x: A | undefined): asserts x is NonNullable<A> {
 
 function nonEmptyDict<A>(xs: Record<string, A>) {
   return Object.keys(xs).length > 0 ? xs : undefined;
+}
+
+/**
+ * A "replace-all" function that doesn't require us escaping a literal string to a regex
+ */
+function replaceAll(s: string, search: string, replace: string) {
+  return s.split(search).join(replace);
+}
+
+export class StringSpecializer {
+  constructor(private readonly stack: Stack, private readonly qualifier: string) {
+  }
+
+  /**
+   * Function to replace placeholders in the input string as much as possible
+   *
+   * We replace:
+   * - ${Qualifier}: always
+   * - ${AWS::AccountId}, ${AWS::Region}: only if we have the actual values available
+   * - ${AWS::Partition}: never, since we never have the actual partition value.
+   */
+  public specialize(s: string): string {
+    s = replaceAll(s, '${Qualifier}', this.qualifier);
+    return cxapi.EnvironmentPlaceholders.replace(s, {
+      region: resolvedOr(this.stack.region, cxapi.EnvironmentPlaceholders.CURRENT_REGION),
+      accountId: resolvedOr(this.stack.account, cxapi.EnvironmentPlaceholders.CURRENT_ACCOUNT),
+      partition: cxapi.EnvironmentPlaceholders.CURRENT_PARTITION,
+    });
+  }
+
+  /**
+   * Specialize only the qualifier
+   */
+  public qualifierOnly(s: string): string {
+    return replaceAll(s, '${Qualifier}', this.qualifier);
+  }
+}
+
+/**
+ * Return the given value if resolved or fall back to a default
+ */
+export function resolvedOr<A>(x: string, def: A): string | A {
+  return Token.isUnresolved(x) ? def : x;
+}
+
+export function stackTemplateFileAsset(stack: Stack, session: ISynthesisSession): FileAssetSource {
+  const templatePath = path.join(session.assembly.outdir, stack.templateFile);
+  const template = fs.readFileSync(templatePath, { encoding: 'utf-8' });
+
+  const sourceHash = contentHash(template);
+
+  return {
+    fileName: stack.templateFile,
+    packaging: FileAssetPackaging.FILE,
+    sourceHash,
+  };
 }