fix(app-staging-synthesizer): custom bootstrap qualifier is not passed through to deployment role name (#35118)

### Issue #28195 

Closes #28195 

### Reason for this change

When passing `bootstrapQualifier` in props to `AppStagingSynthesizer.defaultResources`, the synthesizer would still use the default qualifier `'hnb659fds'` when looking for bootstrap roles.

### Description of changes


`BootstraplessSynthesizer` is modified to take `qualifier` as an optional argument (if not provided, default bootstrap qualifier 'hnb659fds' is used).

The `bootstrapqualifier` is passed to `BootstraplessSynthesizer`, which is called in `AppStagingSynthesizer.defaultResources()`.

These changes ensure that calls to `AppStagingSynthesizer.defaultResources` using the `bootstrapQualifier` will use the qualifier in the deployment and CloudFormation execution roles instead of the default qualifier 'hnb659fds'.

### Describe any new or updated permissions being added

None.


### Description of how you validated changes

Added unit tests for:
- `BootstraplessSynthesizer`, which now optionally takes `qualifier` as an option
- `AppStagingSynthesizer`, which passes `qualifier` to `BootstraplessSynthesizer`

Tested by hand in a personal dev account.

### Checklist
- [X] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

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

Author: iankhou

packages/@aws-cdk/app-staging-synthesizer-alpha/lib/default-staging-stack.ts

@@ -155,7 +155,7 @@ export interface DefaultStagingStackProps extends DefaultStagingStackOptions, St
   /**
    * The qualifier used to specialize strings
    *
-   * Shouldn't be necessary but who knows what people might do.
+   * Can be used to specify custom bootstrapped role names
    */
   readonly qualifier: string;
 }
