@aws/nx-plugin-mcp 0.119.0 → 0.121.0

package/docs/guides/runtime-config.mdx

@@ -0,0 +1,312 @@
+---
+title: Runtime Configuration
+description: How runtime configuration connects your generated projects using AWS AppConfig
+---
+import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
+import Infrastructure from '@components/infrastructure.astro';
+import Link from '@components/link.astro';
+
+Runtime configuration is the mechanism used by Nx Plugin for AWS to pass deploy-time values between generated projects and components so they can connect to one another. For example, when you generate an API, its URL is automatically registered in the runtime configuration so that a connected website can discover it.
+
+## How It Works
+
+Runtime configuration is organised into **namespaces**. Each namespace is a logical grouping of related configuration values. At deploy time, all namespaces are stored in **AWS AppConfig** as Configuration Profiles.
+
+Two built-in namespaces are used by generated constructs:
+
+- **`connection`** — configuration that enables generated projects to connect to each other:
+  - **API URLs** — registered automatically by API constructs
+  - **Cognito settings** — registered automatically by the UserIdentity construct
+  - **Agent runtime ARNs** — added by the connection generator when you connect a React website to an Agent
+- **`agentcore`** — AgentCore runtime ARNs for agents and MCP servers. Registered automatically by the agent/MCP constructs and used for server-side discovery (agent → agent via A2A, agent → MCP server).
+
+The `connection` namespace is also deployed as a `runtime-config.json` file to your website's S3 bucket, enabling client-side discovery of backend resources. The `agentcore` namespace is server-side only (via AppConfig) so agent runtime ARNs are not exposed to the frontend unless you explicitly connect a website to an agent.
+
+You can define as many additional namespaces as you like, providing a convenient alternative to environment variables for passing deploy-time values such as DynamoDB table names to your Lambda functions or other compute resources.
+
+```d2
+direction: down
+
+iac: "Infrastructure as code\nRuntimeConfig.set(...)"
+
+appconfig: "AWS AppConfig" {
+  shape: cylinder
+  connection: "connection namespace"
+  agentcore: "agentcore namespace"
+  custom: "custom namespaces"
+}
+
+s3: "website S3 bucket" {
+  shape: cylinder
+  rcj: runtime-config.json {
+    shape: page
+  }
+}
+
+website: React website
+
+server: Lambda / agent
+
+iac -> appconfig.connection
+iac -> appconfig.agentcore
+iac -> appconfig.custom
+
+appconfig.connection -> s3.rcj: deployed
+s3.rcj -> website: fetched at load
+
+appconfig.connection -> server
+appconfig.agentcore -> server: Powertools getAppConfig
+appconfig.custom -> server
+```
+
+## Infrastructure
+
+### Writing Configuration
+
+Generated constructs automatically write relevant configuration to the `connection` namespace. You can also write your own values to any namespace.
+
+<Infrastructure>
+<Fragment slot="cdk">
+The `RuntimeConfig` CDK construct is a stage-scoped singleton. Use `set()` to write a key into a namespace:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { RuntimeConfig } from ':my-scope/common-constructs';
+
+const rc = RuntimeConfig.ensure(this);
+
+// Built-in 'connection' namespace (written automatically by generated constructs)
+rc.set('connection', 'apis', {
+  ...rc.get('connection').apis,
+  MyApi: api.url,
+});
+
+// Custom namespaces for server-side configuration
+rc.set('tables', 'users', {
+  tableName: usersTable.tableName,
+  tableArn: usersTable.tableArn,
+});
+```
+
+At synth/deploy time, `RuntimeConfig` creates an **AWS AppConfig** application containing:
+- A **Configuration Profile** for each namespace
+- A **Hosted Configuration Version** with the JSON data for each profile
+- An instant **Deployment** to the `default` environment
+</Fragment>
+<Fragment slot="terraform">
+Terraform wires runtime configuration across three `core/runtime-config/*` modules. Declare them in the following order in your root module:
+
+<Steps>
+
+1. **`core/runtime-config/appconfig`** — declared once, near the top of the root module. Creates the AppConfig application, environment, deployment strategy and one configuration profile per namespace. Its `application_id` and `application_arn` outputs are passed into every module that reads runtime configuration at runtime (agents, MCP servers, Lambda functions, etc.).
+
+   ```hcl title="packages/infra/src/main.tf"
+   module "runtime_config_appconfig" {
+     source = "../../common/terraform/src/core/runtime-config/appconfig"
+
+     application_name = "my-app-runtime-config"
+   }
+   ```
+
+2. **`core/runtime-config/entry`** — one invocation per contribution. Generated API, agent and MCP modules call this internally to publish their URLs and ARNs. Call it directly to publish custom configuration.
+
+   ```hcl title="packages/infra/src/main.tf"
+   # Automatic — done inside generated modules
+   module "add_api_url" {
+     source = "../../common/terraform/src/core/runtime-config/entry"
+
+     namespace = "connection"
+     key       = "apis"
+     value     = { "MyApi" = module.my_api.api_url }
+   }
+
+   # Custom namespace for server-side configuration
+   module "add_table_config" {
+     source = "../../common/terraform/src/core/runtime-config/entry"
+
+     namespace = "tables"
+     key       = "users"
+     value     = {
+       tableName = aws_dynamodb_table.users.name
+       arn       = aws_dynamodb_table.users.arn
+     }
+   }
+   ```
+
+3. **`core/runtime-config/appconfig-deployment`** — declared once, at the end of the root module, with `depends_on` covering every module that contributes an entry. Aggregates the contributed entries into one JSON per namespace and creates the hosted configuration version + deployment against the shared application.
+
+   ```hcl title="packages/infra/src/main.tf"
+   module "runtime_config_appconfig_deployment" {
+     source = "../../common/terraform/src/core/runtime-config/appconfig-deployment"
+
+     application_id            = module.runtime_config_appconfig.application_id
+     environment_id            = module.runtime_config_appconfig.environment_id
+     deployment_strategy_id    = module.runtime_config_appconfig.deployment_strategy_id
+     configuration_profile_ids = module.runtime_config_appconfig.configuration_profile_ids
+     namespaces                = module.runtime_config_appconfig.namespaces
+
+     depends_on = [
+       module.my_api,
+       module.add_table_config,
+       # ...every module that contributes an entry
+     ]
+   }
+   ```
+
+</Steps>
+</Fragment>
+</Infrastructure>
+
+### Reading Configuration
+
+Server-side consumers need the **AppConfig Application ID** and IAM permissions to read configuration at runtime. Generated constructs handle this automatically.
+
+<Infrastructure>
+<Fragment slot="cdk">
+Use `appConfigApplicationId` to get the AppConfig Application ID, and `grantReadAppConfig()` to grant read permissions:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+const rc = RuntimeConfig.ensure(this);
+
+// Get the AppConfig Application ID (lazy token, resolved at synth time)
+const appId = rc.appConfigApplicationId;
+
+// Pass it as an environment variable to a Lambda function
+const myFunction = new Function(this, 'MyFunction', {
+  // ...
+  environment: {
+    RUNTIME_CONFIG_APP_ID: appId,
+  },
+});
+
+// Grant the function permission to read from AppConfig
+rc.grantReadAppConfig(myFunction);
+```
+
+:::note[Automatic Registration]
+Generated API and agent constructs do this automatically — you only need to do this manually if you create your own Lambda functions or compute resources that need to read runtime configuration.
+:::
+</Fragment>
+<Fragment slot="terraform">
+Reference the shared `runtime_config_appconfig` module's `application_id` output to get the AppConfig Application ID, and add the appropriate IAM policy statements:
+
+```hcl title="packages/infra/src/main.tf"
+# Pass the AppConfig Application ID as an environment variable
+resource "aws_lambda_function" "my_function" {
+  # ...
+  environment {
+    variables = {
+      RUNTIME_CONFIG_APP_ID = module.runtime_config_appconfig.application_id
+    }
+  }
+}
+
+# Grant the function permission to read from AppConfig
+resource "aws_iam_policy" "appconfig_read" {
+  name = "AppConfigReadPolicy"
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect = "Allow"
+      Action = [
+        "appconfig:StartConfigurationSession",
+        "appconfig:GetLatestConfiguration"
+      ]
+      Resource = ["${module.runtime_config_appconfig.application_arn}/*"]
+    }]
+  })
+}
+```
+
+:::note[Automatic Registration]
+Generated agent and MCP modules accept `appconfig_application_id` + `appconfig_application_arn` inputs — pass the shared `runtime_config_appconfig` outputs and they wire up the environment variable and IAM permissions for you. You only need to do this manually for custom Lambda functions or compute resources.
+:::
+</Fragment>
+</Infrastructure>
+
+:::tip[Local Development]
+If you use runtime config with custom namespaces (e.g. `tables`, `features`), you only need to define a single `RUNTIME_CONFIG_APP_ID` environment variable locally to point to your deployed AppConfig application. This allows your local APIs or agents to retrieve the same configuration as the deployed environment without needing to replicate all the individual environment variables.
+:::
+
+## Server-Side Access via AppConfig
+
+Server-side consumers such as Lambda functions and agents can retrieve runtime configuration from **AWS AppConfig** using [AWS Lambda Powertools](https://docs.aws.amazon.com/powertools/).
+
+All generated API and agent constructs are automatically configured with:
+- The `RUNTIME_CONFIG_APP_ID` environment variable (the AppConfig Application ID)
+- IAM permissions to read from AppConfig
+
+<Tabs>
+  <TabItem label="TypeScript" icon="seti:typescript">
+
+Use `getAppConfig` from [`@aws-lambda-powertools/parameters`](https://docs.aws.amazon.com/powertools/typescript/latest/features/parameters):
+
+```ts
+import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
+
+// Retrieve the 'connection' namespace as a parsed JSON object
+const config = await getAppConfig('connection', {
+  application: process.env.RUNTIME_CONFIG_APP_ID!,
+  environment: 'default',
+  transform: 'json',
+});
+
+// Access values
+const apiUrl = config.apis?.MyApi;
+const cognitoProps = config.cognitoProps;
+```
+
+You can also retrieve custom namespaces:
+
+```ts
+// Retrieve a custom 'tables' namespace
+const tablesConfig = await getAppConfig('tables', {
+  application: process.env.RUNTIME_CONFIG_APP_ID!,
+  environment: 'default',
+  transform: 'json',
+});
+
+const usersTableName = tablesConfig.users?.tableName;
+```
+
+  </TabItem>
+  <TabItem label="Python" icon="seti:python">
+
+Use `get_app_config` from [`aws_lambda_powertools.utilities.parameters`](https://docs.aws.amazon.com/powertools/python/latest/utilities/parameters/):
+
+```python
+import os
+from aws_lambda_powertools.utilities import parameters
+
+# Retrieve the 'connection' namespace as a parsed JSON object
+config = parameters.get_app_config(
+    name="connection",
+    environment="default",
+    application=os.environ["RUNTIME_CONFIG_APP_ID"],
+    transform="json",
+)
+
+# Access values
+api_url = config.get("apis", {}).get("MyApi")
+cognito_props = config.get("cognitoProps")
+```
+
+You can also retrieve custom namespaces:
+
+```python
+# Retrieve a custom 'tables' namespace
+tables_config = parameters.get_app_config(
+    name="tables",
+    environment="default",
+    application=os.environ["RUNTIME_CONFIG_APP_ID"],
+    transform="json",
+)
+
+users_table_name = tables_config.get("users", {}).get("tableName")
+```
+
+  </TabItem>
+</Tabs>
+
+## Client-Side Access
+
+For websites, the `connection` namespace is deployed as a `runtime-config.json` file to the S3 bucket. See the <Link path="guides/react-website#runtime-configuration">React Website Runtime Configuration</Link> guide for details on how to access these values from your frontend code.

package/docs/guides/terraform-project.mdx

@@ -0,0 +1,317 @@
+---
+title: Terraform Infrastructure
+description: Reference documentation for Terraform Infrastructure
+generator: terraform#project
+---
+import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
+import RunGenerator from '@components/run-generator.astro';
+import Link from '@components/link.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import OptionFilter from '@components/option-filter.astro';
+
+[Terraform](https://www.terraform.io/) is an open-source infrastructure as code software tool that enables you to safely and predictably create, change, and improve infrastructure.
+
+The Terraform infrastructure generator creates a Terraform infrastructure project. The generated application includes security best practices through [Checkov](https://www.checkov.io/) security checks.
+
+## Usage
+
+### Generate a Terraform Project
+
+You can generate a new Terraform project in two ways:
+
+<RunGenerator generator="terraform#project" requiredParameters={{ name: 'tf-infra' }} />
+
+### Options
+
+<GeneratorParameters generator="terraform#project" />
+
+## Generator Output
+
+The generator creates different file structures depending on the project type:
+
+<OptionFilter when={{ type: 'application' }} description="Application type: full Terraform app with remote state management">
+### Application Type
+
+For application projects (`--type=application`), the generator creates a complete Terraform application with remote state management:
+
+<FileTree>
+
+  - src
+    - main.tf Main Terraform configuration file
+    - providers.tf Provider configuration with S3 backend
+    - variables.tf Input variable definitions
+    - outputs.tf Output value definitions
+    - env Environment-specific variable files
+      - dev.tfvars Development environment variables
+  - bootstrap Bootstrap configuration for remote state
+    - 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
+    - aws-config.ts Resolves account + region via the AWS SDK credential chain
+    - bootstrap.ts Pulls/pushes the bootstrap tfstate and runs `terraform apply`
+    - init.ts Runs `terraform init` with the S3 backend config
+  - project.json Project configuration and build targets
+
+</FileTree>
+
+
+:::note[Shared Terraform Modules]
+The generator also creates a `packages/common/terraform` library which initially just adds a metrics module (creates an empty Cloudformation stack with metadata) that is automatically instrumented so that the `nx-plugin-for-aws` team can track usage metrics.
+:::
+</OptionFilter>
+
+<OptionFilter when={{ type: 'library' }} description="Library type: simpler layout for reusable Terraform modules">
+### Library Type
+
+For library projects (`--type=library`), the generator creates a simpler structure for reusable Terraform modules:
+
+<FileTree>
+
+  - src
+    - main.tf Main Terraform module file
+  - project.json Project configuration and build targets
+
+</FileTree>
+</OptionFilter>
+
+:::tip[Application vs Library]
+Application projects include full deployment capabilities with remote state management, while library projects are designed for creating reusable Terraform modules that can be consumed by other projects.
+:::
+
+## Implementing your Terraform Infrastructure
+
+You can start writing your Terraform infrastructure inside `src/main.tf`, for example:
+
+```diff title="src/main.tf" {2-4}
+-locals {
+-  account_id = data.aws_caller_identity.current.account_id
+-  aws_region = data.aws_region.current.id
+-}
+-
+-resource "null_resource" "print_info" {
+-  # triggers = {
+-  #   always_run = timestamp()
+-  # }
+-
+-  provisioner "local-exec" {
+-    command = "echo 'AWS Region: ${local.aws_region}, AWS Account: ${local.account_id}, Environment: ${var.environment}'"
+-  }
+-}
++
++# Declare your infrastructure here
++resource "aws_s3_bucket" "my_bucket" {
++  bucket = "my-unique-bucket-name"
++}
+```
+
+### Cross project dependencies
+
+If you wanted to execute a module from a seperate project (lib), you could do so as follows:
+
+```
+module "lib_module" {
+  source = "../../path/to/my-lib/src"
+}
+```
+
+This will automatically update the Nx graph to add a dependency between your consuming application and your lib.
+
+### Environment Configuration
+
+Configure environment-specific variables in the `src/env/*.tfvars` files.
+
+To add new environments, create a new `src/env/<environment>.tfvars` file with the environment-specific variables and add new entries for `apply, destroy, init, plan` in the `project.json` for the new env configuration. For example, let's assume we want to add a `prod` env:
+
+<Tabs>
+<TabItem label="src/env/prod.tfvars">
+```hcl
+# Production environment variables
+environment = "prod"
+region      = "us-west-2"
+```
+</TabItem>
+<TabItem label="project.json">
+```diff
+{
+  "targets": {
+        "apply": {
+            "executor": "nx:run-commands",
+            "defaultConfiguration": "dev",
+            "configurations": {
+                "dev": {
+                    "command": "terraform apply ../../../dist/packages/infra/terraform/dev.tfplan"
+                },
++                "prod": {
++                    "command": "terraform apply ../../../dist/packages/infra/terraform/prod.tfplan"
++                }
+            },
+            "options": {
+                "forwardAllArgs": true,
+                "cwd": "{projectRoot}/src"
+            },
+            "dependsOn": ["plan"]
+        },
+        "destroy": {
+            "executor": "nx:run-commands",
+            "defaultConfiguration": "dev",
+            "configurations": {
+                "dev": {
+                    "command": "terraform destroy -var-file=env/dev.tfvars"
+                },
++                "prod": {
++                    "command": "terraform destroy -var-file=env/prod.tfvars"
++                }
+            },
+            "options": {
+                "forwardAllArgs": true,
+                "cwd":"{projectRoot}/src"
+            },
+            "dependsOn": ["init"]
+        },
+        "init": {
+            "executor": "nx:run-commands",
+            "defaultConfiguration": "dev",
+            "configurations": {
+                "dev": {
+                    "env": { "TF_ENV": "dev" }
+                },
++                "prod": {
++                    "env": { "TF_ENV": "prod" }
++                }
+            },
+            "options": {
+                "forwardAllArgs": true,
+                "commands": ["tsx {projectRoot}/scripts/init.ts {projectRoot}"],
+                "cwd": "{workspaceRoot}"
+            }
+        },
+        "plan": {
+            "executor": "nx:run-commands",
+            "defaultConfiguration": "dev",
+            "configurations": {
+                "dev": {
+                    "command": "terraform plan -var-file=env/dev.tfvars -out=../../../dist/packages/infra/terraform/dev.tfplan"
+                },
++                "prod": {
++                    "command": "terraform plan -var-file=env/dev.tfvars -out=../../../dist/packages/infra/terraform/prod.tfplan"
++                }
+            },
+            "options": {
+                "forwardAllArgs": true,
+                "cwd": "{projectRoot}/src"
+            },
+            "dependsOn": ["init"]
+        }
+    }
+}
+```
+</TabItem>
+</Tabs>
+
+:::tip[Default Environment]
+By default, all targets assume `dev` environment, however you can target a specific environment as follows: <NxCommands commands={['apply tf-infra --configuration=prod']} />
+
+You can also swap environment at any time as the state segments the tfstate automatically between environments.
+:::
+
+<OptionFilter when={{ type: 'application' }} description="Remote state bootstrap is application-only">
+### Remote State Bootstrap (Application Projects Only)
+
+Before deploying your infrastructure, you'll need to bootstrap the remote state backend. This creates an S3 bucket to store your Terraform state files:
+
+<NxCommands commands={['bootstrap tf-infra']} />
+
+:::note[AWS Profile Configuration]
+Ensure your AWS CLI profile is configured to the account/region you wish to deploy the bootstrap resources into.
+
+The bootstrap target is only available for application type projects. Library projects don't require remote state management as they are designed to be reusable modules.
+:::
+</OptionFilter>
+
+## Available Targets
+
+The available targets depend on your project type:
+
+### Common Targets (Both Application and Library)
+
+#### Validating your Infrastructure
+
+You can validate your Terraform configuration using the `validate` target:
+
+<NxCommands commands={['validate tf-infra']} />
+
+#### Formatting your Code
+
+Format your Terraform code using the `fmt` target:
+
+<NxCommands commands={['fmt tf-infra']} />
+
+#### Security Testing
+
+Run security checks on your infrastructure using Checkov with the `test` target:
+
+<NxCommands commands={['test tf-infra']} />
+
+You will find your security test results in the root `dist` folder, under `dist/packages/<my-terraform-project>/checkov`.
+
+<OptionFilter when={{ type: 'application' }} description="Application-only targets: plan / apply / destroy / etc.">
+### Application-Only Targets
+
+The following targets are only available for application type projects:
+
+#### Planning your Infrastructure
+
+Before applying changes, you can see what Terraform will do by running the `plan` target:
+
+<NxCommands commands={['plan tf-infra']} />
+
+This will create a plan file in `dist/packages/<my-terraform-project>/terraform/dev.tfplan`.
+
+#### Initializing Terraform
+
+Initialize your Terraform working directory with the `init` target:
+
+<NxCommands commands={['run tf-infra:init']} />
+
+#### Deploying to AWS
+
+After planning, you can deploy your infrastructure to AWS using the `apply` target:
+
+<NxCommands commands={['apply tf-infra']} />
+
+:::tip[Auto-Approve]
+The above command applies the plan created by the `plan` target. Make sure to run `plan` first to review the changes.
+:::
+
+:::note[Deploy Alias]
+A `deploy` target is also available as an alias for `apply`. You can use either <NxCommands commands={['deploy tf-infra']} /> or <NxCommands commands={['apply tf-infra']} /> interchangeably.
+:::
+
+#### Getting Outputs
+
+Retrieve output values from your Terraform configuration:
+
+<NxCommands commands={['output tf-infra']} />
+
+#### Destroying Infrastructure
+
+When you need to tear down your infrastructure, use the `destroy` target:
+
+<NxCommands commands={['destroy tf-infra']} />
+
+:::caution[Destructive Operation]
+This will permanently delete all resources managed by this Terraform configuration. Use with caution!
+:::
+
+#### Destroying Bootstrap Resources
+
+To clean up the bootstrap resources (S3 bucket for state storage):
+
+<NxCommands commands={['bootstrap-destroy tf-infra']} />
+</OptionFilter>
+
+## More Information
+
+For more information about Terraform, please refer to the [Terraform Documentation](https://www.terraform.io/docs) and [AWS Provider Documentation](https://registry.terraform.io/providers/hashicorp/aws/latest/docs).