@aws/nx-plugin 1.0.0-rc.31 → 1.0.0-rc.33

package/src/utils/agent-core-constructs/files/terraform/core/agent-core/runtime.tf.template

@@ -70,6 +70,30 @@ variable "additional_iam_policy_statements" {
   default = []
 }
 
+# VPC Configuration (optional)
+variable "enable_vpc" {
+  description = "Run the agent core runtime inside a VPC. Set alongside vpc_id/subnet_ids."
+  type        = bool
+  default     = false
+}
+
+variable "vpc_id" {
+  description = "VPC ID to run the agent core runtime in. Required when enable_vpc is true."
+  type        = string
+  default     = null
+
+  validation {
+    condition     = !var.enable_vpc || (var.vpc_id != null && var.subnet_ids != null)
+    error_message = "vpc_id and subnet_ids must be set when enable_vpc is true."
+  }
+}
+
+variable "subnet_ids" {
+  description = "Subnet IDs to run the agent core runtime in. Required when enable_vpc is true."
+  type        = list(string)
+  default     = null
+}
+
 variable "tags" {
   description = "Tags to apply to resources"
   type        = map(string)
@@ -305,6 +329,28 @@ resource "null_resource" "docker_publish" {
   depends_on = [aws_ecr_repository_policy.agent_core_ecr_policy]
 }
 
+# Security group for the agent core runtime, used when running inside a VPC
+resource "aws_security_group" "agent_core_runtime" {
+  count = var.enable_vpc ? 1 : 0
+
+  #checkov:skip=CKV2_AWS_5:Attached to the runtime via network_configuration; Checkov cannot resolve this reference
+  name_prefix = "${var.agent_runtime_name}-runtime-"
+  description = "Security group for the ${var.agent_runtime_name} agent core runtime"
+  vpc_id      = var.vpc_id
+  tags        = var.tags
+}
+
+resource "aws_vpc_security_group_egress_rule" "agent_core_runtime_https" {
+  count = var.enable_vpc ? 1 : 0
+
+  security_group_id = aws_security_group.agent_core_runtime[0].id
+  cidr_ipv4         = "0.0.0.0/0"
+  from_port         = 443
+  to_port           = 443
+  ip_protocol       = "tcp"
+  description       = "Allow outbound HTTPS to AWS service endpoints"
+}
+
 # Bedrock AgentCore Agent Runtime
 resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
   agent_runtime_name = "${var.agent_runtime_name}_${random_id.unique_suffix.hex}"
@@ -331,7 +377,15 @@ resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
   }
 
   network_configuration {
-    network_mode = "PUBLIC"
+    network_mode = var.enable_vpc ? "VPC" : "PUBLIC"
+
+    dynamic "network_mode_config" {
+      for_each = var.enable_vpc ? [1] : []
+      content {
+        security_groups = [aws_security_group.agent_core_runtime[0].id]
+        subnets         = var.subnet_ids
+      }
+    }
   }
 
   protocol_configuration {
@@ -433,3 +487,8 @@ output "agent_runtime_version" {
   description = "Version of the Bedrock Agent Core runtime"
   value       = aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_version
 }
+
+output "security_group_id" {
+  description = "Security group ID of the agent core runtime, for use in ingress rules on resources it must reach (e.g. a database). Null unless enable_vpc is true."
+  value       = var.enable_vpc ? aws_security_group.agent_core_runtime[0].id : null
+}

package/src/utils/api-constructs/api-constructs.js

@@ -3,6 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */ import { generateFiles, joinPathFragments, OverwriteStrategy, updateJson } from "@nx/devkit";
 import { addStarExport } from "../ast.js";
+import { esmVars } from "../module-format.js";
 import { addDependencyToTargetIfNotPresent } from "../nx.js";
 import { PACKAGES_DIR, SHARED_CONSTRUCTS_DIR, SHARED_TERRAFORM_DIR } from "../shared-constructs-constants.js";
 import { PY_VERSIONS, terraformProviderVersions } from "../versions.js";
@@ -23,7 +24,9 @@ export const addApiGatewayInfra = async (tree, options)=>{
  * Add an API CDK construct, and update the Runtime Config type to export its url
  */ const addApiGatewayCdkConstructs = async (tree, options)=>{
     const generateCoreApiFile = (name)=>{
-        generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', 'cdk', 'core', 'api', name), joinPathFragments(PACKAGES_DIR, SHARED_CONSTRUCTS_DIR, 'src', 'core', 'api'), {}, {
+        generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', 'cdk', 'core', 'api', name), joinPathFragments(PACKAGES_DIR, SHARED_CONSTRUCTS_DIR, 'src', 'core', 'api'), {
+            ...esmVars(tree)
+        }, {
             overwriteStrategy: OverwriteStrategy.KeepExisting
         });
     };
@@ -34,7 +37,10 @@ export const addApiGatewayInfra = async (tree, options)=>{
         generateCoreApiFile('trpc');
     }
     // Generate app specific CDK construct
-    generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', 'cdk', 'app', 'apis', options.constructType), joinPathFragments(PACKAGES_DIR, SHARED_CONSTRUCTS_DIR, 'src', 'app', 'apis'), options, {
+    generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', 'cdk', 'app', 'apis', options.constructType), joinPathFragments(PACKAGES_DIR, SHARED_CONSTRUCTS_DIR, 'src', 'app', 'apis'), {
+        ...options,
+        ...esmVars(tree)
+    }, {
         overwriteStrategy: OverwriteStrategy.KeepExisting
     });
     // Export app specific CDK construct

