@aws/nx-plugin-mcp 1.0.0-rc.7 → 1.0.0-rc.71

package/docs/guides/connection/ts-mcp-server-dynamodb.mdx

@@ -1,6 +1,6 @@
 ---
 title: MCP Server to DynamoDB
-description: Connect a TypeScript MCP Server to a DynamoDB table
+description: Connect a TypeScript MCP Server to a TypeScript DynamoDB project
 when:
   sourceType: ts#mcp-server
   targetType: ts#dynamodb
@@ -12,7 +12,7 @@ import NxCommands from '@components/nx-commands.astro';
 import Infrastructure from '@components/infrastructure.astro';
 import Snippet from '@components/snippet.astro';
 
-The `connection` generator wires a <Link path="guides/ts-mcp-server">TypeScript MCP Server</Link> to a <Link path="guides/ts-dynamodb">DynamoDB</Link> project, configuring local development so both start together automatically.
+The `connection` generator wires a <Link path="guides/ts-mcp-server">TypeScript MCP Server</Link> to a <Link path="guides/ts-dynamodb">TypeScript DynamoDB</Link> project, configuring local development so both start together automatically.
 
 ## Prerequisites
 
@@ -35,14 +35,14 @@ Select your MCP server project as the source and your DynamoDB project as the ta
 
 ## Generator Output
 
-The generator updates the MCP server's `<mcp-server-name>-serve-local` target in `project.json` to depend on the DynamoDB project's `serve-local` target. No source files are modified.
+The generator updates the MCP server's `<mcp-server-name>-dev` target in `project.json` to depend on the DynamoDB project's `dev` target. No source files are modified.
 
 ## Using DynamoDB in Tools
 
 Import entity factories from the DynamoDB package and use them inside `createServer`:
 
 ```ts title="packages/my-service/src/my-mcp/server.ts"
-import { createExampleEntity } from ':my-scope/my-table';
+import { createExampleEntity } from '@my-scope/my-table';
 
 export const createServer = async () => {
   const server = new McpServer({ name: 'my-service', version: '1.0.0' });
@@ -67,7 +67,7 @@ To allow the MCP server to access the DynamoDB table, grant the necessary permis
 <Fragment slot="cdk">
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyTable } from ':my-scope/common-constructs';
+import { MyTable } from '@my-scope/common-constructs';
 
 const table = new MyTable(this, 'Table');
 const myMcpServer = new MyMcpServer(this, 'MyMcpServer');

package/docs/guides/connection/ts-mcp-server-rdb.mdx

@@ -46,14 +46,14 @@ The generator modifies two files in your MCP server's source directory:
 
 </FileTree>
 
-Additionally, the `<mcp-server-name>-serve-local` target is updated to depend on the database's `serve-local` target.
+Additionally, the `<mcp-server-name>-dev` target is updated to depend on the database's `dev` target.
 
-## How It Works
+## Using the Database in MCP Tools
 
 The Prisma client is fetched inside `createServer` and available to all tools and resources registered there:
 
 ```ts title="packages/my-service/src/my-mcp/server.ts" {1,4}
-import { getPrisma as getMyDb } from ':my-scope/my-db';
+import { getPrisma as getMyDb } from '@my-scope/my-db';
 
 export const createServer = async () => {
   const myDb = await getMyDb();
@@ -85,10 +85,21 @@ The generated MCP server construct implements `IGrantable` and `IConnectable`, s
 <Fragment slot="cdk">
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyDatabase } from ':my-scope/common-constructs';
+import { SecurityGroup } from 'aws-cdk-lib/aws-ec2';
+import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';
+import { MyDatabase } from '@my-scope/common-constructs';
 
 const db = new MyDatabase(this, 'Db', { vpc, ... });
-const myMcpServer = new MyMcpServer(this, 'MyMcpServer', { vpc, ... });
+
+const myMcpServer = new MyMcpServer(this, 'MyMcpServer', {
+  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(this, {
+    vpc,
+    vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
+    securityGroups: [
+      new SecurityGroup(this, 'MyMcpServerSecurityGroup', { vpc, allowAllOutbound: true }),
+    ],
+  }),
+});
 
 db.allowDefaultPortFrom(myMcpServer);
 db.grantConnect(myMcpServer);
