feat(apigatewayv2): add stage variables support for HTTP and WebSocket API (#34548)

### Issue # 

Closes #11818 .

### Reason for this change

To support stage variables to HttpApi & WebSocketApi.

### Description of changes

Add `stageVariables` property to `WebSocketStage` & `HttpStage`.
 
### Describe any new or updated permissions being added

N/A


### Description of how you validated changes

* Add a unit test
* Tested it manually by creating stack to use the new props and check the CF template & UI
* 
### 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*

Author: gasolima

packages/aws-cdk-lib/aws-apigatewayv2/lib/common/base.ts

@@ -30,6 +30,7 @@ export abstract class ApiBase extends Resource implements IApi {
  * @internal
  */
 export abstract class StageBase extends Resource implements IStage {
+  private stageVariables: { [key: string]: string } = {};
   public abstract readonly stageName: string;
   protected abstract readonly baseApi: IApi;
 
@@ -87,4 +88,16 @@ export abstract class StageBase extends Resource implements IStage {
       dimensionsMap: { ApiId: this.baseApi.apiId, Stage: this.stageName },
     }).attachTo(this);
   }
+
+  public addStageVariable(name: string, value: string) {
+    this.stageVariables[name] = value;
+  }
+
+  /**
+   * Returns the stage variables for this stage.
+   * @internal
+   */
+  protected get _stageVariables(): { [key: string]: string } | undefined {
+    return Object.keys(this.stageVariables).length > 0 ? { ...this.stageVariables } : undefined;
+  }
 }

packages/aws-cdk-lib/aws-apigatewayv2/lib/common/stage.ts

@@ -25,6 +25,16 @@ export interface IStage extends IResource {
    * @default - average over 5 minutes
    */
   metric(metricName: string, props?: MetricOptions): Metric;
+
+  /**
+   * Adds a stage variable to this stage.
+   *
+   * @param name The name of the stage variable.
+   * @param value The value of the stage variable.
+   *
+   * The allowed characters for variable names and the required pattern for variable values are specified here: https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-apigateway-stage.html#cfn-apigateway-stage-variables
+   */
+  addStageVariable(name: string, value: string): void;
 }
 
 /**
@@ -89,6 +99,16 @@ export interface StageOptions {
    * @default - No access logging
    */
   readonly accessLogSettings?: IAccessLogSettings;
+
+  /**
+   * Stage variables for the stage.
+   * These are key-value pairs that you can define and use in your API routes.
+   *
+   * The allowed characters for variable names and the required pattern for variable values are specified here: https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-apigateway-stage.html#cfn-apigateway-stage-variables
+   *
+   * @default - No stage variables
+   */
+  readonly stageVariables?: { [key: string]: string };
 }
 
 /**

packages/aws-cdk-lib/aws-apigatewayv2/lib/http/stage.ts

@@ -2,7 +2,7 @@ import { Construct } from 'constructs';
 import { IHttpApi } from './api';
 import { CfnStage } from '.././index';
 import { Metric, MetricOptions } from '../../../aws-cloudwatch';
-import { Stack } from '../../../core';
+import { Lazy, Stack } from '../../../core';
 import { ValidationError } from '../../../core/lib/errors';
 import { addConstructMetadata } from '../../../core/lib/metadata-resource';
 import { propertyInjectable } from '../../../core/lib/prop-injectable';
@@ -172,6 +172,12 @@ export class HttpStage extends HttpStageBase {
     // Enhanced CDK Analytics Telemetry
     addConstructMetadata(this, props);
 
+    if (props.stageVariables) {
+      Object.entries(props.stageVariables).forEach(([key, value]) => {
+        this.addStageVariable(key, value);
+      });
+    }
+
     new CfnStage(this, 'Resource', {
       apiId: props.httpApi.apiId,
       stageName: this.physicalName,
@@ -183,6 +189,7 @@ export class HttpStage extends HttpStageBase {
         detailedMetricsEnabled: props.detailedMetricsEnabled,
       } : undefined,
       description: props.description,
+      stageVariables: Lazy.any({ produce: () => this._stageVariables }),
     });
 
     this.stageName = this.physicalName;

packages/aws-cdk-lib/aws-apigatewayv2/lib/websocket/stage.ts

@@ -2,7 +2,7 @@ import { Construct } from 'constructs';
 import { IWebSocketApi } from './api';
 import { CfnStage } from '.././index';
 import { Grant, IGrantable } from '../../../aws-iam';
-import { Stack } from '../../../core';
+import { Lazy, Stack } from '../../../core';
 import { ValidationError } from '../../../core/lib/errors';
 import { addConstructMetadata, MethodMetadata } from '../../../core/lib/metadata-resource';
 import { propertyInjectable } from '../../../core/lib/prop-injectable';
@@ -92,6 +92,12 @@ export class WebSocketStage extends StageBase implements IWebSocketStage {
     // Enhanced CDK Analytics Telemetry
     addConstructMetadata(this, props);
 
+    if (props.stageVariables) {
+      Object.entries(props.stageVariables).forEach(([key, value]) => {
+        this.addStageVariable(key, value);
+      });
+    }
+
     this.baseApi = props.webSocketApi;
     this.api = props.webSocketApi;
     this.stageName = this.physicalName;
@@ -106,6 +112,7 @@ export class WebSocketStage extends StageBase implements IWebSocketStage {
         detailedMetricsEnabled: props.detailedMetricsEnabled,
       } : undefined,
       description: props.description,
+      stageVariables: Lazy.any({ produce: () => this._stageVariables }),
     });
 
     if (props.domainMapping) {

packages/aws-cdk-lib/aws-apigatewayv2/test/http/stage.test.ts

@@ -256,6 +256,27 @@ describe('HttpStage', () => {
       })).not.toThrow();
     });
   });
+  test('can add stage variables after creation', () => {
+    // WHEN
+    const stage = new HttpStage(stack, 'DefaultStage', {
+      httpApi: api,
+      stageVariables: {
+        env: 'prod',
+      },
+    });
+
+    stage.addStageVariable('timeout', '300');
+
+    // THEN
+    Template.fromStack(stack).hasResourceProperties('AWS::ApiGatewayV2::Stage', {
+      ApiId: stack.resolve(api.apiId),
+      StageName: '$default',
+      StageVariables: {
+        env: 'prod',
+        timeout: '300',
+      },
+    });
+  });
 });
 
 describe('HttpStage with domain mapping', () => {

packages/aws-cdk-lib/aws-apigatewayv2/test/websocket/stage.test.ts

@@ -179,4 +179,27 @@ describe('WebSocketStage', () => {
       Description: 'My Stage',
     });
   });
+
+  test('can add stage variables after creation', () => {
+    // WHEN
+    const stage = new WebSocketStage(stack, 'DefaultStage', {
+      webSocketApi: api,
+      stageName: 'dev',
+      stageVariables: {
+        env: 'dev',
+      },
+    });
+
+    stage.addStageVariable('timeout', '600');
+
+    // THEN
+    Template.fromStack(stack).hasResourceProperties('AWS::ApiGatewayV2::Stage', {
+      ApiId: stack.resolve(api.apiId),
+      StageName: 'dev',
+      StageVariables: {
+        env: 'dev',
+        timeout: '600',
+      },
+    });
+  });
 });