feat(core): add description to exportValue and `exportStringListV…

…alue` methods (#29150)

### Issue # (if applicable)

Closes #29092.

### Reason for this change

To be able to set the description of the `CfnOutput` created when using `exportValue` and `exportStringListValue`.

### Description of changes

Add property `description` to `ExportValueOptions` interface.

### Description of how you validated changes

Both unit and integ tests

### 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*

packages/@aws-cdk-testing/framework-integ/test/core/test/integ.stack.js.snapshot/Stack.template.json

@@ -1,4 +1,20 @@
 {
+ "Outputs": {
+ "ExportMyExportValue": {
+ "Description": "This is a description for MyExportValue",
+ "Value": "someValue",
+ "Export": {
+ "Name": "MyExportValue"
+ }
+ },
+ "ExportMyExportStringListValue": {
+ "Description": "This is a description for MyExportStringListValue",
+ "Value": "someValue||anotherValue",
+ "Export": {
+ "Name": "MyExportStringListValue"
+ }
+ }
+ },
  "Parameters": {
  "BootstrapVersion": {
  "Type": "AWS::SSM::Parameter::Value<String>",

packages/@aws-cdk-testing/framework-integ/test/core/test/integ.stack.ts

@@ -9,4 +9,13 @@ const app = new cdk.App();
 const stack = new cdk.Stack(app, 'Stack', { terminationProtection: false });
 stack.terminationProtection = true;
 
+stack.exportValue('someValue', {
+ name: 'MyExportValue',
+ description: 'This is a description for MyExportValue',
+});
+stack.exportStringListValue(['someValue', 'anotherValue'], {
+ name: 'MyExportStringListValue',
+ description: 'This is a description for MyExportStringListValue',
+});
+
 new IntegTest(app, 'stack', { testCases: [stack] });

packages/aws-cdk-lib/core/README.md

@@ -836,6 +836,17 @@ new CfnOutput(this, 'OutputName', {
 });
 ```
 
+You can also use the `exportValue` method to export values as stack outputs:
+
+```ts
+declare const stack: Stack;
+
+stack.exportValue(myBucket.bucketName, {
+ name: 'TheAwesomeBucket',
+ description: 'The name of an S3 bucket',
+});
+```
+
 [cfn-stack-output]: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html
 
 ### Parameters

packages/aws-cdk-lib/core/lib/stack.ts

@@ -1204,6 +1204,7 @@ export class Stack extends Construct implements ITaggable {
  new CfnOutput(this, `Export${options.name}`, {
  value: exportedValue,
  exportName: options.name,
+ description: options.description,
  });
  return Fn.importValue(options.name);
  }
@@ -1215,6 +1216,7 @@ export class Stack extends Construct implements ITaggable {
  new CfnOutput(exportsScope, id, {
  value: Token.asString(exportable),
  exportName,
+ description: options.description,
  });
  }
 
@@ -1253,6 +1255,7 @@ export class Stack extends Construct implements ITaggable {
  new CfnOutput(this, `Export${options.name}`, {
  value: Fn.join(STRING_LIST_REFERENCE_DELIMITER, exportedValue),
  exportName: options.name,
+ description: options.description,
  });
  return Fn.split(STRING_LIST_REFERENCE_DELIMITER, Fn.importValue(options.name));
  }
@@ -1268,6 +1271,7 @@ export class Stack extends Construct implements ITaggable {
  // (string lists are invalid)
  value: Fn.join(STRING_LIST_REFERENCE_DELIMITER, Token.asList(exportable)),
  exportName,
+ description: options.description,
  });
  }
 
@@ -1766,6 +1770,13 @@ export interface ExportValueOptions {
  * @default - A name is automatically chosen
  */
  readonly name?: string;
+
+ /**
+ * The description of the outputs
+ *
+ * @default - No description
+ */
+ readonly description?: string;
 }
 
 function count(xs: string[]): Record<string, number> {

packages/aws-cdk-lib/core/test/stack.test.ts

@@ -1489,6 +1489,83 @@ describe('stack', () => {
  });
  });
 
+ test('exports with name can include description', () => {
+ const app = new App();
+ const stack = new Stack(app, 'Stack');
+
+ stack.exportValue('someValue', {
+ name: 'MyExport',
+ description: 'This is a description',
+ });
+
+ const template = app.synth().getStackByName(stack.stackName).template;
+ expect(template).toMatchObject({
+ Outputs: {
+ ExportMyExport: {
+ Description: 'This is a description',
+ },
+ },
+ });
+ });
+
+ test('list exports with name can include description', () => {
+ const app = new App();
+ const stack = new Stack(app, 'Stack');
+
+ stack.exportStringListValue(['someValue', 'anotherValue'], {
+ name: 'MyExport',
+ description: 'This is a description',
+ });
+
+ const template = app.synth().getStackByName(stack.stackName).template;
+ expect(template).toMatchObject({
+ Outputs: {
+ ExportMyExport: {
+ Description: 'This is a description',
+ },
+ },
+ });
+ });
+
+ test('exports without name can include description', () => {
+ const app = new App();
+ const stack = new Stack(app, 'Stack');
+
+ const resource = new CfnResource(stack, 'Resource', { type: 'AWS::Resource' });
+ stack.exportValue(resource.getAtt('Att'), {
+ description: 'This is a description',
+ });
+
+ const template = app.synth().getStackByName(stack.stackName).template;
+ expect(template).toMatchObject({
+ Outputs: {
+ ExportsOutputFnGetAttResourceAttB5968E71: {
+ Description: 'This is a description',
+ },
+ },
+ });
+ });
+
+ test('list exports without name can include description', () => {
+ const app = new App();
+ const stack = new Stack(app, 'Stack');
+
+ const resource = new CfnResource(stack, 'Resource', { type: 'AWS::Resource' });
+ (resource as any).attrAtt = ['Foo', 'Bar'];
+ stack.exportStringListValue(resource.getAtt('Att', ResolutionTypeHint.STRING_LIST), {
+ description: 'This is a description',
+ });
+
+ const template = app.synth().getStackByName(stack.stackName).template;
+ expect(template).toMatchObject({
+ Outputs: {
+ ExportsOutputFnGetAttResourceAttB5968E71: {
+ Description: 'This is a description',
+ },
+ },
+ });
+ });
+
  test('CfnSynthesisError is ignored when preparing cross references', () => {
  // GIVEN
  const app = new App();