@@ -96,40 +107,79 @@ db.grantConnect(myMcpServer);
 
 `allowDefaultPortFrom` opens the security group rule so the MCP server runtime can reach the database port. `grantConnect` grants IAM `rds-db:connect` permission to the server's execution role.
 
+
 </Fragment>
 <Fragment slot="terraform">
 
-Pass the database module outputs into your MCP server module so it can reach the database and read its runtime configuration:
+Run the MCP server inside the same VPC as the database, grant it `rds-db:connect` via `additional_iam_policy_statements`, and open the network path with a pair of security group rules. The `aws_vpc.main` and `aws_subnet` resources are defined in the database deployment guide:
 
 ```hcl title="packages/infra/src/main.tf"
 module "my_database" {
   source              = "../../common/terraform/src/app/dbs/my-database"
-  vpc_id              = module.vpc.vpc_id
-  database_subnet_ids = module.vpc.private_isolated_subnet_ids
+  vpc_id              = aws_vpc.main.id
+  database_subnet_ids = aws_subnet.database[*].id
+  lambda_subnet_ids   = aws_subnet.private[*].id
 }
 
 module "my_mcp_server" {
-  source = "../../common/terraform/src/app/mcp-servers/my-mcp-server"
+  source     = "../../common/terraform/src/app/mcp-servers/my-mcp-server"
+  enable_vpc = true
+  vpc_id     = aws_vpc.main.id
+  subnet_ids = aws_subnet.private[*].id
+
+  appconfig_application_id  = module.runtime_config_appconfig.application_id
+  appconfig_application_arn = module.runtime_config_appconfig.application_arn
+
+  additional_iam_policy_statements = [
+    {
+      Effect = "Allow"
+      Action = ["rds-db:connect"]
+      Resource = [
+        "arn:aws:rds-db:${data.aws_region.current.region}:${data.aws_caller_identity.current.account_id}:dbuser:${module.my_database.connect_resource_id}/${module.my_database.database_runtime_user}"
+      ]
+    }
+  ]
+}
+
+resource "aws_vpc_security_group_ingress_rule" "mcp_server_to_database" {
+  description                  = "Allow the MCP server runtime to connect to the database"
+  security_group_id            = module.my_database.security_group_id
+  referenced_security_group_id = module.my_mcp_server.security_group_id
+  from_port                    = module.my_database.cluster_port
+  to_port                      = module.my_database.cluster_port
+  ip_protocol                  = "tcp"
+}
 
-  appconfig_application_id     = module.my_database.appconfig_application_id
-  database_cluster_resource_id = module.my_database.cluster_resource_id
-  database_runtime_user        = module.my_database.database_runtime_user
-  database_security_group_id   = module.my_database.security_group_id
-  database_port                = module.my_database.cluster_port
+resource "aws_vpc_security_group_egress_rule" "mcp_server_to_database" {
+  description                  = "Allow outbound traffic from the MCP server runtime to the database"
+  security_group_id            = module.my_mcp_server.security_group_id
+  referenced_security_group_id = module.my_database.security_group_id
+  from_port                    = module.my_database.cluster_port
+  to_port                      = module.my_database.cluster_port
+  ip_protocol                  = "tcp"
 }
 ```
 
-Ensure the MCP server's execution role has `rds-db:connect` permission and that its security group can reach the database security group on the database port.
+`appconfig_application_id`/`appconfig_application_arn` come from the shared <Link path="guides/runtime-config">runtime configuration</Link> AppConfig application declared once in your root module, not from the database module. Include the `database` namespace when instantiating it so the database module's runtime configuration entry is deployed:
+
+```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"
+  namespaces       = ["connection", "agentcore", "database"]
+}
+```
 
 </Fragment>
 </Infrastructure>
 
 ### SSL Requirements When Connecting Without RDS Proxy
 
-<Snippet name="connection/mcp-server-rdb-ssl-requirements" parentHeading="SSL Requirements When Connecting Without RDS Proxy" />
+<Snippet name="connection/ts-mcp-server-rdb-ssl-requirements" parentHeading="SSL Requirements When Connecting Without RDS Proxy" />
 
 ## Local Development
 
-<NxCommands commands={["<mcp-server-name>-serve-local <project-name>"]} />
+<NxCommands commands={["<mcp-server-name>-dev <project-name>"]} />
 
