feat(servicecatalogappregistry): application-associator L2 Construct

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

@@ -27,7 +27,7 @@ enables organizations to create and manage repositores of applications and assoc
 ## Table Of Contents
 
 - [Application](#application)
-- [Automatic-Application](#automatic-application)
+- [Register-Application](#register-application)
 - [Attribute-Group](#attribute-group)
 - [Associations](#associations)
  - [Associating application with an attribute group](#attribute-group-association)
@@ -65,33 +65,39 @@ const importedApplication = appreg.Application.fromApplicationArn(
 );
 ```
 
-## Automatic-Application
+## Register-Application
 
-An AppRegistry L2 construct to automatically create an application with the given name and description.
-The application name must be unique at the account level and it's immutable.
-`AutomaticApplication` L2 construct will automatically associate all stacks in the given scope, however
-in case of a `Pipeline` stack, stage underneath the pipeline will not automatically be associated and
-needs to be associated separately.
-If cross account stack is detected, then this construct will automatically share the application to consumer accounts.
-Cross account feature will only work for non environment agnostic stacks.
-
-Following will create an Application named `MyAutoApplication` in account `123456789012` and region `us-east-1`
-and will associate all stacks in the `App` scope to `MyAutoApplication`.
+If you want to create an Application named `MyRegisteredApplication` in account `123456789012` and region `us-east-1`
+and want to associate all stacks in the `App` scope to `MyRegisteredApplication`, then use as shown in the example below:
 
 ```ts
 const app = new App();
-const autoApp = new appreg.AutomaticApplication(app, 'AutoApplication', {
- applicationName: 'MyAutoApplication',
- description: 'Testing auto application',
+const registeredApp = new appreg.RegisterApplication(app, 'RegisterApplication', {
+ applicationName: 'MyRegisteredApplication',
+ description: 'Testing registered application',
  stackProps: {
- stackName: 'MyAutoApplicationStack',
+ stackName: 'MyRegisteredApplicationStack',
  env: {account: '123456789012', region: 'us-east-1'},
  },
 });
 ```
 
-In case of a Pipeline stack, you need to pass the reference of `AutomaticApplication` to pipeline stack and associate
-each stage as shown below:
+If you want to re-use an existing Application with ARN: `arn:aws:servicecatalog:us-east-1:123456789012:/applications/applicationId`
+and want to associate all stacks in the `App` scope to your imported application, then use as shown in the example below:
+
+```ts
+const app = new App();
+const registeredApp = new appreg.RegisterApplication(app, 'RegisterApplication', {
+ applicationArnValue: 'arn:aws:servicecatalog:us-east-1:123456789012:/applications/applicationId',
+ stackProps: {
+ stackName: 'MyRegisteredApplicationStack',
+ },
+});
+```
+
+If you are using CDK Pipelines to deploy your application, the application stacks will be inside Stages, and 
+RegisterApplication will not be able to find them. Call `associateStage` on each Stage object before adding it to the 
+Pipeline, as shown in the example below:
 
 ```ts
 import * as cdk from "@aws-cdk/core";
@@ -104,28 +110,28 @@ class ApplicationPipelineStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props: ApplicationPipelineStackProps) {
  super(scope, id, props);
 
- //associate the stage to automatic application.
- props.application.associateStage(beta, this.stackName);
+ //associate the stage to register application.
+ props.application.associateStage(beta);
  pipeline.addStage(beta);
  }
 };
 
 interface ApplicationPipelineStackProps extends cdk.StackProps {
- application: appreg.AutomaticApplication;
+ application: appreg.RegisterApplication;
 };
 
 const app = new App();
-const autoApp = new appreg.AutomaticApplication(app, 'AutoApplication', {
- applicationName: 'MyPipelineAutoApplication',
- description: 'Testing pipeline auto app',
+const registeredApp = new appreg.RegisterApplication(app, 'RegisterApplication', {
+ applicationName: 'MyPipelineRegisteredApplication',
+ description: 'Testing pipeline registered app',
  stackProps: {
- stackName: 'MyPipelineAutoApplicationStack',
+ stackName: 'MyPipelineRegisteredApplicationStack',
  env: {account: '123456789012', region: 'us-east-1'},
  },
 });
 
 const cdkPipeline = new ApplicationPipelineStack(app, 'CDKApplicationPipelineStack', {
- application: autoApp,
+ application: registeredApp,
  env: {account: '123456789012', region: 'us-east-1'},
 });
 ```

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

@@ -5,6 +5,7 @@ import { Construct } from 'constructs';
 import { StageStackAssociator } from './aspects/stack-associator';
 import { IAttributeGroup } from './attribute-group';
 import { getPrincipalsforSharing, hashValues, ShareOptions, SharePermission } from './common';
+import { isAccountUnresolved } from './private/utils';
 import { InputValidator } from './private/validation';
 import { CfnApplication, CfnAttributeGroupAssociation, CfnResourceAssociation } from './servicecatalogappregistry.generated';
 
@@ -43,7 +44,7 @@ export interface IApplication extends cdk.IResource {
  /**
  * Associate this application with a CloudFormation stack.
  *
- * @deprecated Use `associateApplicationWithResource` instead.
+ * @deprecated Use `associateApplicationWithStack` instead.
  * @param stack a CFN stack
  */
  associateStack(stack: cdk.Stack): void;
@@ -53,7 +54,7 @@ export interface IApplication extends cdk.IResource {
  *
  * @param stack a CFN stack
  */
- associateApplicationWithResource(stack: cdk.Stack): void;
+ associateApplicationWithStack(stack: cdk.Stack): void;
 
  /**
  * Share this application with other IAM entities, accounts, or OUs.
@@ -116,7 +117,7 @@ abstract class ApplicationBase extends cdk.Resource implements IApplication {
  * If the resource is already associated, it will ignore duplicate request.
  * A stack can only be associated with one application.
  *
- * @deprecated Use `associateApplicationWithResource` instead.
+ * @deprecated Use `associateApplicationWithStack` instead.
  */
  public associateStack(stack: cdk.Stack): void {
  if (!this.associatedResources.has(stack.node.addr)) {
@@ -136,7 +137,7 @@ abstract class ApplicationBase extends cdk.Resource implements IApplication {
  * If the stack is already associated, it will ignore duplicate request.
  * A stack can only be associated with one application.
  */
- public associateApplicationWithResource(stack: cdk.Stack): void {
+ public associateApplicationWithStack(stack: cdk.Stack): void {
  if (!this.associatedResources.has(stack.node.addr)) {
  new CfnResourceAssociation(stack, 'AppRegistryAssociation', {
  application: stack === cdk.Stack.of(this) ? this.applicationId : this.applicationName ?? this.applicationId,
@@ -145,7 +146,7 @@ abstract class ApplicationBase extends cdk.Resource implements IApplication {
  });
 
  this.associatedResources.add(stack.node.addr);
- if (stack !== cdk.Stack.of(this) && this.env.account === stack.account && !this.isStageScope(stack)) {
+ if (stack !== cdk.Stack.of(this) && this.isSameAccount(stack) && !this.isStageScope(stack)) {
  stack.addDependency(cdk.Stack.of(this));
  }
  }
@@ -200,9 +201,20 @@ abstract class ApplicationBase extends cdk.Resource implements IApplication {
  }
  }
 
+ /**
+ * Checks whether a stack is defined in a Stage or not.
+ */
  private isStageScope(stack : cdk.Stack): boolean {
  return !(stack.node.scope instanceof cdk.App) && (stack.node.scope instanceof cdk.Stage);
  }
+
+ /**
+ * Verifies if application and the visited node is deployed in different account.
+ */
+ private isSameAccount(stack: cdk.Stack): boolean {
+ return isAccountUnresolved(this.env.account, stack.account) || this.env.account === stack.account;
+ }
+
 }
 
 /**

packages/@aws-cdk/aws-servicecatalogappregistry/lib/aspects/stack-associator.ts

@@ -1,10 +1,9 @@
-import { Pipeline } from '@aws-cdk/aws-codepipeline';
-import { IAspect, Stack, Token, Annotations } from '@aws-cdk/core';
-import { CodePipeline } from '@aws-cdk/pipelines';
+import { IAspect, Stack, Stage, Annotations } from '@aws-cdk/core';
 import { IConstruct } from 'constructs';
 import { IApplication } from '../application';
-import { AutomaticApplication } from '../automatic-application';
 import { SharePermission } from '../common';
+import { isRegionUnresolved, isAccountUnresolved } from '../private/utils';
+import { RegisterApplication } from '../register-application';
 
 /**
  * Aspect class, this will visit each node from the provided construct once.
@@ -14,26 +13,21 @@ import { SharePermission } from '../common';
  */
 abstract class StackAssociatorBase implements IAspect {
  protected abstract readonly application: IApplication;
- protected abstract readonly automaticApplication?: AutomaticApplication;
+ protected abstract readonly registerApplication?: RegisterApplication;
 
  protected readonly sharedAccounts: Set<string> = new Set();
- protected pipelineStages: Set<string> = new Set();
 
  public visit(node: IConstruct): void {
- if (node instanceof CodePipeline) {
- this.pipelineStages = this.getPipelineStages(node);
- }
-
  // verify if a stage in a particular stack is associated to Application.
- if (this.automaticApplication != undefined && node instanceof Pipeline) {
- this.pipelineStages.forEach(( customStage ) => {
- var stageAssociated = this.automaticApplication?.isStageAssociated(customStage, node.stack.stackName);
- if (!stageAssociated) {
- this.error(node, 'Associate Stage: ' + customStage + ' to ensure all stacks in your cdk app are associated with AppRegistry. '
- + 'You can use AutomaticApplication.associateStage to associate any stage.');
+ node.node.children.forEach((childNode) => {
+ if (Stage.isStage(childNode)) {
+ var stageAssociated = this.registerApplication?.isStageAssociated(childNode);
+ if (stageAssociated === false) {
+ this.error(childNode, 'Associate Stage: ' + childNode.stageName + ' to ensure all stacks in your cdk app are associated with AppRegistry. '
+  + 'You can use RegisterApplication.associateStage to associate any stage.');
  }
- });
- }
+ }
+ });
 
  if (Stack.isStack(node)) {
  this.handleCrossRegionStack(node);
@@ -48,7 +42,7 @@ abstract class StackAssociatorBase implements IAspect {
  * @param node A Stage stack.
  */
  private associate(node: Stack): void {
- this.application.associateApplicationWithResource(node);
+ this.application.associateApplicationWithStack(node);
  }
 
  /**
@@ -80,7 +74,7 @@ abstract class StackAssociatorBase implements IAspect {
  * @param node Cfn stack.
  */
  private handleCrossRegionStack(node: Stack): void {
- if (this.isRegionUnresolved(this.application.env.region, node.region)) {
+ if (isRegionUnresolved(this.application.env.region, node.region)) {
  this.warning(node, 'Environment agnostic stack determined, AppRegistry association might not work as expected in case you deploy cross-region or cross-account stack.');
  return;
  }
@@ -99,7 +93,7 @@ abstract class StackAssociatorBase implements IAspect {
  * @param node Cfn stack.
  */
  private handleCrossAccountStack(node: Stack): void {
- if (this.isAccountUnresolved(this.application.env.account!, node.account)) {
+ if (isAccountUnresolved(this.application.env.account!, node.account)) {
  this.warning(node, 'Environment agnostic stack determined, AppRegistry association might not work as expected in case you deploy cross-region or cross-account stack.');
  return;
  }
@@ -113,58 +107,22 @@ abstract class StackAssociatorBase implements IAspect {
  this.sharedAccounts.add(node.account);
  }
  }
-
- /**
- * Verifies if application or the visited node is region agnostic.
- *
- * @param applicationRegion Region of the application.
- * @param nodeRegion Region of the visited node.
- */
- private isRegionUnresolved(applicationRegion: string, nodeRegion: string): boolean {
- return Token.isUnresolved(applicationRegion) || Token.isUnresolved(nodeRegion);
- }
-
- /**
- * Verifies if application or the visited node is account agnostic.
- *
- * @param applicationAccount Account of the application.
- * @param nodeAccount Account of the visited node.
- */
- private isAccountUnresolved(applicationAccount: string, nodeAccount: string): boolean {
- return Token.isUnresolved(applicationAccount) || Token.isUnresolved(nodeAccount);
- }
-
- /**
- * Get custom defined stage names for the given pipeline.
- *
- * @param pipeline Code Pipeline.
- */
- private getPipelineStages(pipeline: CodePipeline): Set<string> {
- const stageNames = new Set<string>();
- pipeline.waves.forEach( ( wave ) => {
- wave.stages.forEach( ( stage ) => {
- stageNames.add(stage.stageName);
- });
- });
-
- return stageNames;
- }
 }
 
-export class AutomaticApplicationStageStackAssociator extends StackAssociatorBase {
+export class RegisterApplicationStageStackAssociator extends StackAssociatorBase {
  protected readonly application: IApplication;
- protected readonly automaticApplication?: AutomaticApplication;
+ protected readonly registerApplication?: RegisterApplication;
 
- constructor(app: AutomaticApplication) {
+ constructor(app: RegisterApplication) {
  super();
  this.application = app.appRegistryApplication;
- this.automaticApplication = app;
+ this.registerApplication = app;
  }
 }
 
 export class StageStackAssociator extends StackAssociatorBase {
  protected readonly application: IApplication;
- protected readonly automaticApplication?: AutomaticApplication;
+ protected readonly registerApplication?: RegisterApplication;
 
  constructor(app: IApplication) {
  super();

packages/@aws-cdk/aws-servicecatalogappregistry/lib/attribute-group.ts

@@ -1,10 +1,10 @@
 import { CfnResourceShare } from '@aws-cdk/aws-ram';
 import * as cdk from '@aws-cdk/core';
-import { getPrincipalsforSharing, hashValues, ShareOptions, SharePermission } from './common';
+import { Names } from '@aws-cdk/core';
 import { Construct } from 'constructs';
+import { getPrincipalsforSharing, hashValues, ShareOptions, SharePermission } from './common';
 import { InputValidator } from './private/validation';
 import { CfnAttributeGroup } from './servicecatalogappregistry.generated';
-import { Names } from '@aws-cdk/core';
 
 const ATTRIBUTE_GROUP_READ_ONLY_RAM_PERMISSION_ARN = 'arn:aws:ram::aws:permission/AWSRAMPermissionServiceCatalogAppRegistryAttributeGroupReadOnly';
 const ATTRIBUTE_GROUP_ALLOW_ACCESS_RAM_PERMISSION_ARN = 'arn:aws:ram::aws:permission/AWSRAMPermissionServiceCatalogAppRegistryAttributeGroupAllowAssociation';