@aws/nx-plugin-mcp 1.0.0-rc.84 → 1.0.0-rc.86

package/bin/aws-nx-mcp.js

@@ -54266,6 +54266,13 @@ var generators$1 = {
 		"metric": "g19",
 		"hidden": true
 	},
+	"open-api#json-metadata": {
+		"factory": "./src/open-api/json-metadata/generator",
+		"schema": "./src/open-api/json-metadata/schema.json",
+		"description": "Generate a JSON metadata file describing an OpenAPI specification's operations",
+		"metric": "g72",
+		"hidden": true
+	},
 	"preset": {
 		"factory": "./src/preset/generator",
 		"schema": "./src/preset/schema.json",

package/docs/guides/fastapi.mdx

@@ -491,6 +491,8 @@ The `UserIdentity` construct can be generated using the <Link path="/guides/reac
 <OptionFilter when={{ auth: 'custom' }} description="Custom Lambda Authorizer CDK usage">
 :::caution[Custom Lambda Authorizer]
 When using `Custom` auth, the construct creates a Lambda Authorizer internally from the generated `authorizer.py` file, which **denies all requests by default**. You must implement your authorization logic in that file before your API will accept any traffic.
+
+Authorizer results are cached for 5 minutes, keyed on the `Authorization` header, so a revoked token may be accepted until its cached result expires. Reduce the cache duration in the generated infrastructure if you need faster revocation.
 :::
 </OptionFilter>
 </Fragment>
@@ -604,6 +606,8 @@ module "my_api" {
 <OptionFilter when={{ auth: 'custom' }} description="Custom Lambda Authorizer usage with Terraform">
 :::caution[Custom Lambda Authorizer]
 When using `Custom` auth, your API is protected by a Lambda Authorizer that **denies all requests by default**. You must implement your authorization logic in the generated `authorizer.py` file before your API will accept any traffic.
+
+Authorizer results are cached for 5 minutes, keyed on the `Authorization` header, so a revoked token may be accepted until its cached result expires. Reduce the cache duration in the generated infrastructure if you need faster revocation.
 :::
 </OptionFilter>
 </Fragment>

package/docs/guides/py-rdb.mdx

@@ -231,6 +231,10 @@ When using RDS Proxy, you do not need to configure the RDS CA bundle in the runt
 
 <Snippet name="rdb/encryption-key-rotation" />
 
+### Admin Credentials
+
+<Snippet name="rdb/admin-credentials" />
+
 ## Connections
 
 Use the <Link path="guides/connection">`connection`</Link> generator to integrate this project with others in your workspace. The following connections involve this project:

package/docs/guides/terraform-project.mdx

@@ -48,10 +48,12 @@ For application projects (`--type=application`), the generator creates a complet
     - main.tf S3 bucket and policies for state storage
     - providers.tf AWS provider configuration
     - variables.tf Bootstrap variable definitions
-  - scripts Node helpers run by the nx `bootstrap` and `init` targets
+  - scripts Node helpers run by the nx `bootstrap`, `bootstrap-destroy` and `init` targets
     - aws-config.ts Resolves account + region via the AWS SDK credential chain
     - bootstrap.ts Pulls/pushes the bootstrap tfstate and runs `terraform apply`
+    - bootstrap-destroy.ts Empties the state bucket and runs `terraform destroy`
     - init.ts Runs `terraform init` with the S3 backend config
+  - checkov.yml Checkov configuration, including the checks to skip
   - project.json Project configuration and build targets
 
 </FileTree>
@@ -71,6 +73,7 @@ For library projects (`--type=library`), the generator creates a simpler structu
 
   - src
     - main.tf Main Terraform module file
+  - checkov.yml Checkov configuration, including the checks to skip
   - project.json Project configuration and build targets
 
 </FileTree>
@@ -250,12 +253,66 @@ Format your Terraform code using the `fmt` target:
 
 #### Security Testing
 
-Run security checks on your infrastructure using Checkov with the `test` target:
+Run security checks on your infrastructure using Checkov with the `checkov` target:
 
-<NxCommands commands={['test tf-infra']} />
+<NxCommands commands={['checkov tf-infra']} />
 
 You will find your security test results in the root `dist` folder, under `dist/packages/<my-terraform-project>/checkov`.
 
+Checks are configured in the project's `checkov.yml`. Add a check id to `skip-check` to suppress it across the whole project:
+
+```yaml title="checkov.yml"
+skip-check:
+  - CKV_AWS_115 # Concurrent execution limit
+  - CKV_AWS_116 # Dead Letter Queue
+```
+
+To suppress a check for a single resource instead, add a `#checkov:skip=<id>:<reason>` comment inside the resource block:
+
+```hcl
+resource "aws_s3_bucket" "example" {
+  #checkov:skip=CKV_AWS_18:Access logging not required for this bucket
+  bucket = "example"
+}
+```
+
+#### Running Terraform Tests
+
+The `test` target runs [Terraform's native test framework](https://developer.hashicorp.com/terraform/language/tests) over any `.tftest.hcl` files in your project:
+
+<NxCommands commands={['test tf-infra']} />
+
+A project with no test files is a no-op success, so you can add tests when you need them. `build` runs this target, so your tests run as part of a normal build.
+
+Each `run` block evaluates your configuration. Use `command = plan` to check what Terraform _would_ do (this expands the whole module graph, so it catches plan-time errors that `validate` cannot), or `command = apply` to create real resources and assert on their outputs. Declaring `mock_provider` means no API calls are made and no AWS credentials are needed, which keeps `plan` tests fast and safe to run in CI:
+
+```hcl title="src/main.tftest.hcl"
+mock_provider "aws" {
+  mock_data "aws_caller_identity" {
+    defaults = { account_id = "123456789012" }
+  }
+  mock_data "aws_region" {
+    defaults = { region = "us-east-1" }
+  }
+}
+
+variables {
+  aws_region  = "us-east-1"
+  environment = "dev"
+}
+
+run "plan_is_valid" {
+  command = plan
+
+  assert {
+    condition     = data.aws_caller_identity.current.account_id == "123456789012"
+    error_message = "Unexpected account id"
+  }
+}
+```
+
+Set every variable your configuration requires in the `variables` block, otherwise the run fails with "has a required variable ... with no set value".
+
 <OptionFilter when={{ type: 'application' }} description="Application-only targets: plan / apply / destroy / etc.">
 ### Application-Only Targets
 
@@ -310,6 +367,12 @@ This will permanently delete all resources managed by this Terraform configurati
 To clean up the bootstrap resources (S3 bucket for state storage):
 
 <NxCommands commands={['bootstrap-destroy tf-infra']} />
+
+This empties the state bucket before destroying it, and resolves the region from the AWS SDK credential chain, so it runs unattended in CI.
+
+:::caution[Destroy your infrastructure first]
+The state bucket holds the state for every environment, so run `destroy` for each environment before this. Once the bucket is gone, Terraform no longer knows about the resources it created.
+:::
 </OptionFilter>
 
 ## More Information

package/docs/guides/trpc.mdx

@@ -573,6 +573,8 @@ export class ExampleStack extends Stack {
 
 :::caution[Custom Lambda Authorizer]
 When using `Custom` auth, the construct creates a Lambda Authorizer internally from the generated `src/authorizer.ts` file, which **denies all requests by default**. You must implement your authorization logic in that file before your API will accept any traffic.
+
+Authorizer results are cached for 5 minutes, keyed on the `Authorization` header, so a revoked token may be accepted until its cached result expires. Reduce the cache duration in the generated infrastructure if you need faster revocation.
 :::
 </OptionFilter>
 
@@ -718,6 +720,8 @@ module "my_api" {
 <OptionFilter when={{ auth: 'custom' }} description="Custom Lambda Authorizer usage with Terraform">
 :::caution[Custom Lambda Authorizer]
 When using `Custom` auth, your API is protected by a Lambda Authorizer that **denies all requests by default**. You must implement your authorization logic in the generated `src/authorizer.ts` file before your API will accept any traffic.
+
+Authorizer results are cached for 5 minutes, keyed on the `Authorization` header, so a revoked token may be accepted until its cached result expires. Reduce the cache duration in the generated infrastructure if you need faster revocation.
 :::
 </OptionFilter>
 </Fragment>

package/docs/guides/ts-rdb.mdx

@@ -311,6 +311,10 @@ For more details, see the AWS Lambda [SSL/TLS requirements for Amazon RDS connec
 
 <Snippet name="rdb/encryption-key-rotation" />
 
+### Admin Credentials
+
+<Snippet name="rdb/admin-credentials" />
+
 ## Limitations
 
 <OptionFilter when={{ engine: 'mysql' }}>

package/docs/guides/ts-smithy-api.mdx

@@ -697,6 +697,8 @@ The `UserIdentity` construct can be generated using the <Link path="/guides/reac
 <OptionFilter when={{ auth: 'custom' }} description="Custom Lambda Authorizer CDK usage">
 :::caution[Custom Lambda Authorizer]
 When using `Custom` auth, the construct creates a Lambda Authorizer internally from the generated `src/authorizer.ts` file, which **denies all requests by default**. You must implement your authorization logic in that file before your API will accept any traffic.
+
+Authorizer results are cached for 5 minutes, keyed on the `Authorization` header, so a revoked token may be accepted until its cached result expires. Reduce the cache duration in the generated infrastructure if you need faster revocation.
 :::
 </OptionFilter>
 </Fragment>
@@ -768,6 +770,8 @@ module "my_api" {
 <OptionFilter when={{ auth: 'custom' }} description="Custom Lambda Authorizer usage with Terraform">
 :::caution[Custom Lambda Authorizer]
 When using `Custom` auth, your API is protected by a Lambda Authorizer that **denies all requests by default**. You must implement your authorization logic in the generated `src/authorizer.ts` file before your API will accept any traffic.
+
+Authorizer results are cached for 5 minutes, keyed on the `Authorization` header, so a revoked token may be accepted until its cached result expires. Reduce the cache duration in the generated infrastructure if you need faster revocation.
 :::
 </OptionFilter>
 

package/docs/snippets/api/type-safe-api-integrations.mdx

@@ -1,24 +1,14 @@
 ---
 title: Type-Safe API Integrations
 ---
-import { Tabs, TabItem } from '@astrojs/starlight/components';
+import { Steps } from '@astrojs/starlight/components';
 import Infrastructure from '@components/infrastructure.astro';
+import Drawer from '@components/drawer.astro';
+import OptionFilter from '@components/option-filter.astro';
+import RunGenerator from '@components/run-generator.astro';
 
 The REST/HTTP API CDK constructs are configured to provide a type-safe interface for defining integrations for each of your operations.
 
-<Infrastructure>
-<Fragment slot="cdk">
-The CDK constructs provide full type-safe integration support as described below.
-</Fragment>
-<Fragment slot="terraform">
-:::note[Router Pattern]
-Terraform modules use the "router pattern" with a single Lambda function serving all operations. Type-safe integrations are not supported - the module creates one Lambda function that handles all API requests.
-
-For explicit per-operation integrations with Terraform, you would need to manually create individual Lambda functions and API Gateway routes. See the [Explicit Integrations](#explicit-integrations) section for examples.
-:::
-</Fragment>
-</Infrastructure>
-
 #### Default Integrations
 
 <Infrastructure>
@@ -32,7 +22,7 @@ new MyApi(this, 'MyApi', {
 ```
 </Fragment>
 <Fragment slot="terraform">
-Terraform modules automatically use the router pattern with a single Lambda function. No additional configuration is needed:
+The generated module already defines the default integrations for the pattern the API was generated with, so no additional configuration is needed:
 
 ```hcl
 module "my_api" {
@@ -40,11 +30,11 @@ module "my_api" {
 
   asset_bucket_name = module.asset_bucket.bucket_name
 
-  # The module automatically creates a single Lambda function
-  # that handles all API operations
   tags = local.common_tags
 }
 ```
+
+With the default `isolated` pattern, this creates one Lambda function per operation.
 </Fragment>
 </Infrastructure>
 
@@ -78,13 +68,13 @@ api.integrations.$router.handler.addEnvironment('LOG_LEVEL', 'DEBUG');
 ```
 </Fragment>
 <Fragment slot="terraform">
-With Terraform's router pattern, there's only one Lambda function. You can access it via the module outputs:
+With the `isolated` pattern, the module's outputs are maps keyed by operation name, so you can reach a single operation's resources. For example, to grant one operation's Lambda function extra permissions:
 
 ```hcl
-# Grant additional permissions to the single Lambda function
-resource "aws_iam_role_policy" "additional_permissions" {
-  name = "additional-api-permissions"
-  role = module.my_api.lambda_execution_role_name
+# Grant additional permissions to just the sayHello operation's function
+resource "aws_iam_role_policy" "say_hello_permissions" {
+  name = "say-hello-additional-permissions"
+  role = module.my_api.lambda_execution_role_names["sayHello"]
 
   policy = jsonencode({
     Version = "2012-10-17"
@@ -101,6 +91,48 @@ resource "aws_iam_role_policy" "additional_permissions" {
   })
 }
 ```
+
+To grant the same permissions to every operation, iterate the `operations` output:
+
+```hcl
+resource "aws_iam_role_policy" "additional_permissions" {
+  for_each = toset(module.my_api.operations)
+
+  name = "additional-api-permissions"
+  role = module.my_api.lambda_execution_role_names[each.key]
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect   = "Allow"
+        Action   = ["s3:GetObject"]
+        Resource = "arn:aws:s3:::my-bucket/*"
+      }
+    ]
+  })
+}
+```
+
+The module also exposes `lambda_function_names`, `lambda_function_arns`, `lambda_invoke_arns`, `integration_ids` and `lambda_log_group_names` as maps keyed by operation name. With the `shared` pattern the equivalent singular outputs (`lambda_execution_role_name`, `lambda_function_name`, …) are exposed instead, since there is only one function.
+
+Permissions every operation needs are better passed to the module, which applies them to each function's role:
+
+```hcl
+module "my_api" {
+  source = "../../common/terraform/src/app/apis/my-api"
+
+  asset_bucket_name = module.asset_bucket.bucket_name
+
+  additional_iam_policy_statements = [
+    {
+      Effect   = "Allow"
+      Action   = ["s3:GetObject"]
+      Resource = ["arn:aws:s3:::my-bucket/*"]
+    }
+  ]
+}
+```
 </Fragment>
 </Infrastructure>
 
@@ -125,7 +157,7 @@ new MyApi(this, 'MyApi', {
 
 </Fragment>
 <Fragment slot="terraform">
-VPC configuration is already supported by the generated module — set `enable_vpc` along with `vpc_id` and `subnet_ids`, and the module deploys the Lambda function into your VPC behind a security group it creates for you:
+VPC configuration is already supported by the generated module — set `enable_vpc` along with `vpc_id` and `subnet_ids`, and the module deploys every Lambda function into your VPC behind a shared security group it creates for you:
 
 ```hcl
 module "my_api" {
@@ -142,7 +174,7 @@ module "my_api" {
 }
 ```
 
-For options the module does not expose, edit the `aws_lambda_function` resource in the generated Terraform module directly.
+For options the module does not expose, edit the `aws_lambda_function` resource in the generated Terraform module directly. With the `isolated` pattern that single resource is declared `for_each = local.operations`, so an edit there applies to every operation.
 </Fragment>
 </Infrastructure>
 
@@ -173,7 +205,21 @@ You will encounter a type error if the same operation is targeted by both `withO
 
 </Fragment>
 <Fragment slot="terraform">
-To customise options for specific operations with Terraform, you need to edit the generated Terraform module to configure individual Lambda functions per operation (see the [Explicit Integrations](#explicit-integrations) section below).
+With the `isolated` pattern the Lambda function resource is already per-operation, so options can be varied by operation name. For example, to give one operation a longer timeout, edit the `aws_lambda_function` resource in the generated module:
+
+```hcl
+# packages/common/terraform/src/app/apis/my-api/my-api.tf
+resource "aws_lambda_function" "api_lambda" {
+  for_each = local.operations
+
+  # Default to 30 seconds, but allow longer for specific operations
+  timeout = lookup({
+    sayHello = 60
+  }, each.key, 30)
+
+  # ... rest of configuration
+}
+```
 </Fragment>
 </Infrastructure>
 
@@ -244,11 +290,36 @@ api.integrations.getFile.bucket.grantRead(...);
 ```
 </Fragment>
 <Fragment slot="terraform">
-:::note[Integration Overrides]
-Overriding specific integrations is not supported with Terraform modules since they use the router pattern. All operations are handled by the single Lambda function.
+To point a specific operation at a different integration type, exclude it from the default `for_each` and declare its integration separately. For example, to serve `getDocumentation` from an external website:
 
-For different integration types per operation, you would need to implement explicit integrations manually (see the [Explicit Integrations](#explicit-integrations) section below).
-:::
+```hcl
+# packages/common/terraform/src/app/apis/my-api/my-api.tf
+
+# Exclude the overridden operation from the default per-operation resources
+locals {
+  overridden_operations = ["getDocumentation"]
+  default_operations = {
+    for op, details in local.operations : op => details
+    if !contains(local.overridden_operations, op)
+  }
+}
+
+# Then use local.default_operations in place of local.operations for the
+# aws_lambda_function, aws_iam_role, aws_apigatewayv2_integration and
+# aws_lambda_permission resources, and add the override:
+resource "aws_apigatewayv2_integration" "get_documentation" {
+  api_id             = module.http_api.api_id
+  integration_type   = "HTTP_PROXY"
+  integration_uri    = "https://example.com/documentation"
+  integration_method = "GET"
+}
+
+resource "aws_apigatewayv2_route" "get_documentation" {
+  api_id    = module.http_api.api_id
+  route_key = local.route_key["getDocumentation"]
+  target    = "integrations/${aws_apigatewayv2_integration.get_documentation.id}"
+}
+```
 </Fragment>
 </Infrastructure>
 
@@ -274,11 +345,20 @@ new MyApi(this, 'MyApi', {
 ```
 </Fragment>
 <Fragment slot="terraform">
-:::note[Authorizer Overrides]
-Per-operation authorizer overrides are not supported with Terraform modules. The entire API uses the authentication method specified when generating the API (IAM, Cognito, or Custom).
+Authorization is set on the route (HTTP API) or method (REST API) for each operation, so it can be varied by operation name. For example, to leave one operation unauthenticated on an HTTP API:
 
-For per-operation authorization, you would need to implement explicit integrations manually as below.
-:::
+```hcl
+# packages/common/terraform/src/app/apis/my-api/my-api.tf
+resource "aws_apigatewayv2_route" "operation_routes" {
+  for_each = local.operations
+
+  # ... rest of configuration
+
+  authorization_type = each.key == "getDocumentation" ? "NONE" : "AWS_IAM"
+}
+```
+
+For an IAM-authenticated REST API, also add a resource policy statement allowing unauthenticated access to that operation's path.
 </Fragment>
 </Infrastructure>
 
@@ -302,331 +382,26 @@ new MyApi(this, 'MyApi', {
 ```
 </Fragment>
 <Fragment slot="terraform">
-For explicit per-operation integrations with Terraform, you should modify the generated app-specific module to replace the default proxy integration with specific integrations for each operation.
-
-Edit `packages/common/terraform/src/app/apis/my-api/my-api.tf`:
-
-1. **Remove the default proxy routes** (e.g., `resource "aws_apigatewayv2_route" "proxy_routes"`)
-2. **Replace the single Lambda function** with individual functions for each operation
-3. **Create specific integrations and routes** for each operation, reusing the same ZIP bundle:
-
-<Tabs syncKey="http-rest">
-<TabItem label="HTTP API" _filter={{ infra: 'http-lambda' }}>
-
-```diff
-# packages/common/terraform/src/app/apis/my-api/my-api.tf
-
-# Remove the default single Lambda function
-- resource "aws_lambda_function" "api_lambda" {
--   s3_bucket         = aws_s3_object.lambda_zip.bucket
--   s3_key            = aws_s3_object.lambda_zip.key
--   s3_object_version = aws_s3_object.lambda_zip.version_id
--   function_name    = "MyApiHandler"
--   role            = aws_iam_role.lambda_execution_role.arn
--   handler         = "index.handler"
--   runtime         = "nodejs22.x"
--   timeout         = 30
--   # ... rest of configuration
-- }
-
-# Remove the default proxy integration
-- resource "aws_apigatewayv2_integration" "lambda_integration" {
--   api_id           = module.http_api.api_id
--   integration_type = "AWS_PROXY"
--   integration_uri  = aws_lambda_function.api_lambda.invoke_arn
--   # ... rest of configuration
-- }
-
-# Remove the default proxy routes
-- resource "aws_apigatewayv2_route" "proxy_routes" {
--   for_each = toset(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"])
--   api_id    = module.http_api.api_id
--   route_key = "${each.key} /{proxy+}"
--   target    = "integrations/${aws_apigatewayv2_integration.lambda_integration.id}"
--   # ... rest of configuration
-- }
-
-# Add individual Lambda functions for each operation using the same bundle
-+ resource "aws_lambda_function" "say_hello_handler" {
-+   s3_bucket         = aws_s3_object.lambda_zip.bucket
-+   s3_key            = aws_s3_object.lambda_zip.key
-+   s3_object_version = aws_s3_object.lambda_zip.version_id
-+   function_name    = "MyApi-SayHello"
-+   role            = aws_iam_role.lambda_execution_role.arn
-+   handler         = "sayHello.handler"  # Specific handler for this operation
-+   runtime         = "nodejs22.x"
-+   timeout         = 30
-+   source_code_hash = data.archive_file.lambda_zip.output_base64sha256
-+
-+   tracing_config {
-+     mode = "Active"
-+   }
-+
-+   environment {
-+     variables = var.env
-+   }
-+
-+   tags = var.tags
-+ }
-
-+ resource "aws_lambda_function" "get_documentation_handler" {
-+   s3_bucket         = aws_s3_object.lambda_zip.bucket
-+   s3_key            = aws_s3_object.lambda_zip.key
-+   s3_object_version = aws_s3_object.lambda_zip.version_id
-+   function_name    = "MyApi-GetDocumentation"
-+   role            = aws_iam_role.lambda_execution_role.arn
-+   handler         = "getDocumentation.handler"  # Specific handler for this operation
-+   runtime         = "nodejs22.x"
-+   timeout         = 30
-+   source_code_hash = data.archive_file.lambda_zip.output_base64sha256
-+
-+   tracing_config {
-+     mode = "Active"
-+   }
-+
-+   environment {
-+     variables = var.env
-+   }
-+
-+   tags = var.tags
-+ }
-
-# Add specific integrations for each operation
-+ resource "aws_apigatewayv2_integration" "say_hello_integration" {
-+   api_id           = module.http_api.api_id
-+   integration_type = "AWS_PROXY"
-+   integration_uri  = aws_lambda_function.say_hello_handler.invoke_arn
-+   payload_format_version = "2.0"
-+   timeout_milliseconds   = 30000
-+ }
-
-+ resource "aws_apigatewayv2_integration" "get_documentation_integration" {
-+   api_id           = module.http_api.api_id
-+   integration_type = "HTTP_PROXY"
-+   integration_uri  = "https://example.com/documentation"
-+   integration_method = "GET"
-+ }
-
-# Add specific routes for each operation
-+ resource "aws_apigatewayv2_route" "say_hello_route" {
-+   api_id    = module.http_api.api_id
-+   route_key = "POST /sayHello"
-+   target    = "integrations/${aws_apigatewayv2_integration.say_hello_integration.id}"
-+   authorization_type = "AWS_IAM"
-+ }
-
-+ resource "aws_apigatewayv2_route" "get_documentation_route" {
-+   api_id    = module.http_api.api_id
-+   route_key = "GET /documentation"
-+   target    = "integrations/${aws_apigatewayv2_integration.get_documentation_integration.id}"
-+   authorization_type = "NONE"
-+ }
-
-# Add Lambda permissions for each function
-+ resource "aws_lambda_permission" "say_hello_permission" {
-+   statement_id  = "AllowExecutionFromAPIGateway-SayHello"
-+   action        = "lambda:InvokeFunction"
-+   function_name = aws_lambda_function.say_hello_handler.function_name
-+   principal     = "apigateway.amazonaws.com"
-+   source_arn    = "${module.http_api.api_execution_arn}/*/*"
-+ }
-
-+ resource "aws_lambda_permission" "get_documentation_permission" {
-+   statement_id  = "AllowExecutionFromAPIGateway-GetDocumentation"
-+   action        = "lambda:InvokeFunction"
-+   function_name = aws_lambda_function.get_documentation_handler.function_name
-+   principal     = "apigateway.amazonaws.com"
-+   source_arn    = "${module.http_api.api_execution_arn}/*/*"
-+ }
-```
-</TabItem>
-<TabItem label="REST API" _filter={{ infra: 'rest-lambda' }}>
-
-```diff
-# packages/common/terraform/src/app/apis/my-api/my-api.tf
-
-# Remove the default single Lambda function
-- resource "aws_lambda_function" "api_lambda" {
--   s3_bucket         = aws_s3_object.lambda_zip.bucket
--   s3_key            = aws_s3_object.lambda_zip.key
--   s3_object_version = aws_s3_object.lambda_zip.version_id
--   function_name    = "MyApiHandler-${random_string.suffix.result}"
--   role            = aws_iam_role.lambda_execution_role.arn
--   handler         = "index.handler"
--   runtime         = "nodejs22.x"
--   timeout         = 30
--   # ... rest of configuration
-- }
-
-# Remove the default proxy integration
-- resource "aws_api_gateway_integration" "lambda_integration" {
--   rest_api_id = module.rest_api.api_id
--   resource_id = aws_api_gateway_resource.proxy_resource.id
--   http_method = aws_api_gateway_method.proxy_method.http_method
--   integration_http_method = "POST"
--   type                    = "AWS_PROXY"
--   uri                     = aws_lambda_function.api_lambda.invoke_arn
--   # ... rest of configuration
-- }
-
-# Remove the default catch-all proxy method
-- resource "aws_api_gateway_method" "proxy_method" {
--   rest_api_id   = module.rest_api.api_id
--   resource_id   = aws_api_gateway_resource.proxy_resource.id
--   http_method   = "ANY"
--   # ... rest of configuration
-- }
-
-# Add individual Lambda functions for each operation using the same bundle
-+ resource "aws_lambda_function" "say_hello_handler" {
-+   s3_bucket         = aws_s3_object.lambda_zip.bucket
-+   s3_key            = aws_s3_object.lambda_zip.key
-+   s3_object_version = aws_s3_object.lambda_zip.version_id
-+   function_name    = "MyApi-SayHello"
-+   role            = aws_iam_role.lambda_execution_role.arn
-+   handler         = "sayHello.handler"  # Specific handler for this operation
-+   runtime         = "nodejs22.x"
-+   timeout         = 30
-+   source_code_hash = data.archive_file.lambda_zip.output_base64sha256
-+
-+   tracing_config {
-+     mode = "Active"
-+   }
-+
-+   environment {
-+     variables = var.env
-+   }
-+
-+   tags = var.tags
-+ }
-
-+ resource "aws_lambda_function" "get_documentation_handler" {
-+   s3_bucket         = aws_s3_object.lambda_zip.bucket
-+   s3_key            = aws_s3_object.lambda_zip.key
-+   s3_object_version = aws_s3_object.lambda_zip.version_id
-+   function_name    = "MyApi-GetDocumentation"
-+   role            = aws_iam_role.lambda_execution_role.arn
-+   handler         = "getDocumentation.handler"  # Specific handler for this operation
-+   runtime         = "nodejs22.x"
-+   timeout         = 30
-+   source_code_hash = data.archive_file.lambda_zip.output_base64sha256
-+
-+   tracing_config {
-+     mode = "Active"
-+   }
-+
-+   environment {
-+     variables = var.env
-+   }
-+
-+   tags = var.tags
-+ }
-
-# Add specific resources and methods for each operation
-+ resource "aws_api_gateway_resource" "say_hello_resource" {
-+   rest_api_id = module.rest_api.api_id
-+   parent_id   = module.rest_api.api_root_resource_id
-+   path_part   = "sayHello"
-+ }
-
-+ resource "aws_api_gateway_method" "say_hello_method" {
-+   rest_api_id   = module.rest_api.api_id
-+   resource_id   = aws_api_gateway_resource.say_hello_resource.id
-+   http_method   = "POST"
-+   authorization = "AWS_IAM"
-+ }
-
-+ resource "aws_api_gateway_integration" "say_hello_integration" {
-+   rest_api_id = module.rest_api.api_id
-+   resource_id = aws_api_gateway_resource.say_hello_resource.id
-+   http_method = aws_api_gateway_method.say_hello_method.http_method
-+
-+   integration_http_method = "POST"
-+   type                   = "AWS_PROXY"
-+   uri                    = aws_lambda_function.say_hello_handler.invoke_arn
-+ }
-
-+ resource "aws_api_gateway_resource" "get_documentation_resource" {
-+   rest_api_id = module.rest_api.api_id
-+   parent_id   = module.rest_api.api_root_resource_id
-+   path_part   = "documentation"
-+ }
-
-+ resource "aws_api_gateway_method" "get_documentation_method" {
-+   rest_api_id   = module.rest_api.api_id
-+   resource_id   = aws_api_gateway_resource.get_documentation_resource.id
-+   http_method   = "GET"
-+   authorization = "NONE"
-+ }
-
-+ resource "aws_api_gateway_integration" "get_documentation_integration" {
-+   rest_api_id = module.rest_api.api_id
-+   resource_id = aws_api_gateway_resource.get_documentation_resource.id
-+   http_method = aws_api_gateway_method.get_documentation_method.http_method
-+
-+   integration_http_method = "GET"
-+   type                   = "HTTP"
-+   uri                    = "https://example.com/documentation"
-+ }
-
-# Update deployment to depend on new integrations
-~ resource "aws_api_gateway_deployment" "api_deployment" {
-    rest_api_id = module.rest_api.api_id
-
-    depends_on = [
--     aws_api_gateway_integration.lambda_integration,
-+     aws_api_gateway_integration.say_hello_integration,
-+     aws_api_gateway_integration.get_documentation_integration,
-    ]
-
-    lifecycle {
-      create_before_destroy = true
-    }
-
-+   triggers = {
-+     redeployment = sha1(jsonencode([
-+       aws_api_gateway_integration.say_hello_integration,
-+       aws_api_gateway_integration.get_documentation_integration,
-+     ]))
-+   }
-  }
-
-# Add Lambda permissions for each function
-+ resource "aws_lambda_permission" "say_hello_permission" {
-+   statement_id  = "AllowExecutionFromAPIGateway-SayHello"
-+   action        = "lambda:InvokeFunction"
-+   function_name = aws_lambda_function.say_hello_handler.function_name
-+   principal     = "apigateway.amazonaws.com"
-+   source_arn    = "${module.rest_api.api_execution_arn}/*/*"
-+ }
-
-+ resource "aws_lambda_permission" "get_documentation_permission" {
-+   statement_id  = "AllowExecutionFromAPIGateway-GetDocumentation"
-+   action        = "lambda:InvokeFunction"
-+   function_name = aws_lambda_function.get_documentation_handler.function_name
-+   principal     = "apigateway.amazonaws.com"
-+   source_arn    = "${module.rest_api.api_execution_arn}/*/*"
-+ }
-```
-</TabItem>
-</Tabs>
+Replace the `for_each` used by the `isolated` pattern with explicit instantiations of the Lambda functions, integrations and permissions for each operation.
 
+:::caution
+Unlike CDK, there is no type-safety in Terraform which will give you a type error if you add a new operation in your application code but forget to declare it in your infrastructure.
+:::
 </Fragment>
 </Infrastructure>
 
 #### Integration Pattern
 
-<Infrastructure>
-<Fragment slot="cdk">
+Generated APIs support two integration patterns:
 
-Generated CDK API constructs support two integration patterns:
-
-- `isolated` creates one Lambda function per operation. This is the default for generated APIs.
+- `isolated` creates one Lambda function per operation. This is the default and recommended option for APIs.
 - `shared` creates a single default router Lambda and reuses it for every operation unless you override specific integrations.
 
-`isolated` gives you finer-grained permissions and configuration per operation. `shared` reduces Lambda and API Gateway integration sprawl while still allowing selective overrides.
+`isolated` gives you finer-grained permissions and configuration per operation, as well as better separation for logs and traces. `shared` reduces the likelihood of encountering cold-starts for low-usage APIs.
 
-For example, setting `pattern` to `'shared'` creates a single function instead of one per integration:
+<Infrastructure>
+<Fragment slot="cdk">
+The integration pattern can be changed at any time in CDK by updating your API construct. For example, setting `pattern` to `'shared'` creates a single function instead of one per integration:
 
 ```ts {6}
 // packages/common/constructs/src/app/apis/my-api.ts
@@ -643,20 +418,71 @@ export class MyApi<...> extends ... {
 ```
 </Fragment>
 <Fragment slot="terraform">
-Terraform modules automatically use the router pattern - this is the default and only supported approach. The generated module creates a single Lambda function that handles all API operations.
-
-You can simply instantiate the default module to get the router pattern:
+Unlike CDK, the integration pattern is baked into the generated module. To change the integration pattern:
 
-```hcl
-# Default router pattern - single Lambda function for all operations
-module "my_api" {
-  source = "../../common/terraform/src/app/apis/my-api"
+<Steps>
+  1. Delete the previously generated API module in `packages/common/terraform/src/app/apis`
+  2. Re-run the API generator with the other integration pattern:
+      <RunGenerator generator="ts#api" requiredParameters={{ integrationPattern: 'shared' }} />
+</Steps>
 
-  asset_bucket_name = module.asset_bucket.bucket_name
+With the `isolated` pattern, the module reads the operations from a generated file:
 
-  # Single Lambda function handles all operations automatically
-  tags = local.common_tags
+```hcl
+# packages/common/terraform/src/app/apis/my-api/my-api.tf
+locals {
+  operations_file = "${path.module}/../../../generated/my-api/operations.json"
+  operations      = fileexists(local.operations_file) ? jsondecode(file(local.operations_file)) : {}
 }
 ```
+
+This file is generated from your API, so you do not need to edit this by hand. Adding an operation to your API application code adds the route and lambda function on the next deploy. It is `.gitignore`d by default; remove the entry if you prefer to check it in.
 </Fragment>
 </Infrastructure>
+
+<OptionFilter when={{ iac: 'terraform', infra: 'rest-lambda' }} description="Raising the REST API path depth limit in Terraform">
+##### Terraform REST API Path Depth Limit
+
+:::caution
+Due to a limitation with Terraform where instances of resources can't reference one another (see [hashicorp/terraform#26697](https://github.com/hashicorp/terraform/issues/26697)), the API Gateway resource tree is built one level at a time rather than recursively, supporting operation paths of up to 16 segments. If an operation's path exceeds this, the plan fails with a message naming the paths that are too deep.
+
+<Drawer title="Supporting deeper paths" trigger="Click here for instructions to support deeper paths should your API require it">
+
+Edit `packages/common/terraform/src/app/apis/<my-api>/<my-api>.tf`:
+
+<Steps>
+  1. Increment `max_path_depth` in `locals`:
+
+      ```hcl
+      locals {
+        max_path_depth = 17
+      }
+      ```
+
+  2. Copy the last `aws_api_gateway_resource` block, incrementing both the resource name and its parent:
+
+      ```hcl
+      resource "aws_api_gateway_resource" "path_depth_16" {
+        for_each = local.path_nodes_by_depth[16]
+
+        rest_api_id = module.rest_api.api_id
+        parent_id   = aws_api_gateway_resource.path_depth_15[each.value.parent].id
+        path_part   = each.value.part
+      }
+      ```
+
+  3. Add the new level to the `resource_ids` local:
+
+      ```hcl
+      locals {
+        resource_ids = merge(
+          ...
+          { for path, resource in aws_api_gateway_resource.path_depth_16 : path => resource.id },
+        )
+      }
+      ```
+</Steps>
+
+</Drawer>
+:::
+</OptionFilter>

package/docs/snippets/rdb/admin-credentials.mdx

@@ -0,0 +1,42 @@
+---
+title: Admin Credentials
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+The Aurora admin (master) user's password is generated and rotated by Aurora itself in AWS Secrets Manager, using [RDS-managed master user passwords](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/rds-secrets-manager.html). Your infrastructure code never receives the password, so it cannot leak into a CloudFormation template or Terraform state file. Aurora rotates the secret every 7 days without any rotation function to deploy or maintain.
+
+The secret is encrypted with the same customer-managed KMS key as the cluster.
+
+Your application never uses these credentials. It connects as a least-privilege database user using IAM authentication — only the migration and create-db-user handlers read the admin secret, and each is granted access to just that secret and its KMS key.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+The admin secret is exposed as `secret.secretArn` on the underlying cluster, and `grantSecretRead` grants a consumer read access to it:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from '@my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', { ... });
+
+db.grantSecretRead(myFunction);
+```
+</Fragment>
+<Fragment slot="terraform">
+
+The admin secret's ARN is exposed as the `secret_arn` output, alongside the `kms_key_arn` needed to decrypt it:
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+}
+
+output "database_secret_arn" {
+  value = module.my_database.secret_arn
+}
+```
+
+An RDS-managed secret holds a JSON object with `username` and `password` only — no connection details. Take the host, port and database name from the module's `writer_endpoint`, `cluster_port` and `database_name` outputs.
+</Fragment>
+</Infrastructure>

package/docs/snippets/rdb/architecture.mdx

@@ -35,4 +35,5 @@ app -> proxy: SQL (IAM auth)
 proxy -> aurora
 migrations -> aurora: Schema migrations
 migrations -> secrets: Admin credentials
+aurora -> secrets: Generates and rotates\nadmin credentials
 ```

package/generators.json

@@ -124,6 +124,13 @@
       "metric": "g19",
       "hidden": true
     },
+    "open-api#json-metadata": {
+      "factory": "./src/open-api/json-metadata/generator",
+      "schema": "./src/open-api/json-metadata/schema.json",
+      "description": "Generate a JSON metadata file describing an OpenAPI specification's operations",
+      "metric": "g72",
+      "hidden": true
+    },
     "preset": {
       "factory": "./src/preset/generator",
       "schema": "./src/preset/schema.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin-mcp",
-  "version": "1.0.0-rc.84",
+  "version": "1.0.0-rc.86",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",

package/src/open-api/json-metadata/schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "OpenApiJsonMetadata",
+  "title": "OpenAPI JSON Metadata",
+  "description": "Generate a JSON metadata file describing an OpenAPI specification's operations",
+  "type": "object",
+  "properties": {
+    "openApiSpecPath": {
+      "type": "string",
+      "description": "Path to the OpenAPI specification relative to the monorepo root",
+      "x-priority": "important"
+    },
+    "outputPath": {
+      "type": "string",
+      "description": "Path to the directory in which to generate the metadata relative to the monorepo root",
+      "x-priority": "important"
+    }
+  },
+  "required": ["openApiSpecPath", "outputPath"]
+}