-This starts the MCP server and all connected databases. The `SERVE_LOCAL=true` environment variable causes each Prisma client to connect to its local Docker database instead of Aurora.
+This starts the MCP server and all connected databases. The `LOCAL_DEV=true` environment variable causes each Prisma client to connect to its local Docker database instead of Aurora.

package/docs/guides/connection.mdx

@@ -6,9 +6,25 @@ import Astro from '@astrojs/react';
 import { CardGrid, LinkButton } from '@astrojs/starlight/components';
 import Link from '@components/link.astro';
 import ConnectionCard from '@components/connection-card.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
 
 This generator is used to connect projects together, such as websites calling APIs. Simply select the source project (for example the project that will call your API) and target project (for example your API project), and this generator will handle integrating the two.
 
+:::tip[Sketch it visually]
+Prefer to design your workspace first? The <Link path="get_started/graph-builder">Graph Builder</Link> lets you drag out projects and draw the connections between them, then gives you the commands to scaffold the lot.
+:::
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
 ### Supported Connections
 
 The Connection generator supports the following connections:
@@ -113,28 +129,55 @@ The Connection generator supports the following connections:
     target="aurora"
   />
   <ConnectionCard
-    title="MCP Server to Relational Database"
+    title="TypeScript MCP Server to Relational Database"
     description="Connect a TypeScript MCP Server to an Aurora relational database"
     href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-mcp-server-rdb`}
     source="mcp"
+    sourceBadge="typescript"
     target="aurora"
   />
   <ConnectionCard
-    title="tRPC API to DynamoDB"
+    title="FastAPI to Python Relational Database"
+    description="Connect a FastAPI to a Python Aurora relational database"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-fast-api-rdb`}
+    source="fastapi"
+    target="aurora"
+    targetBadge="python"
+  />
+  <ConnectionCard
+    title="Python Agent to Python Relational Database"
+    description="Connect a Python Agent to a Python Aurora relational database"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-agent-rdb`}
+    source="strands"
+    sourceBadge="python"
+    target="aurora"
+    targetBadge="python"
+  />
+  <ConnectionCard
+    title="Python MCP Server to Python Relational Database"
+    description="Connect a Python MCP Server to a Python Aurora relational database"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-mcp-server-rdb`}
+    source="mcp"
+    sourceBadge="python"
+    target="aurora"
+    targetBadge="python"
+  />
+  <ConnectionCard
+    title="tRPC API to TypeScript DynamoDB"
     description="Connect a tRPC API to a DynamoDB table"
     href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/trpc-dynamodb`}
     source="trpc"
     target="dynamodb"
   />
   <ConnectionCard
-    title="Smithy API to DynamoDB"
+    title="Smithy API to TypeScript DynamoDB"
     description="Connect a Smithy API to a DynamoDB table"
     href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/smithy-dynamodb`}
     source="smithy"
     target="dynamodb"
   />
   <ConnectionCard
-    title="TypeScript Agent to DynamoDB"
+    title="TypeScript Agent to TypeScript DynamoDB"
     description="Connect a TypeScript Agent to a DynamoDB table"
     href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-dynamodb`}
     source="strands"
@@ -142,14 +185,88 @@ The Connection generator supports the following connections:
     target="dynamodb"
   />
   <ConnectionCard
-    title="MCP Server to DynamoDB"
+    title="MCP Server to TypeScript DynamoDB"
     description="Connect a TypeScript MCP Server to a DynamoDB table"
     href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-mcp-server-dynamodb`}
     source="mcp"
     target="dynamodb"
   />