package/src/utils/api-constructs/api-constructs.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../packages/nx-plugin/src/utils/api-constructs/api-constructs.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  generateFiles,\n  joinPathFragments,\n  OverwriteStrategy,\n  type ProjectConfiguration,\n  type Tree,\n  updateJson,\n} from '@nx/devkit';\nimport { addStarExport } from '../ast';\nimport type { Iac } from '../iac';\nimport { addDependencyToTargetIfNotPresent } from '../nx';\nimport {\n  PACKAGES_DIR,\n  SHARED_CONSTRUCTS_DIR,\n  SHARED_TERRAFORM_DIR,\n} from '../shared-constructs-constants';\nimport { PY_VERSIONS, terraformProviderVersions } from '../versions';\n\ninterface BackendOptions {\n  type: 'trpc' | 'fastapi' | 'smithy';\n  integrationPattern: 'isolated' | 'shared';\n}\n\nexport interface TrpcBackendOptions extends BackendOptions {\n  type: 'trpc';\n  projectAlias: string;\n  bundleOutputDir: string;\n  authorizerBundleOutputDir?: string;\n}\n\nexport interface FastApiBackendOptions extends BackendOptions {\n  type: 'fastapi';\n  moduleName: string;\n  bundleOutputDir: string;\n}\n\nexport interface SmithyBackendOptions extends BackendOptions {\n  type: 'smithy';\n  bundleOutputDir: string;\n  authorizerBundleOutputDir?: string;\n}\n\nexport interface AddApiGatewayConstructOptions {\n  apiProjectName: string;\n  apiNameClassName: string;\n  apiNameKebabCase: string;\n  constructType: 'http' | 'rest';\n  backend: TrpcBackendOptions | FastApiBackendOptions | SmithyBackendOptions;\n  auth: 'iam' | 'cognito' | 'custom';\n}\n\nexport const addApiGatewayInfra = async (\n  tree: Tree,\n  options: AddApiGatewayConstructOptions & { iac: Iac },\n) => {\n  if (options.iac === 'cdk') {\n    await addApiGatewayCdkConstructs(tree, options);\n  } else if (options.iac === 'terraform') {\n    addApiGatewayTerraformModules(tree, options);\n  } else {\n    throw new Error(`Unsupported iac ${options.iac}`);\n  }\n\n  updateJson(\n    tree,\n    joinPathFragments(\n      PACKAGES_DIR,\n      options.iac === 'cdk' ? SHARED_CONSTRUCTS_DIR : SHARED_TERRAFORM_DIR,\n      'project.json',\n    ),\n    (config: ProjectConfiguration) => {\n      addDependencyToTargetIfNotPresent(\n        config,\n        'build',\n        `${options.apiProjectName}:build`,\n      );\n      return config;\n    },\n  );\n};\n\n/**\n * Add an API CDK construct, and update the Runtime Config type to export its url\n */\nconst addApiGatewayCdkConstructs = async (\n  tree: Tree,\n  options: AddApiGatewayConstructOptions,\n) => {\n  const generateCoreApiFile = (name: string) => {\n    generateFiles(\n      tree,\n      joinPathFragments(\n        import.meta.dirname,\n        'files',\n        'cdk',\n        'core',\n        'api',\n        name,\n      ),\n      joinPathFragments(\n        PACKAGES_DIR,\n        SHARED_CONSTRUCTS_DIR,\n        'src',\n        'core',\n        'api',\n      ),\n      {},\n      {\n        overwriteStrategy: OverwriteStrategy.KeepExisting,\n      },\n    );\n  };\n\n  // Generate relevant core CDK construct and utilities\n  generateCoreApiFile(options.constructType);\n  generateCoreApiFile('utils');\n  if (options.backend.type === 'trpc') {\n    generateCoreApiFile('trpc');\n  }\n\n  // Generate app specific CDK construct\n  generateFiles(\n    tree,\n    joinPathFragments(\n      import.meta.dirname,\n      'files',\n      'cdk',\n      'app',\n      'apis',\n      options.constructType,\n    ),\n    joinPathFragments(\n      PACKAGES_DIR,\n      SHARED_CONSTRUCTS_DIR,\n      'src',\n      'app',\n      'apis',\n    ),\n    options,\n    {\n      overwriteStrategy: OverwriteStrategy.KeepExisting,\n    },\n  );\n\n  // Export app specific CDK construct\n  await addStarExport(\n    tree,\n    joinPathFragments(\n      PACKAGES_DIR,\n      SHARED_CONSTRUCTS_DIR,\n      'src',\n      'app',\n      'apis',\n      'index.ts',\n    ),\n    `./${options.apiNameKebabCase}.js`,\n  );\n  await addStarExport(\n    tree,\n    joinPathFragments(\n      PACKAGES_DIR,\n      SHARED_CONSTRUCTS_DIR,\n      'src',\n      'app',\n      'index.ts',\n    ),\n    './apis/index.js',\n  );\n};\n\n/**\n * Add an API terraform module, and update the Runtime Config type to export its url\n */\nconst addApiGatewayTerraformModules = (\n  tree: Tree,\n  options: AddApiGatewayConstructOptions,\n) => {\n  // Generate core terraform module\n  generateFiles(\n    tree,\n    joinPathFragments(\n      import.meta.dirname,\n      'files',\n      'terraform',\n      'core',\n      'api',\n      options.constructType,\n    ),\n    joinPathFragments(PACKAGES_DIR, SHARED_TERRAFORM_DIR, 'src', 'core', 'api'),\n    { boto3Version: PY_VERSIONS.boto3, ...terraformProviderVersions() },\n    {\n      overwriteStrategy: OverwriteStrategy.KeepExisting,\n    },\n  );\n\n  // Generate app specific terraform module\n  generateFiles(\n    tree,\n    joinPathFragments(\n      import.meta.dirname,\n      'files',\n      'terraform',\n      'app',\n      'apis',\n      options.constructType,\n    ),\n    joinPathFragments(PACKAGES_DIR, SHARED_TERRAFORM_DIR, 'src', 'app', 'apis'),\n    { ...options, ...terraformProviderVersions() },\n    {\n      overwriteStrategy: OverwriteStrategy.KeepExisting,\n    },\n  );\n};\n"],"names":["generateFiles","joinPathFragments","OverwriteStrategy","updateJson","addStarExport","addDependencyToTargetIfNotPresent","PACKAGES_DIR","SHARED_CONSTRUCTS_DIR","SHARED_TERRAFORM_DIR","PY_VERSIONS","terraformProviderVersions","addApiGatewayInfra","tree","options","iac","addApiGatewayCdkConstructs","addApiGatewayTerraformModules","Error","config","apiProjectName","generateCoreApiFile","name","dirname","overwriteStrategy","KeepExisting","constructType","backend","type","apiNameKebabCase","boto3Version","boto3"],"mappings":"AAAA;;;CAGC,GACD,SACEA,aAAa,EACbC,iBAAiB,EACjBC,iBAAiB,EAGjBC,UAAU,QACL,aAAa;AACpB,SAASC,aAAa,QAAQ,YAAS;AAEvC,SAASC,iCAAiC,QAAQ,WAAQ;AAC1D,SACEC,YAAY,EACZC,qBAAqB,EACrBC,oBAAoB,QACf,oCAAiC;AACxC,SAASC,WAAW,EAAEC,yBAAyB,QAAQ,iBAAc;AAmCrE,OAAO,MAAMC,qBAAqB,OAChCC,MACAC;IAEA,IAAIA,QAAQC,GAAG,KAAK,OAAO;QACzB,MAAMC,2BAA2BH,MAAMC;IACzC,OAAO,IAAIA,QAAQC,GAAG,KAAK,aAAa;QACtCE,8BAA8BJ,MAAMC;IACtC,OAAO;QACL,MAAM,IAAII,MAAM,CAAC,gBAAgB,EAAEJ,QAAQC,GAAG,EAAE;IAClD;IAEAX,WACES,MACAX,kBACEK,cACAO,QAAQC,GAAG,KAAK,QAAQP,wBAAwBC,sBAChD,iBAEF,CAACU;QACCb,kCACEa,QACA,SACA,GAAGL,QAAQM,cAAc,CAAC,MAAM,CAAC;QAEnC,OAAOD;IACT;AAEJ,EAAE;AAEF;;CAEC,GACD,MAAMH,6BAA6B,OACjCH,MACAC;IAEA,MAAMO,sBAAsB,CAACC;QAC3BrB,cACEY,MACAX,kBACE,YAAYqB,OAAO,EACnB,SACA,OACA,QACA,OACAD,OAEFpB,kBACEK,cACAC,uBACA,OACA,QACA,QAEF,CAAC,GACD;YACEgB,mBAAmBrB,kBAAkBsB,YAAY;QACnD;IAEJ;IAEA,qDAAqD;IACrDJ,oBAAoBP,QAAQY,aAAa;IACzCL,oBAAoB;IACpB,IAAIP,QAAQa,OAAO,CAACC,IAAI,KAAK,QAAQ;QACnCP,oBAAoB;IACtB;IAEA,sCAAsC;IACtCpB,cACEY,MACAX,kBACE,YAAYqB,OAAO,EACnB,SACA,OACA,OACA,QACAT,QAAQY,aAAa,GAEvBxB,kBACEK,cACAC,uBACA,OACA,OACA,SAEFM,SACA;QACEU,mBAAmBrB,kBAAkBsB,YAAY;IACnD;IAGF,oCAAoC;IACpC,MAAMpB,cACJQ,MACAX,kBACEK,cACAC,uBACA,OACA,OACA,QACA,aAEF,CAAC,EAAE,EAAEM,QAAQe,gBAAgB,CAAC,GAAG,CAAC;IAEpC,MAAMxB,cACJQ,MACAX,kBACEK,cACAC,uBACA,OACA,OACA,aAEF;AAEJ;AAEA;;CAEC,GACD,MAAMS,gCAAgC,CACpCJ,MACAC;IAEA,iCAAiC;IACjCb,cACEY,MACAX,kBACE,YAAYqB,OAAO,EACnB,SACA,aACA,QACA,OACAT,QAAQY,aAAa,GAEvBxB,kBAAkBK,cAAcE,sBAAsB,OAAO,QAAQ,QACrE;QAAEqB,cAAcpB,YAAYqB,KAAK;QAAE,GAAGpB,2BAA2B;IAAC,GAClE;QACEa,mBAAmBrB,kBAAkBsB,YAAY;IACnD;IAGF,yCAAyC;IACzCxB,cACEY,MACAX,kBACE,YAAYqB,OAAO,EACnB,SACA,aACA,OACA,QACAT,QAAQY,aAAa,GAEvBxB,kBAAkBK,cAAcE,sBAAsB,OAAO,OAAO,SACpE;QAAE,GAAGK,OAAO;QAAE,GAAGH,2BAA2B;IAAC,GAC7C;QACEa,mBAAmBrB,kBAAkBsB,YAAY;IACnD;AAEJ"}
+{"version":3,"sources":["../../../../../../packages/nx-plugin/src/utils/api-constructs/api-constructs.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  generateFiles,\n  joinPathFragments,\n  OverwriteStrategy,\n  type ProjectConfiguration,\n  type Tree,\n  updateJson,\n} from '@nx/devkit';\nimport { addStarExport } from '../ast';\nimport type { Iac } from '../iac';\nimport { esmVars } from '../module-format';\nimport { addDependencyToTargetIfNotPresent } from '../nx';\nimport {\n  PACKAGES_DIR,\n  SHARED_CONSTRUCTS_DIR,\n  SHARED_TERRAFORM_DIR,\n} from '../shared-constructs-constants';\nimport { PY_VERSIONS, terraformProviderVersions } from '../versions';\n\ninterface BackendOptions {\n  type: 'trpc' | 'fastapi' | 'smithy';\n  integrationPattern: 'isolated' | 'shared';\n}\n\nexport interface TrpcBackendOptions extends BackendOptions {\n  type: 'trpc';\n  projectAlias: string;\n  bundleOutputDir: string;\n  authorizerBundleOutputDir?: string;\n}\n\nexport interface FastApiBackendOptions extends BackendOptions {\n  type: 'fastapi';\n  moduleName: string;\n  bundleOutputDir: string;\n}\n\nexport interface SmithyBackendOptions extends BackendOptions {\n  type: 'smithy';\n  bundleOutputDir: string;\n  authorizerBundleOutputDir?: string;\n}\n\nexport interface AddApiGatewayConstructOptions {\n  apiProjectName: string;\n  apiNameClassName: string;\n  apiNameKebabCase: string;\n  constructType: 'http' | 'rest';\n  backend: TrpcBackendOptions | FastApiBackendOptions | SmithyBackendOptions;\n  auth: 'iam' | 'cognito' | 'custom';\n}\n\nexport const addApiGatewayInfra = async (\n  tree: Tree,\n  options: AddApiGatewayConstructOptions & { iac: Iac },\n) => {\n  if (options.iac === 'cdk') {\n    await addApiGatewayCdkConstructs(tree, options);\n  } else if (options.iac === 'terraform') {\n    addApiGatewayTerraformModules(tree, options);\n  } else {\n    throw new Error(`Unsupported iac ${options.iac}`);\n  }\n\n  updateJson(\n    tree,\n    joinPathFragments(\n      PACKAGES_DIR,\n      options.iac === 'cdk' ? SHARED_CONSTRUCTS_DIR : SHARED_TERRAFORM_DIR,\n      'project.json',\n    ),\n    (config: ProjectConfiguration) => {\n      addDependencyToTargetIfNotPresent(\n        config,\n        'build',\n        `${options.apiProjectName}:build`,\n      );\n      return config;\n    },\n  );\n};\n\n/**\n * Add an API CDK construct, and update the Runtime Config type to export its url\n */\nconst addApiGatewayCdkConstructs = async (\n  tree: Tree,\n  options: AddApiGatewayConstructOptions,\n) => {\n  const generateCoreApiFile = (name: string) => {\n    generateFiles(\n      tree,\n      joinPathFragments(\n        import.meta.dirname,\n        'files',\n        'cdk',\n        'core',\n        'api',\n        name,\n      ),\n      joinPathFragments(\n        PACKAGES_DIR,\n        SHARED_CONSTRUCTS_DIR,\n        'src',\n        'core',\n        'api',\n      ),\n      { ...esmVars(tree) },\n      {\n        overwriteStrategy: OverwriteStrategy.KeepExisting,\n      },\n    );\n  };\n\n  // Generate relevant core CDK construct and utilities\n  generateCoreApiFile(options.constructType);\n  generateCoreApiFile('utils');\n  if (options.backend.type === 'trpc') {\n    generateCoreApiFile('trpc');\n  }\n\n  // Generate app specific CDK construct\n  generateFiles(\n    tree,\n    joinPathFragments(\n      import.meta.dirname,\n      'files',\n      'cdk',\n      'app',\n      'apis',\n      options.constructType,\n    ),\n    joinPathFragments(\n      PACKAGES_DIR,\n      SHARED_CONSTRUCTS_DIR,\n      'src',\n      'app',\n      'apis',\n    ),\n    { ...options, ...esmVars(tree) },\n    {\n      overwriteStrategy: OverwriteStrategy.KeepExisting,\n    },\n  );\n\n  // Export app specific CDK construct\n  await addStarExport(\n    tree,\n    joinPathFragments(\n      PACKAGES_DIR,\n      SHARED_CONSTRUCTS_DIR,\n      'src',\n      'app',\n      'apis',\n      'index.ts',\n    ),\n    `./${options.apiNameKebabCase}.js`,\n  );\n  await addStarExport(\n    tree,\n    joinPathFragments(\n      PACKAGES_DIR,\n      SHARED_CONSTRUCTS_DIR,\n      'src',\n      'app',\n      'index.ts',\n    ),\n    './apis/index.js',\n  );\n};\n\n/**\n * Add an API terraform module, and update the Runtime Config type to export its url\n */\nconst addApiGatewayTerraformModules = (\n  tree: Tree,\n  options: AddApiGatewayConstructOptions,\n) => {\n  // Generate core terraform module\n  generateFiles(\n    tree,\n    joinPathFragments(\n      import.meta.dirname,\n      'files',\n      'terraform',\n      'core',\n      'api',\n      options.constructType,\n    ),\n    joinPathFragments(PACKAGES_DIR, SHARED_TERRAFORM_DIR, 'src', 'core', 'api'),\n    { boto3Version: PY_VERSIONS.boto3, ...terraformProviderVersions() },\n    {\n      overwriteStrategy: OverwriteStrategy.KeepExisting,\n    },\n  );\n\n  // Generate app specific terraform module\n  generateFiles(\n    tree,\n    joinPathFragments(\n      import.meta.dirname,\n      'files',\n      'terraform',\n      'app',\n      'apis',\n      options.constructType,\n    ),\n    joinPathFragments(PACKAGES_DIR, SHARED_TERRAFORM_DIR, 'src', 'app', 'apis'),\n    { ...options, ...terraformProviderVersions() },\n    {\n      overwriteStrategy: OverwriteStrategy.KeepExisting,\n    },\n  );\n};\n"],"names":["generateFiles","joinPathFragments","OverwriteStrategy","updateJson","addStarExport","esmVars","addDependencyToTargetIfNotPresent","PACKAGES_DIR","SHARED_CONSTRUCTS_DIR","SHARED_TERRAFORM_DIR","PY_VERSIONS","terraformProviderVersions","addApiGatewayInfra","tree","options","iac","addApiGatewayCdkConstructs","addApiGatewayTerraformModules","Error","config","apiProjectName","generateCoreApiFile","name","dirname","overwriteStrategy","KeepExisting","constructType","backend","type","apiNameKebabCase","boto3Version","boto3"],"mappings":"AAAA;;;CAGC,GACD,SACEA,aAAa,EACbC,iBAAiB,EACjBC,iBAAiB,EAGjBC,UAAU,QACL,aAAa;AACpB,SAASC,aAAa,QAAQ,YAAS;AAEvC,SAASC,OAAO,QAAQ,sBAAmB;AAC3C,SAASC,iCAAiC,QAAQ,WAAQ;AAC1D,SACEC,YAAY,EACZC,qBAAqB,EACrBC,oBAAoB,QACf,oCAAiC;AACxC,SAASC,WAAW,EAAEC,yBAAyB,QAAQ,iBAAc;AAmCrE,OAAO,MAAMC,qBAAqB,OAChCC,MACAC;IAEA,IAAIA,QAAQC,GAAG,KAAK,OAAO;QACzB,MAAMC,2BAA2BH,MAAMC;IACzC,OAAO,IAAIA,QAAQC,GAAG,KAAK,aAAa;QACtCE,8BAA8BJ,MAAMC;IACtC,OAAO;QACL,MAAM,IAAII,MAAM,CAAC,gBAAgB,EAAEJ,QAAQC,GAAG,EAAE;IAClD;IAEAZ,WACEU,MACAZ,kBACEM,cACAO,QAAQC,GAAG,KAAK,QAAQP,wBAAwBC,sBAChD,iBAEF,CAACU;QACCb,kCACEa,QACA,SACA,GAAGL,QAAQM,cAAc,CAAC,MAAM,CAAC;QAEnC,OAAOD;IACT;AAEJ,EAAE;AAEF;;CAEC,GACD,MAAMH,6BAA6B,OACjCH,MACAC;IAEA,MAAMO,sBAAsB,CAACC;QAC3BtB,cACEa,MACAZ,kBACE,YAAYsB,OAAO,EACnB,SACA,OACA,QACA,OACAD,OAEFrB,kBACEM,cACAC,uBACA,OACA,QACA,QAEF;YAAE,GAAGH,QAAQQ,KAAK;QAAC,GACnB;YACEW,mBAAmBtB,kBAAkBuB,YAAY;QACnD;IAEJ;IAEA,qDAAqD;IACrDJ,oBAAoBP,QAAQY,aAAa;IACzCL,oBAAoB;IACpB,IAAIP,QAAQa,OAAO,CAACC,IAAI,KAAK,QAAQ;QACnCP,oBAAoB;IACtB;IAEA,sCAAsC;IACtCrB,cACEa,MACAZ,kBACE,YAAYsB,OAAO,EACnB,SACA,OACA,OACA,QACAT,QAAQY,aAAa,GAEvBzB,kBACEM,cACAC,uBACA,OACA,OACA,SAEF;QAAE,GAAGM,OAAO;QAAE,GAAGT,QAAQQ,KAAK;IAAC,GAC/B;QACEW,mBAAmBtB,kBAAkBuB,YAAY;IACnD;IAGF,oCAAoC;IACpC,MAAMrB,cACJS,MACAZ,kBACEM,cACAC,uBACA,OACA,OACA,QACA,aAEF,CAAC,EAAE,EAAEM,QAAQe,gBAAgB,CAAC,GAAG,CAAC;IAEpC,MAAMzB,cACJS,MACAZ,kBACEM,cACAC,uBACA,OACA,OACA,aAEF;AAEJ;AAEA;;CAEC,GACD,MAAMS,gCAAgC,CACpCJ,MACAC;IAEA,iCAAiC;IACjCd,cACEa,MACAZ,kBACE,YAAYsB,OAAO,EACnB,SACA,aACA,QACA,OACAT,QAAQY,aAAa,GAEvBzB,kBAAkBM,cAAcE,sBAAsB,OAAO,QAAQ,QACrE;QAAEqB,cAAcpB,YAAYqB,KAAK;QAAE,GAAGpB,2BAA2B;IAAC,GAClE;QACEa,mBAAmBtB,kBAAkBuB,YAAY;IACnD;IAGF,yCAAyC;IACzCzB,cACEa,MACAZ,kBACE,YAAYsB,OAAO,EACnB,SACA,aACA,OACA,QACAT,QAAQY,aAAa,GAEvBzB,kBAAkBM,cAAcE,sBAAsB,OAAO,OAAO,SACpE;QAAE,GAAGK,OAAO;QAAE,GAAGH,2BAA2B;IAAC,GAC7C;QACEa,mBAAmBtB,kBAAkBuB,YAAY;IACnD;AAEJ"}

package/src/utils/api-constructs/files/cdk/app/apis/http/__apiNameKebabCase__.ts.template

@@ -13,7 +13,7 @@ import {
   <%_ } _%>
 } from 'aws-cdk-lib/aws-lambda';
 import { Duration<%_ if (backend.type === 'fastapi') { _%>, Stack<%_ } _%> } from 'aws-cdk-lib';
