feat(ssm): allow disabling context caching in valueFromLookup

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

@@ -99,6 +99,20 @@ const arnLookup = ssm.StringParameter.valueFromLookup(this, '/my/role/arn');
 iam.Role.fromRoleArn(this, 'role', Lazy.string({ produce: () => arnLookup }));
 ```
 
+
+#### Enhanced Control over Context Caching
+
+The `ssm.StringParameter.valueFromLookup` method in AWS CDK supports an optional `disableContextCaching` flag, allowing developers to control the caching of context values fetched from AWS SSM Parameter Store. This feature is aimed at providing flexibility for scenarios where parameters may frequently change or when ensuring the freshness of data is critical.
+
+```ts
+const parameterValue = ssm.StringParameter.valueFromLookup(this, 'parameterName', {
+  disableContextCaching: true,
+});
+```
+
+Setting `disableContextCaching` to `true` bypasses the default caching mechanism, ensuring the parameter value is retrieved directly from the source on each synthesis. 
+
+
 ## Creating new SSM Parameters in your CDK app
 
 You can create either `ssm.StringParameter` or `ssm.StringListParameter`s in

packages/aws-cdk-lib/aws-ssm/lib/parameter.ts

@@ -6,7 +6,7 @@ import * as kms from '../../aws-kms';
 import * as cxschema from '../../cloud-assembly-schema';
 import {
   CfnDynamicReference, CfnDynamicReferenceService, CfnParameter,
-  ContextProvider, Fn, IResource, Resource, Stack, Token,
+  ContextProvider, ContextProviderConfig, Fn, IResource, Resource, Stack, Token,
   Tokenization,
 } from '../../core';
 
@@ -532,11 +532,12 @@ export class StringParameter extends ParameterBase implements IStringParameter {
    * Requires that the stack this scope is defined in will have explicit
    * account/region information. Otherwise, it will fail during synthesis.
    */
-  public static valueFromLookup(scope: Construct, parameterName: string): string {
+  public static valueFromLookup(scope: Construct, parameterName: string, contextOpts?: ContextProviderConfig): string {
     const value = ContextProvider.getValue(scope, {
       provider: cxschema.ContextProvider.SSM_PARAMETER_PROVIDER,
       props: { parameterName },
       dummyValue: `dummy-value-for-${parameterName}`,
+      disableContextCaching: contextOpts?.disableContextCaching,
     }).value;
 
     return value;

packages/aws-cdk-lib/aws-ssm/test/parameter.test.ts

@@ -1,6 +1,10 @@
 /* eslint-disable max-len */
 
 import { testDeprecated } from '@aws-cdk/cdk-build-tools';
+import { Deployments } from '../../../aws-cdk/lib/api/deployments';
+import { CdkToolkit } from '../../../aws-cdk/lib/cdk-toolkit';
+import { Configuration, TRANSIENT_CONTEXT_KEY } from '../../../aws-cdk/lib/settings';
+import { MockCloudExecutable } from '../../../aws-cdk/test/util';
 import { Template } from '../../assertions';
 import * as iam from '../../aws-iam';
 import * as kms from '../../aws-kms';
@@ -652,6 +656,160 @@ test('fromLookup will use the SSM context provider to read value during synthesi
   ]);
 });
 
+test('fromLookup will persist value in context by default', async () => {
+  // GIVEN
+  const ssmKey = 'ssm:account=12344:parameterName=my-param-name:region=us-east-1';
+  const app = new cdk.App({ context: { [cxapi.NEW_STYLE_STACK_SYNTHESIS_CONTEXT]: false } });
+  const stack = new cdk.Stack(app, 'my-staq', { env: { region: 'us-east-1', account: '12344' } });
+
+  // WHEN
+  const value = ssm.StringParameter.valueFromLookup(stack, 'my-param-name');
+
+  const synth = app.synth();
+
+  const mockCloudExecutable = new MockCloudExecutable({
+    stacks: synth.stacks,
+    missing: synth.manifest.missing,
+  });
+
+  let requestedParameterName: string | undefined;
+  mockCloudExecutable.sdkProvider.stubSSM({
+    getParameter(request) {
+      requestedParameterName = request.Name;
+      return {
+        Parameter: {
+          Value: 'new-value',
+        },
+      };
+    },
+  });
+
+  const cdkToolkit = new CdkToolkit({
+    cloudExecutable: mockCloudExecutable,
+    configuration: mockCloudExecutable.configuration,
+    sdkProvider: mockCloudExecutable.sdkProvider,
+    deployments: new Deployments({ sdkProvider: mockCloudExecutable.sdkProvider }),
+  });
+
+  await mockCloudExecutable.configuration.load();
+  mockCloudExecutable.configuration.context.set = jest.fn(mockCloudExecutable.configuration.context.set);
+
+  await cdkToolkit.assembly();
+
+  await mockCloudExecutable.configuration.saveContext();
+  const configAfterSave = await new Configuration({ readUserContext: false }).load();
+
+  // THEN
+  expect(value).toEqual('dummy-value-for-my-param-name');
+  expect(requestedParameterName).toEqual('my-param-name');
+  expect(mockCloudExecutable.configuration.context.set).toHaveBeenCalledWith(ssmKey, 'new-value');
+  expect(configAfterSave.context.get(ssmKey)).toEqual('new-value');
+});
+
+test('fromLookup with disableContextCaching: true will not persist value in context', async () => {
+  // GIVEN
+  const app = new cdk.App({ context: { [cxapi.NEW_STYLE_STACK_SYNTHESIS_CONTEXT]: false } });
+  const stack = new cdk.Stack(app, 'my-staq', { env: { region: 'us-east-1', account: '12344' } });
+  const ssmKey = 'ssm:account=12344:parameterName=my-param-name:region=us-east-1';
+
+  // WHEN
+  const value = ssm.StringParameter.valueFromLookup(stack, 'my-param-name', { disableContextCaching: true });
+
+  const synth = app.synth();
+
+  const mockCloudExecutable = new MockCloudExecutable({
+    stacks: synth.stacks,
+    missing: synth.manifest.missing,
+  });
+
+  let requestedParameterName: string | undefined;
+  mockCloudExecutable.sdkProvider.stubSSM({
+    getParameter(request) {
+      requestedParameterName = request.Name;
+      return {
+        Parameter: {
+          Value: '123',
+        },
+      };
+    },
+  });
+
+  const cdkToolkit = new CdkToolkit({
+    cloudExecutable: mockCloudExecutable,
+    configuration: mockCloudExecutable.configuration,
+    sdkProvider: mockCloudExecutable.sdkProvider,
+    deployments: new Deployments({ sdkProvider: mockCloudExecutable.sdkProvider }),
+  });
+
+  await mockCloudExecutable.configuration.load();
+
+  // spy on context set function
+  mockCloudExecutable.configuration.context.set = jest.fn(mockCloudExecutable.configuration.context.set);
+
+  await cdkToolkit.assembly();
+
+  await mockCloudExecutable.configuration.saveContext();
+  const configAfterSave = await new Configuration({ readUserContext: false }).load();
+
+  // THEN
+  expect(value).toEqual('dummy-value-for-my-param-name');
+  expect(requestedParameterName).toEqual('my-param-name');
+  expect(mockCloudExecutable.configuration.context.set).toHaveBeenCalledWith(ssmKey, '123');
+  expect(mockCloudExecutable.configuration.context.set).toHaveBeenCalledWith(ssmKey + TRANSIENT_CONTEXT_KEY, { [TRANSIENT_CONTEXT_KEY]: true });
+  expect(configAfterSave.context.keys).toHaveLength(0);
+});
+
+test('fromLookup with disableContextCaching: true will use previously cached value', async () => {
+  // GIVEN
+  const app = new cdk.App({ context: { [cxapi.NEW_STYLE_STACK_SYNTHESIS_CONTEXT]: false } });
+  const ssmKey = 'ssm:account=12344:parameterName=my-param-name:region=us-east-1';
+  app.node.setContext(ssmKey, 'cached-value');
+
+  const stack = new cdk.Stack(app, 'my-staq', { env: { region: 'us-east-1', account: '12344' } });
+
+  // WHEN
+  const value = ssm.StringParameter.valueFromLookup(stack, 'my-param-name', { disableContextCaching: true });
+
+  const synth = app.synth();
+
+  const mockCloudExecutable = new MockCloudExecutable({
+    stacks: synth.stacks,
+    missing: synth.manifest.missing,
+  });
+
+  let requestedParameterName: string | undefined;
+  mockCloudExecutable.sdkProvider.stubSSM({
+    getParameter(request) {
+      requestedParameterName = request.Name;
+      return {
+        Parameter: {
+          Value: 'new-value',
+        },
+      };
+    },
+  });
+
+  const cdkToolkit = new CdkToolkit({
+    cloudExecutable: mockCloudExecutable,
+    configuration: mockCloudExecutable.configuration,
+    sdkProvider: mockCloudExecutable.sdkProvider,
+    deployments: new Deployments({ sdkProvider: mockCloudExecutable.sdkProvider }),
+  });
+
+  await mockCloudExecutable.configuration.load();
+
+  // spy on context set function
+  mockCloudExecutable.configuration.context.set = jest.fn(mockCloudExecutable.configuration.context.set);
+
+  await cdkToolkit.assembly();
+  await mockCloudExecutable.configuration.saveContext();
+
+  // THEN
+  expect(value).toEqual('cached-value');
+  expect(requestedParameterName).toEqual(undefined);
+  expect(mockCloudExecutable.configuration.context.set).not.toHaveBeenCalled();
+});
+
 describe('from string list parameter', () => {
   testDeprecated('valueForTypedStringParameter list type throws error', () => {
     // GIVEN

packages/aws-cdk-lib/cloud-assembly-schema/lib/cloud-assembly/schema.ts

@@ -60,6 +60,13 @@ export interface MissingContext {
    * A set of provider-specific options.
    */
   readonly props: ContextQueryProperties;
+
+  /**
+   * Whether to disable persisting this to the context file.
+   *
+   * @default false
+   */
+  readonly disableContextCaching?: boolean;
 }
 
 /**

packages/aws-cdk-lib/cloud-assembly-schema/schema/cloud-assembly.schema.json

@@ -482,6 +482,11 @@
                 "props": {
                     "$ref": "#/definitions/ContextQueryProperties",
                     "description": "A set of provider-specific options."
+                },
+                "disableContextCaching": {
+                    "description": "Whether to disable persisting this to the context file.",
+                    "default": false,
+                    "type": "boolean"
                 }
             },
             "required": [

packages/aws-cdk-lib/cloud-assembly-schema/schema/cloud-assembly.version.json

@@ -1 +1 @@
-{"version":"36.0.0"}
+{"version":"37.0.0"}

packages/aws-cdk-lib/core/lib/context-provider.ts

@@ -27,8 +27,20 @@ export interface GetContextKeyOptions {
 }
 
 /**
+ * Configuration options for context providers.
  */
-export interface GetContextValueOptions extends GetContextKeyOptions {
+export interface ContextProviderConfig {
+  /**
+   * Whether caching the value to the context is disabled.
+   *
+   * @default false
+   */
+  readonly disableContextCaching?: boolean;
+}
+
+/**
+ */
+export interface GetContextValueOptions extends GetContextKeyOptions, ContextProviderConfig {
   /**
    * The value to return if the context value was not found and a missing
    * context is reported. This should be a dummy value that should preferably
@@ -105,6 +117,7 @@ export class ContextProvider {
         key,
         provider: options.provider as cxschema.ContextProvider,
         props: props as cxschema.ContextQueryProperties,
+        disableContextCaching: options.disableContextCaching,
       });
 
       if (providerError !== undefined) {

packages/aws-cdk/lib/context-providers/index.ts

@@ -69,6 +69,11 @@ export async function provideContextValues(
       }, resolvedEnvironment, sdk);
 
       value = await provider.getValue({ ...missingContext.props, lookupRoleArn: arns.lookupRoleArn });
+
+      if (missingContext.disableContextCaching) {
+        debug(`Skipping context caching for ${key}`);
+        context.set(key + TRANSIENT_CONTEXT_KEY, { [TRANSIENT_CONTEXT_KEY]: true });
+      }
     } catch (e: any) {
       // Set a specially formatted provider value which will be interpreted
       // as a lookup failure in the toolkit.

packages/aws-cdk/lib/settings.ts

@@ -458,7 +458,7 @@ function expandHomeDir(x: string) {
 function stripTransientValues(obj: {[key: string]: any}) {
   const ret: any = {};
   for (const [key, value] of Object.entries(obj)) {
-    if (!isTransientValue(value)) {
+    if (!isTransientValue(value) && !isTransientValue(obj[key + TRANSIENT_CONTEXT_KEY])) {
       ret[key] = value;
     }
   }

packages/aws-cdk/test/context.test.ts

@@ -137,3 +137,18 @@ test('transient values arent saved to disk', async () => {
   // THEN
   expect(config2.context.get('some_key')).toEqual(undefined);
 });
+
+test('transient keys arent saved to disk', async () => {
+  // GIVEN
+  const config1 = await new Configuration({ readUserContext: false }).load();
+  config1.context.set('some_key', 'some_value');
+  config1.context.set('some_key' + TRANSIENT_CONTEXT_KEY, { [TRANSIENT_CONTEXT_KEY]: true });
+  await config1.saveContext();
+  expect(config1.context.get('some_key')).toEqual('some_value');
+
+  // WHEN
+  const config2 = await new Configuration({ readUserContext: false }).load();
+
+  // THEN
+  expect(config2.context.get('some_key')).toEqual(undefined);
+});