+  <ConnectionCard
+    title="FastAPI to Python DynamoDB"
+    description="Connect a FastAPI to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-fast-api-dynamodb`}
+    source="fastapi"
+    target="dynamodb"
+    targetBadge="python"
+  />
+  <ConnectionCard
+    title="Python Agent to Python DynamoDB"
+    description="Connect a Python Agent to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-agent-dynamodb`}
+    source="strands"
+    sourceBadge="python"
+    target="dynamodb"
+    targetBadge="python"
+  />
+  <ConnectionCard
+    title="Python MCP Server to Python DynamoDB"
+    description="Connect a Python MCP Server to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-mcp-server-dynamodb`}
+    source="mcp"
+    sourceBadge="python"
+    target="dynamodb"
+    targetBadge="python"
+  />
+  <ConnectionCard
+    title="AgentCore Gateway to MCP Server"
+    description="Aggregate an MCP server behind an AgentCore Gateway"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/agentcore-gateway-mcp`}
+    source="agentcore"
+    target="mcp"
+  />
+  <ConnectionCard
+    title="AgentCore Gateway to AgentCore Gateway"
+    description="Aggregate an AgentCore Gateway behind another AgentCore Gateway"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/agentcore-gateway-gateway`}
+    source="agentcore"
+    target="agentcore"
+  />
+  <ConnectionCard
+    title="TypeScript Agent to AgentCore Gateway"
+    description="Connect a TypeScript Agent to an AgentCore Gateway"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-gateway`}
+    source="strands"
+    sourceBadge="typescript"
+    target="agentcore"
+  />
+  <ConnectionCard
+    title="Python Agent to AgentCore Gateway"
+    description="Connect a Python Agent to an AgentCore Gateway"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-agent-gateway`}
+    source="strands"
+    sourceBadge="python"
+    target="agentcore"
+  />
+  <ConnectionCard
+    title="AgentCore Gateway to Agent"
+    description="Front an agent with an AgentCore Gateway as a runtime target"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/agentcore-gateway-agent`}
+    source="agentcore"
+    target="strands"
+  />
+  <ConnectionCard
+    title="React Website to AgentCore Gateway"
+    description="Connect a React website to agents through an AgentCore Gateway"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-agentcore-gateway`}
+    source="react"
+    target="agentcore"
+  />
 </CardGrid>
 
 :::note[Runtime Configuration]
 The connection generator makes use of <Link path="guides/runtime-config">Runtime Configuration</Link> to pass deploy-time values (such as API URLs, Cognito settings, and agent runtime ARNs) between generated projects and components at runtime so they can discover and connect to one another.
 :::
+
+:::tip[Local Development]
+Connected projects can be run on your machine with the `serve` and `dev` targets. See the <Link path="guides/local-development">Local Development</Link> guide for details.
+:::

package/docs/guides/docker-bundling.mdx

@@ -3,15 +3,40 @@ title: Docker Bundling
 description: Build and deploy Docker images for TypeScript and Python projects in an Nx Plugin for AWS workspace.
 ---
 
-import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
+import { FileTree, Tabs, TabItem, Code } from '@astrojs/starlight/components';
 import NxCommands from '@components/nx-commands.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
 import Link from '@components/link.astro';
 import Infrastructure from '@components/infrastructure.astro';
+import TrivyVersion from '@components/trivy-version.astro';
+import { CONTAINER_VERSIONS } from '../../../../../../packages/nx-plugin/src/utils/versions';
 
-Several generators (such as <Link path="/guides/ts-agent">`ts#agent`</Link> and <Link path="/guides/py-agent">`py#agent`</Link>) produce a Docker image that is pushed to Amazon ECR and consumed by AWS infrastructure. This guide describes the pattern they follow so that you can apply it to other use cases — for example, running a <Link path="/guides/fastapi">`py#fast-api`</Link> project on Amazon ECS, or deploying a containerised Express server.
+export const trivyTarget = `{
+  "targets": {
+    "trivy": {
+      "cache": true,
+      "inputs": ["default", "^production"],
+      "outputs": ["{workspaceRoot}/dist/{projectRoot}/trivy"],
+      "executor": "nx:run-commands",
+      "options": {
+        "commands": [
+          "rimraf dist/packages/my-project/trivy",
+          "make-dir dist/packages/my-project/trivy",
+          "ncp packages/my-project/.trivyignore dist/packages/my-project/trivy/.trivyignore",
+          "docker save -o dist/packages/my-project/trivy/image.tar my-scope-my-project:latest",
+          "docker run --rm -v \\"./dist/packages/my-project/trivy\\":/scan public.ecr.aws/aquasecurity/trivy:${CONTAINER_VERSIONS.trivy} image --input /scan/image.tar --ignorefile /scan/.trivyignore --scanners vuln --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 --no-progress -q"
+        ],
+        "parallel": false
+      },
+      "dependsOn": ["docker"]
+    }
+  }
+}`;
+
+Several generators (such as <Link path="/guides/ts-agent">`ts#agent`</Link> and <Link path="/guides/py-agent">`py#agent`</Link>) produce a Docker image that is pushed to Amazon ECR and consumed by AWS infrastructure. This guide describes the pattern they follow so that you can apply it to other use cases — for example, running a <Link path="/guides/fastapi">FastAPI</Link> project on Amazon ECS, or deploying a containerised Express server.
 
 :::tip[Docker or Finch]