-import { RuntimeConfig } from '../../core/runtime-config.js';
+import { RuntimeConfig } from '../../core/runtime-config<% if (esm) { %>.js<% } %>';
 import {
   CorsHttpMethod,
   CfnApi,
@@ -41,10 +41,10 @@ import {
   ApiIntegrations,
   HttpApiIntegration,
   IntegrationBuilder,
-} from '../../core/api/utils.js';
-import { HttpApi } from '../../core/api/http-api.js';
+} from '../../core/api/utils<% if (esm) { %>.js<% } %>';
+import { HttpApi } from '../../core/api/http-api<% if (esm) { %>.js<% } %>';
 <%_ if (backend.type === 'trpc') { _%>
-import { Procedures, routerToOperations } from '../../core/api/trpc-utils.js';
+import { Procedures, routerToOperations } from '../../core/api/trpc-utils<% if (esm) { %>.js<% } %>';
 import { AppRouter, appRouter } from '<%= backend.projectAlias %>';
 
 // String union type for all API operation names
@@ -116,7 +116,7 @@ export class <%= apiNameClassName %><
           url.fileURLToPath(
             new URL(
               '../../../../../../<%- backend.bundleOutputDir %>',
-              import.meta.url,
+              <% if (esm) { %>import.meta.url<% } else { %>require('url').pathToFileURL(__filename).href<% } %>,
             ),
           ),
         ),
