fix(core): implicit Aspect applications do not override custom Aspect applications (#34132)

Some CDK methods apply mutating Aspects on behalf of users. Since #32333, these Aspects have a priority of `MUTATING` to classify their behavior.

If a user-applied Aspect (priority `DEFAULT`) now configures the same property as an implicitly added Aspect:

* Before that change, the relative execution order depended on the location of the Aspects in the construct tree.
* After that change, the user Aspect always "wins" (executes last) because its priority is higher.

In this change, we roll back to the behavior from pre-2.172.0, and introduce a feature flag which gives the Aspects a priority only if the feature flag is enabled. This introduces the feature flag:

```json
{
  "context": {
    "@aws-cdk/core:aspectPrioritiesMutating": true
  }
}
```

Which sets the priority of Aspects added on your behalf a priority of `MUTATING` (200) (instead of the default `DEFAULT`, 500).

* If you have given your own Aspect a priority of `MUTATING` already to make sure it can get overridden by another Aspect  of priority `MUTATING`, this current change will not affect you (either with or without feature flag).
* If you have come to rely on the new default priority being low already, you can set the above feature flag to re-enable the new behavior.

-----------

Did not touch the following Aspects:

- In `integ-tests-alpha`: overriding logical IDs in assertions stacks does not affect production infrastructure.
- Tags: tags are exclusively manipulated through the official APIs, so there no conflict between custom and implicit Aspects.
- CDK Pipelines: there cannot be a conflict because the customer can't create a default pipeline before the implicit Aspect.

This PR also introduces some slight rendering and documentation changes to the feature flags to improve clarity of the purpose of certain fields and the produced report.

Author: rix0rrr

packages/@aws-cdk-testing/framework-integ/test/aws-codepipeline-actions/test/integ.pipeline-ecr-image-scan-action.js.snapshot/asset.12157b27d30ab71eb24ae65825f672ba5cc2c09dbb1703cd7adfcff3aeaca136.zip

@@ -1,4 +1,5 @@
 import * as cdk from 'aws-cdk-lib/core';
+import * as cxapi from 'aws-cdk-lib/cx-api';
 import { Construct } from 'constructs';
 import { IApplication } from './application';
 import { CheckedStageStackAssociator } from './aspects/stack-associator';
@@ -50,7 +51,9 @@ export class ApplicationAssociator extends Construct {
     this.associateCrossAccountStacks = targetBindResult.associateCrossAccountStacks;
     cdk.Aspects.of(scope).add(new CheckedStageStackAssociator(this, {
       associateCrossAccountStacks: this.associateCrossAccountStacks,
-    }), { priority: cdk.AspectPriority.MUTATING });
+    }), {
+      priority: cdk.FeatureFlags.of(this).isEnabled(cxapi.ASPECT_PRIORITIES_MUTATING) ? cdk.AspectPriority.MUTATING : undefined,
+    });
   }
 
   /**
@@ -61,7 +64,9 @@ export class ApplicationAssociator extends Construct {
     this.associatedStages.add(stage);
     cdk.Aspects.of(stage).add(new CheckedStageStackAssociator(this, {
       associateCrossAccountStacks: this.associateCrossAccountStacks,
-    }), { priority: cdk.AspectPriority.MUTATING });
+    }), {
+      priority: cdk.FeatureFlags.of(this).isEnabled(cxapi.ASPECT_PRIORITIES_MUTATING) ? cdk.AspectPriority.MUTATING : undefined,
+    });
     return stage;
   }
 

packages/@aws-cdk-testing/framework-integ/test/aws-codepipeline-actions/test/integ.pipeline-ecr-image-scan-action.js.snapshot/asset.6a9a0507c3e2bfac9749f257bdd3d9f313c01ee3984ad7bf373597c341863d6f.zip

@@ -17,7 +17,6 @@ import * as iam from '../../aws-iam';
 import * as sns from '../../aws-sns';
 import {
   Annotations,
-  AspectPriority,
   Aspects,
   Aws,
   CfnAutoScalingRollingUpdate, CfnCreationPolicy, CfnUpdatePolicy,
@@ -26,6 +25,7 @@ import {
   Tokenization, UnscopedValidationError, ValidationError, withResolved,
 } from '../../core';
 import { addConstructMetadata, MethodMetadata } from '../../core/lib/metadata-resource';
+import { mutatingAspectPrio32333 } from '../../core/lib/private/aspect-prio';
 import { AUTOSCALING_GENERATE_LAUNCH_TEMPLATE } from '../../cx-api';
 
 /**
@@ -1608,7 +1608,9 @@ export class AutoScalingGroup extends AutoScalingGroupBase implements
     this.spotPrice = props.spotPrice;
 
     if (props.requireImdsv2) {
-      Aspects.of(this).add(new AutoScalingGroupRequireImdsv2Aspect(), { priority: AspectPriority.MUTATING });
+      Aspects.of(this).add(new AutoScalingGroupRequireImdsv2Aspect(), {
+        priority: mutatingAspectPrio32333(this),
+      });
     }
 
     this.node.addValidation({ validate: () => this.validateTargetGroup() });

packages/@aws-cdk-testing/framework-integ/test/aws-eks/test/integ.eks-cluster-tags.js.snapshot/asset.12157b27d30ab71eb24ae65825f672ba5cc2c09dbb1703cd7adfcff3aeaca136.zip

@@ -4,8 +4,9 @@ import { BackupableResourcesCollector } from './backupable-resources-collector';
 import { IBackupPlan } from './plan';
 import { BackupResource, TagOperation } from './resource';
 import * as iam from '../../aws-iam';
-import { Lazy, Resource, Aspects, AspectPriority } from '../../core';
+import { Lazy, Resource, Aspects } from '../../core';
 import { addConstructMetadata } from '../../core/lib/metadata-resource';
+import { mutatingAspectPrio32333 } from '../../core/lib/private/aspect-prio';
 
 /**
  * Options for a BackupSelection
@@ -143,7 +144,9 @@ export class BackupSelection extends Resource implements iam.IGrantable {
     }
 
     if (resource.construct) {
-      Aspects.of(resource.construct).add(this.backupableResourcesCollector, { priority: AspectPriority.MUTATING });
+      Aspects.of(resource.construct).add(this.backupableResourcesCollector, {
+        priority: mutatingAspectPrio32333(resource.construct),
+      });
       // Cannot push `this.backupableResourcesCollector.resources` to
       // `this.resources` here because it has not been evaluated yet.
       // Will be concatenated to `this.resources` in a `Lazy.list`

packages/@aws-cdk-testing/framework-integ/test/aws-eks/test/integ.eks-cluster-tags.js.snapshot/asset.93d96d34e0d3cd20eb082652b91012b131bdc34fcf2bc16eb4170e04772fddb1.zip

@@ -15,9 +15,10 @@ import { UserData } from './user-data';
 import { BlockDevice } from './volume';
 import { IVpc, Subnet, SubnetSelection } from './vpc';
 import * as iam from '../../aws-iam';
-import { Annotations, AspectPriority, Aspects, Duration, FeatureFlags, Fn, IResource, Lazy, Resource, Stack, Tags, Token } from '../../core';
+import { Annotations, Aspects, Duration, FeatureFlags, Fn, IResource, Lazy, Resource, Stack, Tags, Token } from '../../core';
 import { md5hash } from '../../core/lib/helpers-internal';
 import { addConstructMetadata, MethodMetadata } from '../../core/lib/metadata-resource';
+import { mutatingAspectPrio32333 } from '../../core/lib/private/aspect-prio';
 import * as cxapi from '../../cx-api';
 
 /**
@@ -671,7 +672,9 @@ export class Instance extends Resource implements IInstance {
     }));
 
     if (props.requireImdsv2) {
-      Aspects.of(this).add(new InstanceRequireImdsv2Aspect(), { priority: AspectPriority.MUTATING });
+      Aspects.of(this).add(new InstanceRequireImdsv2Aspect(), {
+        priority: mutatingAspectPrio32333(this),
+      });
     }
   }
 

packages/@aws-cdk/aws-servicecatalogappregistry-alpha/lib/application-associator.ts

@@ -24,10 +24,10 @@ import {
   IAspect,
   Token,
   Names,
-  AspectPriority,
   FeatureFlags, Annotations,
 } from '../../core';
 import { addConstructMetadata, MethodMetadata } from '../../core/lib/metadata-resource';
+import { mutatingAspectPrio32333 } from '../../core/lib/private/aspect-prio';
 import { Disable_ECS_IMDS_Blocking, Enable_IMDS_Blocking_Deprecated_Feature } from '../../cx-api';
 
 const CLUSTER_SYMBOL = Symbol.for('@aws-cdk/aws-ecs/lib/cluster.Cluster');
@@ -331,7 +331,9 @@ export class Cluster extends Resource implements ICluster {
     // since it's harmless, but we'd prefer not to add unexpected new
     // resources to the stack which could surprise users working with
     // brown-field CDK apps and stacks.
-    Aspects.of(this).add(new MaybeCreateCapacityProviderAssociations(this, id), { priority: AspectPriority.MUTATING });
+    Aspects.of(this).add(new MaybeCreateCapacityProviderAssociations(this, id), {
+      priority: mutatingAspectPrio32333(this),
+    });
   }
 
   /**

packages/aws-cdk-lib/aws-autoscaling/lib/auto-scaling-group.ts

@@ -1,7 +1,8 @@
 import { IConstruct } from 'constructs';
 import { CfnRole, CfnUser } from './iam.generated';
 import { IManagedPolicy } from './managed-policy';
-import { AspectPriority, Aspects, CfnResource } from '../../core';
+import { Aspects, CfnResource } from '../../core';
+import { mutatingAspectPrio32333 } from '../../core/lib/private/aspect-prio';
 
 /**
  * Modify the Permissions Boundaries of Users and Roles in a construct tree
@@ -40,7 +41,9 @@ export class PermissionsBoundary {
           node.addPropertyOverride('PermissionsBoundary', boundaryPolicy.managedPolicyArn);
         }
       },
-    }, { priority: AspectPriority.MUTATING });
+    }, {
+      priority: mutatingAspectPrio32333(this.scope),
+    });
   }
 
   /**
@@ -56,6 +59,8 @@ export class PermissionsBoundary {
           node.addPropertyDeletionOverride('PermissionsBoundary');
         }
       },
-    }, { priority: AspectPriority.MUTATING });
+    }, {
+      priority: mutatingAspectPrio32333(this.scope),
+    });
   }
 }