feat: add addMetadata() method to Stack (#22337)

Encapsulates the logic of adding metadata to a stack, which eventually ends up in the `Metadata` section of the CloudFormation template.

----

### All Submissions:

* [x] Have you followed the guidelines in our [Contributing guide?](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md)

### Adding new Unconventional Dependencies:

* [ ] This PR adds new unconventional dependencies following the process described [here](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md/#adding-new-unconventional-dependencies)

### New Features

* [ ] Have you added the new feature to an [integration test](https://github.com/aws/aws-cdk/blob/main/INTEGRATION_TESTS.md)?
	* [ ] Did you use `yarn integ` to deploy the infrastructure and generate the snapshot (i.e. `yarn integ` without `--dry-run`)?

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

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

@@ -730,6 +730,19 @@ export class Stack extends Construct implements ITaggable {
     this.templateOptions.transforms.push(transform);
   }
 
+  /**
+   * Adds an arbitary key-value pair, with information you want to record about the stack.
+   * These get translated to the Metadata section of the generated template.
+   *
+   * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/metadata-section-structure.html
+   */
+  public addMetadata(key: string, value: any) {
+    if (!this.templateOptions.metadata) {
+      this.templateOptions.metadata = {};
+    }
+    this.templateOptions.metadata[key] = value;
+  }
+
   /**
    * Called implicitly by the `addDependency` helper function in order to
    * realize a dependency between two top-level stacks at the assembly level.

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

@@ -1263,6 +1263,21 @@ describe('regionalFact', () => {
       },
     });
   });
+
+  test('stack.addMetadata() adds metadata', () => {
+    const stack = new Stack();
+
+    stack.addMetadata('Instances', { Description: 'Information about the instances' });
+    stack.addMetadata('Databases', { Description: 'Information about the databases' } );
+
+    expect(toCloudFormation(stack)).toEqual({
+      Metadata: {
+        Instances: { Description: 'Information about the instances' },
+        Databases: { Description: 'Information about the databases' },
+      },
+    });
+  });
+
 });
 
 class StackWithPostProcessor extends Stack {