-The container engine used to build images is chosen at workspace creation time via the `--containerEngine` flag (`docker`, `finch`, or `infer` — the default — which auto-detects what's installed). [Finch](https://runfinch.com/) is an open-source, drop-in alternative to Docker. The selection is recorded in `aws-nx-plugin.config.mts` and applied to every generator that emits container build commands. CDK image asset builds honour the choice via the `CDK_DOCKER` environment variable.
+The container engine used to build images is chosen at workspace creation time via the `--containers` flag (`docker`, `finch`, or `infer` — the default — which auto-detects what's installed). [Finch](https://runfinch.com/) is an open-source, drop-in alternative to Docker. The selection is recorded in `aws-nx-plugin.config.mts` and applied to every generator that emits container build commands. CDK image asset builds honour the choice via the `CDK_DOCKER` environment variable.
 :::
 
 ## The Pattern
@@ -84,7 +109,7 @@ export default defineConfig([
     output: {
       file: '../../dist/packages/my-project/bundle/index.js',
       format: 'cjs',
-      inlineDynamicImports: true,
+      codeSplitting: false,
     },
     platform: 'node',
   },
@@ -253,6 +278,32 @@ This clears the output directory, then copies both the bundle contents and the `
 
 <NxCommands commands={['docker my-project']} />
 
+## Scanning Images with Trivy
+
+It's good practice to scan your images for known vulnerabilities. The generators that follow this pattern add a `trivy` target which scans the built image with [Trivy](https://trivy.dev/), running from the [ECR-hosted Trivy image](https://gallery.ecr.aws/aquasecurity/trivy), and exits non-zero on `HIGH` or `CRITICAL` findings.
+
+Add a `trivy` target which `dependsOn` your `docker` target. It saves the built image to a tarball and scans it via a workspace-relative bind mount, so the same command works under both `docker` and `finch`:
+
+<Code lang="json" code={trivyTarget} />
+
+Each project's per-image scan targets are aggregated under a workspace-wide `trivy` target, which the vended `trivy` root script runs (`nx run-many --target trivy`).
+
+<PackageManagerShortCommand commands={['trivy']} />
+
+:::tip[Run Trivy in CI]
+The scan is intentionally not wired into `build` since this can introduce unnecessary friction when iterating during development, as Trivy's vulnerabilty database is continually updated with new CVEs.
+
+Instead we recommend running the above command as a dedicated step in your CI pipeline prior to deployment to production stages.
+:::
+
+:::tip[Caching skips unchanged images]
+Because the image is fully determined by your project source, declaring `inputs` (here `default` and `^production`, matching the `bundle` target) lets Nx cache the scan and skip re-scanning an image that hasn't changed. Pin the Trivy image version (e.g. <code>trivy:<TrivyVersion /></code>) so scans are reproducible.
+:::
+
+:::note[Suppressing findings]
+Trivy reads a `.trivyignore` file (a list of vulnerability IDs, one per line) from the root of your project. `--ignore-unfixed` skips vulnerabilities with no available fix, so the scan only fails on issues you can action by upgrading tooling in your `Dockerfile`. See the [Trivy filtering documentation](https://trivy.dev/latest/docs/configuration/filtering/#by-finding-ids) for details.
+:::
+
 ## Infrastructure
 
 Wiring the resulting build-context directory to infrastructure as code is the same for both TypeScript and Python — only the path to the build-context directory differs (`dist/packages/my-project/bundle` for TypeScript, `dist/packages/my-project/docker` for Python).
@@ -291,7 +342,7 @@ infra.asset -> ecr: cdk deploy\nbuilds + pushes
 
 ```ts
 import { DockerImageAsset, Platform } from 'aws-cdk-lib/aws-ecr-assets';
-import { findWorkspaceRoot } from ':my-scope/common-constructs';
+import { findWorkspaceRoot } from '@my-scope/common-constructs';
 import * as path from 'path';
 import * as url from 'url';
 
@@ -305,7 +356,7 @@ const image = new DockerImageAsset(this, 'MyImage', {
 });
 ```
 
-The `findWorkspaceRoot` helper is generated by the <Link path="/guides/typescript-infrastructure">`ts#infra`</Link> generator and exported from `:my-scope/common-constructs`. If you are not using shared constructs, you can hardcode the path to the `dist` directory relative to where `cdk` is invoked from — typically the workspace root — and omit the `findWorkspaceRoot` call entirely.
+The `findWorkspaceRoot` helper is generated by the <Link path="/guides/typescript-infrastructure">`ts#infra`</Link> generator and exported from `@my-scope/common-constructs`. If you are not using shared constructs, you can hardcode the path to the `dist` directory relative to where `cdk` is invoked from — typically the workspace root — and omit the `findWorkspaceRoot` call entirely.
 
 :::note[Running bundle before synth]
 CDK does not run the `bundle`/`docker` targets automatically — you must run `nx build my-project` (or wire the deploy target to depend on `build`) before `cdk deploy`. The generators that use this pattern declare `docker` and `bundle` as dependencies of `build` so this happens transparently.
@@ -318,8 +369,8 @@ Terraform's AWS provider does not have a first-class "build and push a Docker im
 
 1. The project's `build` target runs `docker build`, producing a local image tagged `my-scope-my-project:latest`.
 2. An `aws_ecr_repository` to hold the image.
-3. A `null_resource` with a `local-exec` provisioner that authenticates to ECR, re-tags the locally-built image, and pushes it.
-4. The downstream resource (e.g. `aws_ecs_task_definition`) references `"${aws_ecr_repository.repo.repository_url}:latest"`.
+3. A `null_resource` with a `local-exec` provisioner that authenticates to ECR, re-tags the locally-built image with its content digest, and pushes it.
+4. The downstream resource (e.g. `aws_ecs_task_definition`) references the image by its immutable, digest-based tag.
 
 ```d2
 direction: down
@@ -361,7 +412,7 @@ infra.repo -> ecr
 ```hcl
 resource "aws_ecr_repository" "repo" {
   name                 = "my-project-repository"
-  image_tag_mutability = "MUTABLE"
+  image_tag_mutability = "IMMUTABLE"
   force_delete         = true
 }
 
@@ -370,24 +421,30 @@ data "external" "docker_digest" {
   program = ["sh", "-c", "echo '{\"digest\":\"'$(docker inspect my-scope-my-project:latest --format '{{.Id}}')'\"}'"]
 }
 
+locals {
+  # Content-based, immutable image tag derived from the local image digest
+  image_tag = replace(data.external.docker_digest.result.digest, "sha256:", "")
+}
+
 resource "null_resource" "docker_publish" {
   triggers = {
     docker_digest  = data.external.docker_digest.result.digest
     repository_url = aws_ecr_repository.repo.repository_url
+    image_tag      = local.image_tag
   }
 
   provisioner "local-exec" {
     command = <<-EOT
       aws ecr get-login-password --region ${data.aws_region.current.id} \
         | docker login --username AWS --password-stdin ${self.triggers.repository_url}
-      docker tag my-scope-my-project:latest ${self.triggers.repository_url}:latest
-      docker push ${self.triggers.repository_url}:latest
+      docker tag my-scope-my-project:latest ${self.triggers.repository_url}:${self.triggers.image_tag}
+      docker push ${self.triggers.repository_url}:${self.triggers.image_tag}
     EOT
   }
 }
 ```
 
-The `data.external.docker_digest` block ensures the `null_resource` re-runs whenever the local image hash changes, triggering a new push on every meaningful code change.
+The `data.external.docker_digest` block ensures the `null_resource` re-runs whenever the local image hash changes, triggering a new push on every meaningful code change. The image is pushed under an immutable, content-based tag derived from its digest, so the ECR repository can use `IMMUTABLE` tag mutability and reject any attempt to overwrite an existing tag.
 
 :::note[Running bundle before apply]
 `nx apply <project>` requires the image tag `my-scope-my-project:latest` to already exist locally. Run `nx build my-project` (or `nx docker my-project`) before `nx apply <project>`.