@@ -127,7 +127,7 @@ export class <%= apiNameClassName %><
           url.fileURLToPath(
             new URL(
               '../../../../../../<%- backend.bundleOutputDir %>',
-              import.meta.url,
+              <% if (esm) { %>import.meta.url<% } else { %>require('url').pathToFileURL(__filename).href<% } %>,
             ),
           ),
         ),
@@ -184,7 +184,7 @@ export class <%= apiNameClassName %><
         url.fileURLToPath(
           new URL(
             '../../../../../../<%- backend.authorizerBundleOutputDir %>',
-            import.meta.url,
+            <% if (esm) { %>import.meta.url<% } else { %>require('url').pathToFileURL(__filename).href<% } %>,
           ),
         ),
       ),
@@ -195,7 +195,7 @@ export class <%= apiNameClassName %><
         url.fileURLToPath(
           new URL(
             '../../../../../../<%- backend.bundleOutputDir %>',
-            import.meta.url,
+            <% if (esm) { %>import.meta.url<% } else { %>require('url').pathToFileURL(__filename).href<% } %>,
           ),
         ),
       ),

package/src/utils/api-constructs/files/cdk/app/apis/rest/__apiNameKebabCase__.ts.template

@@ -12,7 +12,7 @@ import {
   SnapStartConf,
   <%_ } _%>
 } from 'aws-cdk-lib/aws-lambda';
