feat(aws-cur): add new property enableDefaultUniqueReportName that creates a unique cost report name by default (#48)

* fix(aws-cur): default name for cost report is not unique

* update API.md

* enableDefaultUniqueReportName

API.md

* change an integ test

chage var name

snapshots

---------

Signed-off-by: Thorsten Hoeger <thorsten.hoeger@taimos.de>
Co-authored-by: Thorsten Hoeger <thorsten.hoeger@taimos.de>

Author: go-to-k

API.md

@@ -19,6 +19,7 @@ import { CostReport, ReportGranularity, CurFormat } from '@open-constructs/aws-c
 ```
 
 ### Basic Example
+
 Here's how you can create a monthly cost and usage report in Parquet format:
 
 ```typescript
@@ -50,6 +51,23 @@ new CostReport(stack, 'MyDetailedCostReport', {
 });
 ```
 
+### Generating Unique Report Name By Default
+
+If you set the `enableDefaultUniqueReportName` property to `true`, the construct will automatically
+generate a unique report name by default.
+
+The cost report name must be unique within your AWS account. So this property is useful when you want
+to create multiple reports without specifying a report name for each one.
+
+If you specify a report name directly via the `costReportName`, the construct will use that name instead
+of generating a unique one.
+
+```typescript
+new CostReport(stack, 'MyCostReport', {
+  enableDefaultUniqueReportName: true,
+});
+```
+
 ### Additional Notes
 
 The construct automatically handles the permissions required for AWS billing services to access the S3 bucket.

src/aws-cur/README.md

@@ -1,4 +1,4 @@
-import { Resource, Stack, Token, aws_cur, aws_iam, aws_s3 } from 'aws-cdk-lib';
+import { Names, Resource, Stack, Token, aws_cur, aws_iam, aws_s3 } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 
 /**
@@ -55,10 +55,28 @@ export class CurFormat {
  * Properties for defining a Cost and Usage Report.
  */
 export interface CostReportProps {
+  /**
+   * Whether to generate a unique report name automatically if the `costReportName` property
+   * is not specified.
+   *
+   * The default value of the `costReportName` is normally ‘default-cur’, but setting this flag
+   * to true will generate a unique default value.
+   *
+   * This flag is ignored if the `costReportName` property is specified.
+   *
+   * @default false
+   */
+  readonly enableDefaultUniqueReportName?: boolean;
+
   /**
    * The name of the cost report.
    *
-   * @default - 'default-cur'
+   * The name must be unique, is case sensitive, and can't include spaces.
+   *
+   * The length of this name must be between 1 and 256.
+   *
+   * @default - a unique name automatically generated if `enableDefaultUniqueReportName` is
+   * true, otherwise 'default-cur'.
    */
   readonly costReportName?: string;
 
@@ -99,6 +117,8 @@ export interface CostReportProps {
 export class CostReport extends Resource {
   /** The S3 bucket that stores the cost report */
   public readonly reportBucket: aws_s3.IBucket;
+  /** The name of the cost report */
+  public readonly costReportName: string;
 
   constructor(scope: Construct, id: string, props: CostReportProps) {
     super(scope, id);
@@ -137,11 +157,33 @@ export class CostReport extends Resource {
 
     const format = props.format ?? CurFormat.TEXT_OR_CSV;
 
+    if (props.costReportName !== undefined && !Token.isUnresolved(props.costReportName)) {
+      if (props.costReportName.length < 1 || props.costReportName.length > 256) {
+        throw new Error(
+          `'costReportName' must be between 1 and 256 characters long, got: ${props.costReportName.length}`,
+        );
+      }
+      if (!/^[0-9A-Za-z!\-_.*'()]+$/.test(props.costReportName)) {
+        throw new Error(
+          `'costReportName' must only contain alphanumeric characters and the following special characters: !-_.*'(), got: '${props.costReportName}'`,
+        );
+      }
+    }
+
+    const reportName =
+      props.costReportName ??
+      (props.enableDefaultUniqueReportName
+        ? Names.uniqueResourceName(this, {
+            maxLength: 256,
+            allowedSpecialCharacters: "!-_.*'()",
+          })
+        : 'default-cur');
+
     const reportDefinition = this.createReportDefinition(this, 'Resource', {
       compression: format.compression,
       format: format.format,
       refreshClosedReports: false,
-      reportName: props.costReportName ?? 'default-cur',
+      reportName,
       reportVersioning: 'CREATE_NEW_REPORT',
       s3Bucket: this.reportBucket.bucketName,
       s3Prefix: 'reports',
@@ -150,6 +192,8 @@ export class CostReport extends Resource {
       additionalSchemaElements: ['RESOURCES'],
     });
     reportDefinition.node.addDependency(this.reportBucket.policy!);
+
+    this.costReportName = reportDefinition.ref;
   }
 
   protected createReportBucket(scope: Construct, id: string, props: aws_s3.BucketProps): aws_s3.IBucket {

src/aws-cur/cost-report.ts

@@ -111,6 +111,84 @@ describe('CostReport', () => {
     template.resourceCountIs('AWS::CUR::ReportDefinition', 2);
   });
 
+  test('unique report name is generated if costReportName is not specified and enableDefaultUniqueReportName is true', () => {
+    new CostReport(stack, 'MyCostReport', {
+      enableDefaultUniqueReportName: true,
+    });
+
+    const template = Template.fromStack(stack);
+
+    template.hasResourceProperties('AWS::CUR::ReportDefinition', {
+      ReportName: 'TestStackMyCostReportF831D765',
+    });
+  });
+
+  test('fixed report name is generated if costReportName is not specified and enableDefaultUniqueReportName is false', () => {
+    new CostReport(stack, 'MyCostReport', {
+      enableDefaultUniqueReportName: false,
+    });
+
+    const template = Template.fromStack(stack);
+
+    template.hasResourceProperties('AWS::CUR::ReportDefinition', {
+      ReportName: 'default-cur',
+    });
+  });
+
+  test('report name can be specified even if enableDefaultUniqueReportName is true', () => {
+    new CostReport(stack, 'MyCostReport', {
+      enableDefaultUniqueReportName: true,
+      costReportName: 'custom-cur',
+    });
+
+    const template = Template.fromStack(stack);
+
+    template.hasResourceProperties('AWS::CUR::ReportDefinition', {
+      ReportName: 'custom-cur',
+    });
+  });
+
+  test('report name can have special characters', () => {
+    new CostReport(stack, 'Report', {
+      costReportName: "report1!-_.*'()",
+    });
+
+    const template = Template.fromStack(stack);
+
+    template.hasResourceProperties('AWS::CUR::ReportDefinition', {
+      ReportName: "report1!-_.*'()",
+    });
+  });
+
+  test('throws if the report name has spaces', () => {
+    expect(
+      () =>
+        new CostReport(stack, 'MyCostReport', {
+          costReportName: 'report with spaces',
+        }),
+    ).toThrow(
+      "'costReportName' must only contain alphanumeric characters and the following special characters: !-_.*'(), got: 'report with spaces'",
+    );
+  });
+
+  test('throws if the length of the report name is greater than 256 characters', () => {
+    expect(
+      () =>
+        new CostReport(stack, 'MyCostReport', {
+          costReportName: 'a'.repeat(257),
+        }),
+    ).toThrow("'costReportName' must be between 1 and 256 characters long, got: 257");
+  });
+
+  test('throws if the length of the report name is less than 1 character', () => {
+    expect(
+      () =>
+        new CostReport(stack, 'MyCostReport', {
+          costReportName: '',
+        }),
+    ).toThrow("'costReportName' must be between 1 and 256 characters long, got: 0");
+  });
+
   test('regions other than us-east-1', () => {
     const regionOtherStack = new Stack(app, 'OtherRegionStack', {
       env: { region: 'ap-northeast-1' },

test/aws-cur/cost-report.test.ts

@@ -13,9 +13,20 @@ class CostReportStack extends cdk.Stack {
       blockPublicAccess: cdk.aws_s3.BlockPublicAccess.BLOCK_ALL,
     });
 
-    new ocf.aws_cur.CostReport(this, 'CostReport', {
+    const report = new ocf.aws_cur.CostReport(this, 'CostReport', {
       bucket,
     });
+    const reportWithUniqueReportName = new ocf.aws_cur.CostReport(this, 'CostReportWithUniqueReportName', {
+      bucket,
+      enableDefaultUniqueReportName: true,
+    });
+
+    new cdk.CfnOutput(this, 'CostReportName', {
+      value: report.costReportName,
+    });
+    new cdk.CfnOutput(this, 'UniqueCostReportName', {
+      value: reportWithUniqueReportName.costReportName,
+    });
   }
 }
 

test/aws-cur/integ.cost-report.ts

@@ -15,15 +15,15 @@
         }
       }
     },
-    "ea273a55939f3c24361eca95307fd8752c4fee982b66f7fd4716f69bd89a7ed3": {
+    "a019b27bb46cfc5076913cf39dac56a1e51b11dcdc8521cf57b88a9c8d2b0f32": {
       "source": {
         "path": "cur-report.template.json",
         "packaging": "file"
       },
       "destinations": {
         "current_account-us-east-1": {
           "bucketName": "cdk-hnb659fds-assets-${AWS::AccountId}-us-east-1",
-          "objectKey": "ea273a55939f3c24361eca95307fd8752c4fee982b66f7fd4716f69bd89a7ed3.json",
+          "objectKey": "a019b27bb46cfc5076913cf39dac56a1e51b11dcdc8521cf57b88a9c8d2b0f32.json",
           "region": "us-east-1",
           "assumeRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-file-publishing-role-${AWS::AccountId}-us-east-1"
         }

test/aws-cur/integ.cost-report.ts.snapshot/cur-report.assets.json

@@ -251,6 +251,40 @@
    "DependsOn": [
     "ReportBucketPolicyA15D85AD"
    ]
+  },
+  "CostReportWithUniqueReportName449C5FC3": {
+   "Type": "AWS::CUR::ReportDefinition",
+   "Properties": {
+    "AdditionalSchemaElements": [
+     "RESOURCES"
+    ],
+    "Compression": "GZIP",
+    "Format": "textORcsv",
+    "RefreshClosedReports": false,
+    "ReportName": "cur-reportCostReportWithUniqueReportName82909F43",
+    "ReportVersioning": "CREATE_NEW_REPORT",
+    "S3Bucket": {
+     "Ref": "ReportBucket577F0FCD"
+    },
+    "S3Prefix": "reports",
+    "S3Region": "us-east-1",
+    "TimeUnit": "HOURLY"
+   },
+   "DependsOn": [
+    "ReportBucketPolicyA15D85AD"
+   ]
+  }
+ },
+ "Outputs": {
+  "CostReportName": {
+   "Value": {
+    "Ref": "CostReport0C3566A0"
+   }
+  },
+  "UniqueCostReportName": {
+   "Value": {
+    "Ref": "CostReportWithUniqueReportName449C5FC3"
+   }
   }
  },
  "Parameters": {

test/aws-cur/integ.cost-report.ts.snapshot/cur-report.template.json

@@ -18,7 +18,7 @@
         "validateOnSynth": false,
         "assumeRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-deploy-role-${AWS::AccountId}-us-east-1",
         "cloudFormationExecutionRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-cfn-exec-role-${AWS::AccountId}-us-east-1",
-        "stackTemplateAssetObjectUrl": "s3://cdk-hnb659fds-assets-${AWS::AccountId}-us-east-1/ea273a55939f3c24361eca95307fd8752c4fee982b66f7fd4716f69bd89a7ed3.json",
+        "stackTemplateAssetObjectUrl": "s3://cdk-hnb659fds-assets-${AWS::AccountId}-us-east-1/a019b27bb46cfc5076913cf39dac56a1e51b11dcdc8521cf57b88a9c8d2b0f32.json",
         "requiresBootstrapStackVersion": 6,
         "bootstrapStackVersionSsmParameter": "/cdk-bootstrap/hnb659fds/version",
         "additionalDependencies": [
@@ -70,6 +70,24 @@
             "data": "CostReport0C3566A0"
           }
         ],
+        "/cur-report/CostReportWithUniqueReportName/Resource": [
+          {
+            "type": "aws:cdk:logicalId",
+            "data": "CostReportWithUniqueReportName449C5FC3"
+          }
+        ],
+        "/cur-report/CostReportName": [
+          {
+            "type": "aws:cdk:logicalId",
+            "data": "CostReportName"
+          }
+        ],
+        "/cur-report/UniqueCostReportName": [
+          {
+            "type": "aws:cdk:logicalId",
+            "data": "UniqueCostReportName"
+          }
+        ],
         "/cur-report/BootstrapVersion": [
           {
             "type": "aws:cdk:logicalId",