@@ -259,10 +259,13 @@ export class DefaultStagingStack extends Stack implements IStagingResources {
   constructor(scope: App, id: string, private readonly props: DefaultStagingStackProps) {
     super(scope, id, {
       ...props,
-      synthesizer: new BootstraplessSynthesizer(),
+      synthesizer: new BootstraplessSynthesizer({
+        qualifier: props.qualifier,
+      }),
       description: `This stack includes resources needed to deploy the AWS CDK app ${props.appId} into this environment`,
       analyticsReporting: false, // removing AWS::CDK::Metadata construct saves ~3KB
     });
+
     // removing path metadata saves ~2KB
     this.node.setContext(cxapi.PATH_METADATA_ENABLE_CONTEXT, false);
 
@@ -283,7 +286,6 @@ export class DefaultStagingStack extends Stack implements IStagingResources {
     this.stagingBucketEncryption = props.stagingBucketEncryption;
 
     const specializer = new StringSpecializer(this, props.qualifier);
-
     this.providedFileRole = props.fileAssetPublishingRole?._specialize(specializer);
     this.providedImageRole = props.imageAssetPublishingRole?._specialize(specializer);
     this.stagingRepos = {};

packages/@aws-cdk/app-staging-synthesizer-alpha/test/app-staging-synthesizer.test.ts

@@ -26,6 +26,35 @@ describe(AppStagingSynthesizer, () => {
     });
   });
 
+  test('uses qualifier in deployment roles and staging context', () => {
+    // GIVEN
+    const qualifier = 'custom-qualifier';
+    const customApp = new App({
+      defaultStackSynthesizer: AppStagingSynthesizer.defaultResources({
+        appId: APP_ID,
+        bootstrapQualifier: qualifier,
+        stagingBucketEncryption: BucketEncryption.S3_MANAGED,
+      }),
+    });
+    new Stack(customApp, 'CustomStack', {
+      env: {
+        account: '111111111111',
+        region: 'us-east-1',
+      },
+    });
+
+    // WHEN
+    const assembly = customApp.synth();
+    const artifact = assembly.getStackArtifact('CustomStack');
+
+    // THEN
+    // The deployment role should contain the custom qualifier
+    expect(artifact.assumeRoleArn).toBe(`arn:\${AWS::Partition}:iam::111111111111:role/cdk-${qualifier}-deploy-role-111111111111-us-east-1`);
+
+    // The CloudFormation execution role should contain the custom qualifier
+    expect(artifact.cloudFormationExecutionRoleArn).toBe(`arn:\${AWS::Partition}:iam::111111111111:role/cdk-${qualifier}-cfn-exec-role-111111111111-us-east-1`);
+  });
+
   test('stack template is in asset manifest', () => {
     // GIVEN
     new CfnResource(stack, 'Resource', {

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

@@ -7,6 +7,16 @@ import { UnscopedValidationError } from '../errors';
  * Construction properties of `BootstraplessSynthesizer`.
  */
 export interface BootstraplessSynthesizerProps {
+  /**
+   * The qualifier used to specialize strings
+   *
+   * Can be used to specify custom bootstrapped role names
+   *
+   * @default 'hnb659fds'
+   *
+   */
+  readonly qualifier?: string;
+
   /**
    * The deploy Role ARN to use.
    *
@@ -47,6 +57,7 @@ export class BootstraplessSynthesizer extends DefaultStackSynthesizer {
       deployRoleArn: props.deployRoleArn,
       cloudFormationExecutionRole: props.cloudFormationExecutionRoleArn,
       generateBootstrapVersionRule: false,
+      qualifier: props.qualifier,
     });
   }
 

packages/aws-cdk-lib/core/test/stack-synthesis/_helpers.ts renamed to packages/aws-cdk-lib/core/test/stack-synthesizers/_helpers.ts

@@ -0,0 +1,77 @@
+import { FileAssetPackaging } from '@aws-cdk/cloud-assembly-schema';
+import { App } from '../../lib/app';
+import { Stack } from '../../lib/stack';
+import { BootstraplessSynthesizer } from '../../lib/stack-synthesizers/bootstrapless-synthesizer';
+
+describe('BootstraplessSynthesizer', () => {
+  test('differs from DefaultStackSynthesizer in bootstrap requirements', () => {
+    // GIVEN
+    const app = new App();
+    new Stack(app, 'BootstraplessStack', {
+      synthesizer: new BootstraplessSynthesizer(),
+      env: {
+        account: '111111111111',
+        region: 'us-east-1',
+      },
+    });
+
+    const assembly = app.synth();
+
+    // THEN - bootstrapless stack has no bootstrap requirements
+    const bootstraplessArtifact = assembly.getStackArtifact('BootstraplessStack');
+    expect(bootstraplessArtifact.requiresBootstrapStackVersion).toBeUndefined();
+    expect(bootstraplessArtifact.template.Parameters?.BootstrapVersion).toBeUndefined();
+    expect(bootstraplessArtifact.template.Parameters?.FileAssetsBucketName).toBeUndefined();
+    expect(bootstraplessArtifact.template.Parameters?.ImageRepositoryName).toBeUndefined();
+  });
+
+  test('throws when attempting to add assets', () => {
+    // GIVEN
+    const app = new App();
+    const stack = new Stack(app, 'Stack', {
+      synthesizer: new BootstraplessSynthesizer(),
+      env: {
+        account: '111111111111',
+        region: 'us-east-1',
+      },
+    });
+
+    // THEN
+    expect(() => stack.synthesizer.addFileAsset({
+      fileName: __filename,
+      packaging: FileAssetPackaging.FILE,
+      sourceHash: 'file-hash',
+    })).toThrow('Cannot add assets to a Stack that uses the BootstraplessSynthesizer');
+
+    expect(() => stack.synthesizer.addDockerImageAsset({
+      directoryName: '.',
+      sourceHash: 'docker-hash',
+    })).toThrow('Cannot add assets to a Stack that uses the BootstraplessSynthesizer');
+  });
+
+  test('uses qualifier in deployment and execution roles', () => {
+    // GIVEN
+    const qualifier = 'custom-qualifier';
+    const app = new App();
+    const stack = new Stack(app, 'Stack', {
+      synthesizer: new BootstraplessSynthesizer({
+        qualifier,
+      }),
+      env: {
+        account: '111111111111',
+        region: 'us-east-1',
+      },
+    });
+
+    // WHEN
+    const assembly = app.synth();
+    const artifact = assembly.getStackArtifact('Stack');
+
+    // THEN
+    // The deployment role should contain the custom qualifier and use AWS::Partition placeholder
+    expect(artifact.assumeRoleArn).toBe(`arn:\${AWS::Partition}:iam::111111111111:role/cdk-${qualifier}-deploy-role-111111111111-us-east-1`);
+
+    // The CloudFormation execution role should contain the custom qualifier and use AWS::Partition placeholder
+    expect(artifact.cloudFormationExecutionRoleArn).toBe(`arn:\${AWS::Partition}:iam::111111111111:role/cdk-${qualifier}-cfn-exec-role-111111111111-us-east-1`);
+  });
+});