feat(cli): diff now uses the lookup Role for new-style synthesis (#18277)

This PR exposes information on the bootstrap lookup role on the
CloudFormation stack artifact. This enables the CLI to assume the lookup
role during cli operations in order to lookup information in the stack
account.

Along with the ARN of the lookup role, this also exposes a
`requiresBootstrapStackVersion` property which is set to `8` (the
version the lookup role was given ReadOnlyAccess), and the
`bootstrapStackVersionSsmParameter` which is needed to lookup the
bootstrap version if a user has renamed the bootstrap stack.

This allows us to first check whether the lookupRole exists and has the
correct permissions prior to using it.

This also updates the `diff` capability in the CLI (run as part of `cdk diff` or `cdk deploy`)
to use this new functionality. It now will try to assume the lookupRole and if it doesn't exist or
if the bootstrap stack version is not valid, then it will fallback to using the deployRole (what it uses
currently).

This PR also updates the `forEnvironment` function to return whether or not it is returning the
default credentials. This allows the calling function to decide whether or not it actually wants
to use the default credentials.


----

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

Author: corymhall

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

@@ -1,4 +1,37 @@
 
+/**
+ * Information needed to access an IAM role created
+ * as part of the bootstrap process
+ */
+export interface BootstrapRole {
+  /**
+   * The ARN of the IAM role created as part of bootrapping
+   * e.g. lookupRoleArn
+   */
+  readonly arn: string;
+
+  /**
+   * External ID to use when assuming the bootstrap role
+   *
+   * @default - No external ID
+   */
+  readonly assumeRoleExternalId?: string;
+
+  /**
+   * Version of bootstrap stack required to use this role
+   *
+   * @default - No bootstrap stack required
+   */
+  readonly requiresBootstrapStackVersion?: number;
+
+  /**
+   * Name of SSM parameter with bootstrap stack version
+   *
+   * @default - Discover SSM parameter by reading stack
+   */
+  readonly bootstrapStackVersionSsmParameter?: string;
+}
+
 /**
  * Artifact properties for CloudFormation stacks.
  */
@@ -56,6 +89,13 @@ export interface AwsCloudFormationStackProperties {
    */
   readonly cloudFormationExecutionRoleArn?: string;
 
+  /**
+   * The role to use to look up values from the target AWS account
+   *
+   * @default - No role is assumed (current credentials are used)
+   */
+  readonly lookupRole?: BootstrapRole;
+
   /**
    * If the stack template has already been included in the asset manifest, its asset URL
    *

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

@@ -307,6 +307,10 @@
                     "description": "The role that is passed to CloudFormation to execute the change set (Default - No role is passed (currently assumed role/credentials are used))",
                     "type": "string"
                 },
+                "lookupRole": {
+                    "description": "The role to use to look up values from the target AWS account (Default - No role is assumed (current credentials are used))",
+                    "$ref": "#/definitions/BootstrapRole"
+                },
                 "stackTemplateAssetObjectUrl": {
                     "description": "If the stack template has already been included in the asset manifest, its asset URL (Default - Not uploaded yet, upload just before deploying)",
                     "type": "string"
@@ -328,6 +332,31 @@
                 "templateFile"
             ]
         },
+        "BootstrapRole": {
+            "description": "Information needed to access an IAM role created\nas part of the bootstrap process",
+            "type": "object",
+            "properties": {
+                "arn": {
+                    "description": "The ARN of the IAM role created as part of bootrapping\ne.g. lookupRoleArn",
+                    "type": "string"
+                },
+                "assumeRoleExternalId": {
+                    "description": "External ID to use when assuming the bootstrap role (Default - No external ID)",
+                    "type": "string"
+                },
+                "requiresBootstrapStackVersion": {
+                    "description": "Version of bootstrap stack required to use this role (Default - No bootstrap stack required)",
+                    "type": "number"
+                },
+                "bootstrapStackVersionSsmParameter": {
+                    "description": "Name of SSM parameter with bootstrap stack version (Default - Discover SSM parameter by reading stack)",
+                    "type": "string"
+                }
+            },
+            "required": [
+                "arn"
+            ]
+        },
         "AssetManifestProperties": {
             "description": "Artifact properties for the Asset Manifest",
             "type": "object",
@@ -598,7 +627,7 @@
                     }
                 },
                 "returnAsymmetricSubnets": {
-                    "description": "Whether to populate the subnetGroups field of the {@link VpcContextResponse},\nwhich contains potentially asymmetric subnet groups.",
+                    "description": "Whether to populate the subnetGroups field of the{@linkVpcContextResponse},\nwhich contains potentially asymmetric subnet groups.",
                     "default": false,
                     "type": "boolean"
                 },

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

@@ -1 +1 @@
-{"version":"15.0.0"}
+{"version":"16.0.0"}

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

@@ -21,6 +21,12 @@ export const BOOTSTRAP_QUALIFIER_CONTEXT = '@aws-cdk/core:bootstrapQualifier';
  */
 const MIN_BOOTSTRAP_STACK_VERSION = 6;
 
+/**
+ * The minimum bootstrap stack version required
+ * to use the lookup role.
+ */
+const MIN_LOOKUP_ROLE_BOOTSTRAP_STACK_VERSION = 8;
+
 /**
  * Configuration properties for DefaultStackSynthesizer
  */
@@ -91,6 +97,25 @@ export interface DefaultStackSynthesizerProps {
    */
   readonly lookupRoleArn?: string;
 
+  /**
+   * External ID to use when assuming lookup role
+   *
+   * @default - No external ID
+   */
+  readonly lookupRoleExternalId?: string;
+
+  /**
+   * Use the bootstrapped lookup role for (read-only) stack operations
+   *
+   * Use the lookup role when performing a `cdk diff`. If set to `false`, the
+   * `deploy role` credentials will be used to perform a `cdk diff`.
+   *
+   * Requires bootstrap stack version 8.
+   *
+   * @default true
+   */
+  readonly useLookupRoleForStackOperations?: boolean;
+
   /**
    * External ID to use when assuming role for image asset publishing
    *
@@ -269,6 +294,7 @@ export class DefaultStackSynthesizer extends StackSynthesizer {
   private fileAssetPublishingRoleArn?: string;
   private imageAssetPublishingRoleArn?: string;
   private lookupRoleArn?: string;
+  private useLookupRoleForStackOperations: boolean;
   private qualifier?: string;
   private bucketPrefix?: string;
   private dockerTagPrefix?: string;
@@ -279,6 +305,7 @@ export class DefaultStackSynthesizer extends StackSynthesizer {
 
   constructor(private readonly props: DefaultStackSynthesizerProps = {}) {
     super();
+    this.useLookupRoleForStackOperations = props.useLookupRoleForStackOperations ?? true;
 
     for (const key in props) {
       if (props.hasOwnProperty(key)) {
@@ -453,6 +480,12 @@ export class DefaultStackSynthesizer extends StackSynthesizer {
       requiresBootstrapStackVersion: MIN_BOOTSTRAP_STACK_VERSION,
       bootstrapStackVersionSsmParameter: this.bootstrapStackVersionSsmParameter,
       additionalDependencies: [artifactId],
+      lookupRole: this.useLookupRoleForStackOperations && this.lookupRoleArn ? {
+        arn: this.lookupRoleArn,
+        assumeRoleExternalId: this.props.lookupRoleExternalId,
+        requiresBootstrapStackVersion: MIN_LOOKUP_ROLE_BOOTSTRAP_STACK_VERSION,
+        bootstrapStackVersionSsmParameter: this.bootstrapStackVersionSsmParameter,
+      } : undefined,
     });
   }
 

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

@@ -1,3 +1,4 @@
+import * as cxschema from '@aws-cdk/cloud-assembly-schema';
 import { DockerImageAssetLocation, DockerImageAssetSource, FileAssetLocation, FileAssetSource } from '../assets';
 import { ISynthesisSession } from '../construct-compat';
 import { Stack } from '../stack';
@@ -100,6 +101,13 @@ export interface SynthesizeStackArtifactOptions {
    */
   readonly cloudFormationExecutionRoleArn?: string;
 
+  /**
+   * The role to use to look up values from the target AWS account
+   *
+   * @default - None
+   */
+  readonly lookupRole?: cxschema.BootstrapRole;
+
   /**
    * If the stack template has already been included in the asset manifest, its asset URL
    *

packages/@aws-cdk/cx-api/lib/artifacts/cloudformation-artifact.ts

@@ -75,6 +75,13 @@ export class CloudFormationStackArtifact extends CloudArtifact {
    */
   public readonly cloudFormationExecutionRoleArn?: string;
 
+  /**
+   * The role to use to look up values from the target AWS account
+   *
+   * @default - No role is assumed (current credentials are used)
+   */
+  public readonly lookupRole?: cxschema.BootstrapRole;
+
   /**
    * If the stack template has already been included in the asset manifest, its asset URL
    *
@@ -135,6 +142,7 @@ export class CloudFormationStackArtifact extends CloudArtifact {
     this.bootstrapStackVersionSsmParameter = properties.bootstrapStackVersionSsmParameter;
     this.terminationProtection = properties.terminationProtection;
     this.validateOnSynth = properties.validateOnSynth;
+    this.lookupRole = properties.lookupRole;
 
     this.stackName = properties.stackName || artifactId;
     this.assets = this.findMetadataByType(cxschema.ArtifactMetadataEntryType.ASSET).map(e => e.data as cxschema.AssetMetadataEntry);

packages/aws-cdk/lib/api/aws-auth/sdk-provider.ts

@@ -77,6 +77,33 @@ export interface SdkHttpOptions {
 const CACHED_ACCOUNT = Symbol('cached_account');
 const CACHED_DEFAULT_CREDENTIALS = Symbol('cached_default_credentials');
 
+/**
+ * SDK configuration for a given environment
+ * 'forEnvironment' will attempt to assume a role and if it
+ * is not successful, then it will either:
+ *   1. Check to see if the default credentials (local credentials the CLI was executed with)
+ *      are for the given environment. If they are then return those.
+ *   2. If the default credentials are not for the given environment then
+ *      throw an error
+ *
+ * 'didAssumeRole' allows callers to whether they are receiving the assume role
+ * credentials or the default credentials.
+ */
+export interface SdkForEnvironment {
+  /**
+   * The SDK for the given environment
+   */
+  readonly sdk: ISDK;
+
+  /**
+   * Whether or not the assume role was successful.
+   * If the assume role was not successful (false)
+   * then that means that the 'sdk' returned contains
+   * the default credentials (not the assume role credentials)
+   */
+  readonly didAssumeRole: boolean;
+}
+
 /**
  * Creates instances of the AWS SDK appropriate for a given account/region.
  *
@@ -140,7 +167,11 @@ export class SdkProvider {
    *
    * The `environment` parameter is resolved first (see `resolveEnvironment()`).
    */
-  public async forEnvironment(environment: cxapi.Environment, mode: Mode, options?: CredentialsOptions): Promise<ISDK> {
+  public async forEnvironment(
+    environment: cxapi.Environment,
+    mode: Mode,
+    options?: CredentialsOptions,
+  ): Promise<SdkForEnvironment> {
     const env = await this.resolveEnvironment(environment);
     const baseCreds = await this.obtainBaseCredentials(env.account, mode);
 
@@ -151,7 +182,7 @@ export class SdkProvider {
     // account.
     if (options?.assumeRoleArn === undefined) {
       if (baseCreds.source === 'incorrectDefault') { throw new Error(fmtObtainCredentialsError(env.account, baseCreds)); }
-      return new SDK(baseCreds.credentials, env.region, this.sdkOptions);
+      return { sdk: new SDK(baseCreds.credentials, env.region, this.sdkOptions), didAssumeRole: false };
     }
 
     // We will proceed to AssumeRole using whatever we've been given.
@@ -161,7 +192,7 @@ export class SdkProvider {
     // we can determine whether the AssumeRole call succeeds or not.
     try {
       await sdk.forceCredentialRetrieval();
-      return sdk;
+      return { sdk, didAssumeRole: true };
     } catch (e) {
       // AssumeRole failed. Proceed and warn *if and only if* the baseCredentials were already for the right account
       // or returned from a plugin. This is to cover some current setups for people using plugins or preferring to
@@ -170,7 +201,7 @@ export class SdkProvider {
       if (baseCreds.source === 'correctDefault' || baseCreds.source === 'plugin') {
         debug(e.message);
         warning(`${fmtObtainedCredentials(baseCreds)} could not be used to assume '${options.assumeRoleArn}', but are for the right account. Proceeding anyway.`);
-        return new SDK(baseCreds.credentials, env.region, this.sdkOptions);
+        return { sdk: new SDK(baseCreds.credentials, env.region, this.sdkOptions), didAssumeRole: false };
       }
 
       throw e;

packages/aws-cdk/lib/api/bootstrap/deploy-bootstrap.ts

@@ -27,7 +27,7 @@ export class BootstrapStack {
     toolkitStackName = toolkitStackName ?? DEFAULT_TOOLKIT_STACK_NAME;
 
     const resolvedEnvironment = await sdkProvider.resolveEnvironment(environment);
-    const sdk = await sdkProvider.forEnvironment(resolvedEnvironment, Mode.ForWriting);
+    const sdk = (await sdkProvider.forEnvironment(resolvedEnvironment, Mode.ForWriting)).sdk;
 
     const currentToolkitInfo = await ToolkitInfo.lookup(resolvedEnvironment, sdk, toolkitStackName);