feat(ecs): support version stages and ids for Secrets (#18174)

Adds a new `Secret.fromSecretsManagerVersion` method that allows a stage or id to be provided. It will then be added to the secret string handed over to ECS.

fixes #18123

----

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

Author: hoegertn

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

@@ -427,6 +427,7 @@ const newContainer = taskDefinition.addContainer('container', {
   secrets: { // Retrieved from AWS Secrets Manager or AWS Systems Manager Parameter Store at container start-up.
     SECRET: ecs.Secret.fromSecretsManager(secret),
     DB_PASSWORD: ecs.Secret.fromSecretsManager(dbSecret, 'password'), // Reference a specific JSON field, (requires platform version 1.4.0 or later for Fargate tasks)
+    API_KEY: ecs.Secret.fromSecretsManagerVersion(secret, { versionId: '12345' }, 'apiKey'), // Reference a specific version of the secret by its version id or version stage (requires platform version 1.4.0 or later for Fargate tasks)
     PARAMETER: ecs.Secret.fromSsmParameter(parameter),
   },
 });

packages/@aws-cdk/aws-ecs/lib/container-definition.ts

@@ -14,6 +14,24 @@ import { LogDriver, LogDriverConfig } from './log-drivers/log-driver';
 // eslint-disable-next-line no-duplicate-imports, import/order
 import { Construct as CoreConstruct } from '@aws-cdk/core';
 
+/**
+ * Specify the secret's version id or version stage
+ */
+export interface SecretVersionInfo {
+  /**
+   * version id of the secret
+   *
+   * @default - use default version id
+   */
+  readonly versionId?: string;
+  /**
+   * version stage of the secret
+   *
+   * @default - use default version stage
+   */
+  readonly versionStage?: string;
+}
+
 /**
  * A secret environment variable.
  */
@@ -47,6 +65,25 @@ export abstract class Secret {
     };
   }
 
+  /**
+   * Creates a environment variable value from a secret stored in AWS Secrets
+   * Manager.
+   *
+   * @param secret the secret stored in AWS Secrets Manager
+   * @param versionInfo the version information to reference the secret
+   * @param field the name of the field with the value that you want to set as
+   * the environment variable value. Only values in JSON format are supported.
+   * If you do not specify a JSON field, then the full content of the secret is
+   * used.
+   */
+  public static fromSecretsManagerVersion(secret: secretsmanager.ISecret, versionInfo: SecretVersionInfo, field?: string): Secret {
+    return {
+      arn: `${secret.secretArn}:${field ?? ''}:${versionInfo.versionStage ?? ''}:${versionInfo.versionId ?? ''}`,
+      hasField: !!field,
+      grantRead: grantee => secret.grantRead(grantee),
+    };
+  }
+
   /**
    * The ARN of the secret
    */

packages/@aws-cdk/aws-ecs/test/container-definition.test.ts

@@ -1261,6 +1261,8 @@ describe('container definition', () => {
       secrets: {
         SECRET: ecs.Secret.fromSecretsManager(secret),
         PARAMETER: ecs.Secret.fromSsmParameter(parameter),
+        SECRET_ID: ecs.Secret.fromSecretsManagerVersion(secret, { versionId: 'version-id' }),
+        SECRET_STAGE: ecs.Secret.fromSecretsManagerVersion(secret, { versionStage: 'version-stage' }),
       },
     });
 
@@ -1298,6 +1300,34 @@ describe('container definition', () => {
                 ],
               },
             },
+            {
+              Name: 'SECRET_ID',
+              ValueFrom: {
+                'Fn::Join': [
+                  '',
+                  [
+                    {
+                      Ref: 'SecretA720EF05',
+                    },
+                    ':::version-id',
+                  ],
+                ],
+              },
+            },
+            {
+              Name: 'SECRET_STAGE',
+              ValueFrom: {
+                'Fn::Join': [
+                  '',
+                  [
+                    {
+                      Ref: 'SecretA720EF05',
+                    },
+                    '::version-stage:',
+                  ],
+                ],
+              },
+            },
           ],
         }),
       ],
@@ -1405,6 +1435,8 @@ describe('container definition', () => {
       memoryLimitMiB: 1024,
       secrets: {
         SECRET_KEY: ecs.Secret.fromSecretsManager(secret, 'specificKey'),
+        SECRET_KEY_ID: ecs.Secret.fromSecretsManagerVersion(secret, { versionId: 'version-id' }, 'specificKey'),
+        SECRET_KEY_STAGE: ecs.Secret.fromSecretsManagerVersion(secret, { versionStage: 'version-stage' }, 'specificKey'),
       },
     });
 
@@ -1427,6 +1459,34 @@ describe('container definition', () => {
                 ],
               },
             },
+            {
+              Name: 'SECRET_KEY_ID',
+              ValueFrom: {
+                'Fn::Join': [
+                  '',
+                  [
+                    {
+                      Ref: 'SecretA720EF05',
+                    },
+                    ':specificKey::version-id',
+                  ],
+                ],
+              },
+            },
+            {
+              Name: 'SECRET_KEY_STAGE',
+              ValueFrom: {
+                'Fn::Join': [
+                  '',
+                  [
+                    {
+                      Ref: 'SecretA720EF05',
+                    },
+                    ':specificKey:version-stage:',
+                  ],
+                ],
+              },
+            },
           ],
         }),
       ],