-import { RuntimeConfig } from '../../core/runtime-config.js';
+import { RuntimeConfig } from '../../core/runtime-config<% if (esm) { %>.js<% } %>';
 import {
   AuthorizationType,
   LambdaIntegration,
@@ -44,10 +44,10 @@ import {
   ApiIntegrations,
   IntegrationBuilder,
   RestApiIntegration,
-} from '../../core/api/utils.js';
-import { AddCorsPreflightAspect, RestApi } from '../../core/api/rest-api.js';
+} from '../../core/api/utils<% if (esm) { %>.js<% } %>';
+import { AddCorsPreflightAspect, RestApi } from '../../core/api/rest-api<% if (esm) { %>.js<% } %>';
 <%_ if (backend.type === 'trpc') { _%>
-import { Procedures, routerToOperations } from '../../core/api/trpc-utils.js';
+import { Procedures, routerToOperations } from '../../core/api/trpc-utils<% if (esm) { %>.js<% } %>';
 import { AppRouter, appRouter } from '<%= backend.projectAlias %>';
 
 // String union type for all API operation names
@@ -126,7 +126,7 @@ export class <%= apiNameClassName %><
           url.fileURLToPath(
             new URL(
               '../../../../../../<%- backend.bundleOutputDir %>',
-              import.meta.url,
+              <% if (esm) { %>import.meta.url<% } else { %>require('url').pathToFileURL(__filename).href<% } %>,
             ),
           ),
         ),
@@ -137,7 +137,7 @@ export class <%= apiNameClassName %><
           url.fileURLToPath(
             new URL(
               '../../../../../../<%- backend.bundleOutputDir %>',
-              import.meta.url,
+              <% if (esm) { %>import.meta.url<% } else { %>require('url').pathToFileURL(__filename).href<% } %>,
             ),
           ),
         ),
@@ -204,7 +204,7 @@ export class <%= apiNameClassName %><
         url.fileURLToPath(
           new URL(
             '../../../../../../<%- backend.authorizerBundleOutputDir %>',
-            import.meta.url,
+            <% if (esm) { %>import.meta.url<% } else { %>require('url').pathToFileURL(__filename).href<% } %>,
           ),
         ),
       ),
@@ -215,7 +215,7 @@ export class <%= apiNameClassName %><
         url.fileURLToPath(
           new URL(
             '../../../../../../<%- backend.bundleOutputDir %>',
-            import.meta.url,
+            <% if (esm) { %>import.meta.url<% } else { %>require('url').pathToFileURL(__filename).href<% } %>,
           ),
         ),
       ),

package/src/utils/api-constructs/files/cdk/core/api/http/http-api.ts.template

@@ -1,10 +1,10 @@
 import { Construct } from 'constructs';
-import { RuntimeConfig } from '../runtime-config.js';
+import { RuntimeConfig } from '../runtime-config<% if (esm) { %>.js<% } %>';
 import {
   ApiIntegrations,
   HttpApiIntegration,
   OperationDetails,
-} from './utils.js';
+} from './utils<% if (esm) { %>.js<% } %>';
 import { CfnOutput, Stack } from 'aws-cdk-lib';
 import {
   HttpApi as _HttpApi,
@@ -17,7 +17,7 @@ import {
 import { LogGroup } from 'aws-cdk-lib/aws-logs';
 import { Key } from 'aws-cdk-lib/aws-kms';
 import { ServicePrincipal } from 'aws-cdk-lib/aws-iam';
-import { suppressRules } from '../checkov.js';
+import { suppressRules } from '../checkov<% if (esm) { %>.js<% } %>';
 
 /**
  * Properties for creating an HttpApi construct.

package/src/utils/api-constructs/files/cdk/core/api/rest/api-gateway-account/index.js.template

@@ -16,32 +16,23 @@ const iam = new IAMClient();
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
-const hasLiveRole = async () => {
-  const { cloudwatchRoleArn } = await apigw.send(new GetAccountCommand({}));
-  if (!cloudwatchRoleArn) return false;
-  try {
-    await iam.send(
-      new GetRoleCommand({ RoleName: cloudwatchRoleArn.split('/').pop() }),
-    );
-    return true;
-  } catch (e) {
-    if (e.name === 'NoSuchEntityException') return false;
-    throw e;
-  }
-};
-
 const RETRYABLE = ['BadRequestException', 'TooManyRequestsException'];
 
-const setRole = async (value) => {
-  const command = new UpdateAccountCommand({
-    patchOperations: [{ op: 'replace', path: '/cloudwatchRoleArn', value }],
-  });
-  // Retry while the freshly created role propagates through IAM, and on throttling
+// Throttling may surface as a bare 429 with no modeled error code, so check
+// response metadata as well as error names
+const isRetryable = (e) =>
+  RETRYABLE.includes(e.name) ||
+  e.$metadata?.httpStatusCode === 429 ||
+  e.$retryable?.throttling === true;
+
+// Retry while the freshly created role propagates through IAM, and on
+// throttling of the account-level API (shared across concurrent deployments)
+const send = async (command) => {
   for (let attempt = 0; ; attempt++) {
     try {
       return await apigw.send(command);
     } catch (e) {
-      if (RETRYABLE.includes(e.name) && attempt < 11) {
+      if (isRetryable(e) && attempt < 11) {
         await sleep(5000);
       } else {
         throw e;
@@ -50,6 +41,27 @@ const setRole = async (value) => {
   }
 };
 
+const hasLiveRole = async () => {
+  const { cloudwatchRoleArn } = await send(new GetAccountCommand({}));
+  if (!cloudwatchRoleArn) return false;
+  try {
+    await iam.send(
+      new GetRoleCommand({ RoleName: cloudwatchRoleArn.split('/').pop() }),
+    );
+    return true;
+  } catch (e) {
+    if (e.name === 'NoSuchEntityException') return false;
+    throw e;
+  }
+};
+
+const setRole = (value) =>
+  send(
+    new UpdateAccountCommand({
+      patchOperations: [{ op: 'replace', path: '/cloudwatchRoleArn', value }],
+    }),
+  );
+
 exports.handler = async (event) => {
   if (event.RequestType !== 'Delete' && !(await hasLiveRole())) {
     await setRole(event.ResourceProperties.CloudWatchRoleArn);

package/src/utils/api-constructs/files/cdk/core/api/rest/api-gateway-account.ts.template

@@ -50,7 +50,7 @@ export class ApiGatewayAccount extends Construct {
       handler: 'index.handler',
       timeout: Duration.minutes(2),
       code: Code.fromAsset(
-        url.fileURLToPath(new URL('./api-gateway-account', import.meta.url)),
+        url.fileURLToPath(new URL('./api-gateway-account', <% if (esm) { %>import.meta.url<% } else { %>require('url').pathToFileURL(__filename).href<% } %>)),
       ),
     });
     const { region } = Stack.of(this);

package/src/utils/api-constructs/files/cdk/core/api/rest/rest-api.ts.template

@@ -19,14 +19,14 @@ import {
 import { LogGroup, RetentionDays } from 'aws-cdk-lib/aws-logs';
 import { Key } from 'aws-cdk-lib/aws-kms';
 import { ServicePrincipal } from 'aws-cdk-lib/aws-iam';
-import { RuntimeConfig } from '../runtime-config.js';
-import { ApiGatewayAccount } from './api-gateway-account.js';
+import { RuntimeConfig } from '../runtime-config<% if (esm) { %>.js<% } %>';
+import { ApiGatewayAccount } from './api-gateway-account<% if (esm) { %>.js<% } %>';
 import {
   ApiIntegrations,
   OperationDetails,
   RestApiIntegration,
-} from './utils.js';
-import { suppressRules } from '../checkov.js';
+} from './utils<% if (esm) { %>.js<% } %>';
+import { suppressRules } from '../checkov<% if (esm) { %>.js<% } %>';
 
 /**
  * Properties for creating a RestApi construct.

package/src/utils/api-constructs/files/cdk/core/api/trpc/trpc-utils.ts.template

@@ -1,5 +1,5 @@
 import { TRPCRouterRecord, AnyTRPCRouter } from '@trpc/server';
-import { OperationDetails } from './utils.js';
+import { OperationDetails } from './utils<% if (esm) { %>.js<% } %>';
 import { HttpMethod } from 'aws-cdk-lib/aws-apigatewayv2';
 
 /**

package/src/utils/api-constructs/files/terraform/app/apis/http/__apiNameKebabCase__/__apiNameKebabCase__.tf.template

@@ -43,6 +43,30 @@ variable "asset_bucket_name" {
   type        = string
 }
 
+# VPC Configuration (optional)
+variable "enable_vpc" {
+  description = "Deploy the Lambda function into a VPC. Set alongside vpc_id/subnet_ids."
+  type        = bool
+  default     = false
+}
+
+variable "vpc_id" {
+  description = "VPC ID to deploy the Lambda function into. Required when enable_vpc is true."
+  type        = string
+  default     = null
+
+  validation {
+    condition     = !var.enable_vpc || (var.vpc_id != null && var.subnet_ids != null)
+    error_message = "vpc_id and subnet_ids must be set when enable_vpc is true."
+  }
+}
+
+variable "subnet_ids" {
+  description = "Subnet IDs to deploy the Lambda function into. Required when enable_vpc is true."
+  type        = list(string)
+  default     = null
+}
+
 # CORS Configuration (passed to core module)
 variable "cors_allow_credentials" {
   description = "Whether to allow credentials in CORS requests"
@@ -129,10 +153,32 @@ module "http_api" {
   tags = var.tags
 }
 
+# Security group for the API Lambda function, used when deployed into a VPC
+resource "aws_security_group" "api_lambda" {
+  count = var.enable_vpc ? 1 : 0
+
+  #checkov:skip=CKV2_AWS_5:Attached to api_lambda via vpc_config block; Checkov cannot resolve this reference
+  name_prefix = "<%- apiNameKebabCase %>-lambda-"
+  description = "Security group for the <%- apiNameClassName %> API Lambda function"
+  vpc_id      = var.vpc_id
+  tags        = var.tags
+}
+
+resource "aws_vpc_security_group_egress_rule" "api_lambda_https" {
+  count = var.enable_vpc ? 1 : 0
+
+  security_group_id = aws_security_group.api_lambda[0].id
+  cidr_ipv4         = "0.0.0.0/0"
+  from_port         = 443
+  to_port           = 443
+  ip_protocol       = "tcp"
+  description       = "Allow outbound HTTPS to AWS service endpoints"
+}
+
 # Lambda function
 # This configures a single "router" lambda to serve all requests
 resource "aws_lambda_function" "api_lambda" {
-  #checkov:skip=CKV_AWS_117:Lambda function does not need to be in VPC for this use case
+  #checkov:skip=CKV_AWS_117:Lambda function is optionally deployed into a VPC via vpc_id/subnet_ids; not required for this use case
   #checkov:skip=CKV_AWS_116:Dead Letter Queue not required for this simple API use case
   #checkov:skip=CKV_AWS_272:Code signing not required for this use case
   #checkov:skip=CKV_AWS_115:Concurrent execution limit not required for this use case
@@ -163,6 +209,14 @@ resource "aws_lambda_function" "api_lambda" {
     mode = "Active"
   }
 
+  dynamic "vpc_config" {
+    for_each = var.enable_vpc ? [1] : []
+    content {
+      subnet_ids         = var.subnet_ids
+      security_group_ids = [aws_security_group.api_lambda[0].id]
+    }
+  }
+
   <%_ if (backend.type === 'fastapi') { _%>
   # Enable SnapStart for faster cold starts
   snap_start {
@@ -181,6 +235,8 @@ resource "aws_lambda_function" "api_lambda" {
   }
 
   tags = var.tags
+
+  depends_on = [aws_iam_role_policy_attachment.lambda_vpc_access]
 }
 
 # IAM role for Lambda execution
@@ -215,6 +271,13 @@ resource "aws_iam_role_policy_attachment" "lambda_xray_execution" {
   role       = aws_iam_role.lambda_execution_role.name
 }
 
+# Attach VPC access policy to Lambda role when deployed into a VPC
+resource "aws_iam_role_policy_attachment" "lambda_vpc_access" {
+  count      = var.enable_vpc ? 1 : 0
+  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole"
+  role       = aws_iam_role.lambda_execution_role.name
+}
+
 # Additional IAM policies for Lambda (if provided)
 resource "aws_iam_role_policy" "lambda_additional_policies" {
   count = length(var.additional_iam_policy_statements) > 0 ? 1 : 0
@@ -527,6 +590,11 @@ output "lambda_execution_role_name" {
   value       = aws_iam_role.lambda_execution_role.name
 }
 
+output "security_group_id" {
+  description = "Security group ID of the API Lambda function, for use in ingress rules on resources it must reach (e.g. a database). Null unless enable_vpc is true."
+  value       = var.enable_vpc ? aws_security_group.api_lambda[0].id : null
+}
+
 # Integration Outputs
 output "integration_id" {
   description = "ID of the Lambda integration"

package/src/utils/api-constructs/files/terraform/app/apis/rest/__apiNameKebabCase__/__apiNameKebabCase__.tf.template

@@ -43,6 +43,30 @@ variable "asset_bucket_name" {
   type        = string
 }
 
+# VPC Configuration (optional)
+variable "enable_vpc" {
+  description = "Deploy the Lambda function into a VPC. Set alongside vpc_id/subnet_ids."
+  type        = bool
+  default     = false
+}
+
+variable "vpc_id" {
+  description = "VPC ID to deploy the Lambda function into. Required when enable_vpc is true."
+  type        = string
+  default     = null
+
+  validation {
+    condition     = !var.enable_vpc || (var.vpc_id != null && var.subnet_ids != null)
+    error_message = "vpc_id and subnet_ids must be set when enable_vpc is true."
+  }
+}
+
+variable "subnet_ids" {
+  description = "Subnet IDs to deploy the Lambda function into. Required when enable_vpc is true."
+  type        = list(string)
+  default     = null
+}
+
 # CORS Configuration (passed to core module)
 
 variable "cors_allow_headers" {
@@ -139,9 +163,31 @@ resource "aws_wafv2_web_acl_association" "api_waf_association" {
   depends_on = [aws_api_gateway_stage.api_stage]
 }
 
+# Security group for the API Lambda function, used when deployed into a VPC
+resource "aws_security_group" "api_lambda" {
+  count = var.enable_vpc ? 1 : 0
+
+  #checkov:skip=CKV2_AWS_5:Attached to api_lambda via vpc_config block; Checkov cannot resolve this reference
+  name_prefix = "<%- apiNameKebabCase %>-lambda-"
+  description = "Security group for the <%- apiNameClassName %> API Lambda function"
+  vpc_id      = var.vpc_id
+  tags        = var.tags
+}
+
+resource "aws_vpc_security_group_egress_rule" "api_lambda_https" {
+  count = var.enable_vpc ? 1 : 0
+
+  security_group_id = aws_security_group.api_lambda[0].id
+  cidr_ipv4         = "0.0.0.0/0"
+  from_port         = 443
+  to_port           = 443
+  ip_protocol       = "tcp"
+  description       = "Allow outbound HTTPS to AWS service endpoints"
+}
+
 # Lambda function
 resource "aws_lambda_function" "api_lambda" {
-  #checkov:skip=CKV_AWS_117:Lambda function does not need to be in VPC for this use case
+  #checkov:skip=CKV_AWS_117:Lambda function is optionally deployed into a VPC via vpc_id/subnet_ids; not required for this use case
   #checkov:skip=CKV_AWS_116:Dead Letter Queue not required for this simple API use case
   #checkov:skip=CKV_AWS_272:Code signing not required for this use case
   #checkov:skip=CKV_AWS_115:Concurrent execution limit not required for this use case
@@ -172,6 +218,14 @@ resource "aws_lambda_function" "api_lambda" {
     mode = "Active"
   }
 
+  dynamic "vpc_config" {
+    for_each = var.enable_vpc ? [1] : []
+    content {
+      subnet_ids         = var.subnet_ids
+      security_group_ids = [aws_security_group.api_lambda[0].id]
+    }
+  }
+
   <%_ if (backend.type === 'fastapi') { _%>
   # Enable SnapStart for faster cold starts
   snap_start {
@@ -190,6 +244,8 @@ resource "aws_lambda_function" "api_lambda" {
   }
 
   tags = var.tags
+
+  depends_on = [aws_iam_role_policy_attachment.lambda_vpc_access]
 }
 
 # IAM role for Lambda execution
@@ -224,6 +280,13 @@ resource "aws_iam_role_policy_attachment" "lambda_xray_execution" {
   role       = aws_iam_role.lambda_execution_role.name
 }
 
+# Attach VPC access policy to Lambda role when deployed into a VPC
+resource "aws_iam_role_policy_attachment" "lambda_vpc_access" {
+  count      = var.enable_vpc ? 1 : 0
+  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole"
+  role       = aws_iam_role.lambda_execution_role.name
+}
+
 # Additional IAM policies for Lambda (if provided)
 resource "aws_iam_role_policy" "lambda_additional_policies" {
   count = length(var.additional_iam_policy_statements) > 0 ? 1 : 0
@@ -794,6 +857,11 @@ output "lambda_execution_role_name" {
   value       = aws_iam_role.lambda_execution_role.name
 }
 
+output "security_group_id" {
+  description = "Security group ID of the API Lambda function, for use in ingress rules on resources it must reach (e.g. a database). Null unless enable_vpc is true."
+  value       = var.enable_vpc ? aws_security_group.api_lambda[0].id : null
+}
+
 # Integration Outputs
 output "integration_id" {
   description = "ID of the Lambda integration"