@aws/nx-plugin-mcp 1.0.0-rc.9 → 1.0.0-rc.91

package/docs/snippets/mcp/architecture.mdx

@@ -23,7 +23,7 @@ ecr: ECR {
 
 agentcore: MCP Server\n(AgentCore Runtime) {
   shape: image
-  icon: /nx-plugin-for-aws/icons/aws/bedrock-agentcore.svg
+  icon: /nx-plugin-for-aws/icons/aws/bedrock-agentcore-runtime.svg
 }
 
 cw: CloudWatch\n(Logs, Metrics) {

package/docs/snippets/mcp/bedrock-deployment.mdx

@@ -15,7 +15,7 @@ A CDK construct is generated for your MCP Server, named based on the `name` you
 You can use this CDK construct in a CDK application:
 
 ```ts {6}
-import { MyProjectMcpServer } from ':my-scope/common-constructs';
+import { MyProjectMcpServer } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -64,7 +64,7 @@ By default, your MCP server will be secured using IAM authentication, simply dep
 <Infrastructure>
 <Fragment slot="cdk">
 ```ts {5}
-import { MyProjectMcpServer } from ':my-scope/common-constructs';
+import { MyProjectMcpServer } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -76,7 +76,7 @@ export class ExampleStack extends Stack {
 You can grant access to invoke your MCP server on Bedrock AgentCore Runtime using the `grantInvokeAccess` method. For example you may wish for an agent generated with the <Link path="/guides/py-agent">`py#agent`</Link> generator to call your MCP server:
 
 ```ts {8}
-import { MyProjectAgent, MyProjectMcpServer } from ':my-scope/common-constructs';
+import { MyProjectAgent, MyProjectMcpServer } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -126,7 +126,7 @@ When you select `Cognito` authentication, the generator configures the MCP serve
 The generated construct accepts an `identity` prop which configures Cognito authentication:
 
 ```ts {8}
-import { MyProjectMcpServer, UserIdentity } from ':my-scope/common-constructs';
+import { MyProjectMcpServer, UserIdentity } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -144,7 +144,7 @@ The `UserIdentity` construct can be generated using the <Link path="/guides/reac
 <Fragment slot="terraform">
 The generated module accepts `user_pool_id` and `user_pool_client_ids` variables for Cognito authentication:
 
-```terraform {8-9}
+```terraform {11-12}
 module "user_identity" {
   source = "../../common/terraform/src/core/user-identity"
 }
@@ -164,4 +164,8 @@ module "my_project_mcp_server" {
 
 :::note[Custom OIDC Providers]
 If you require custom JWT authentication with a non-Cognito OIDC provider, you can modify the generated CDK construct or Terraform module for your MCP server directly. Note that the connection generator will only support `IAM` or `Cognito` authentication.
+:::
+
+:::caution[Security Best Practices]
+When implementing your MCP server's business logic, review the [Bedrock AgentCore Runtime security best practices](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-security-best-practices.html).
 :::

package/docs/snippets/mcp/config.mdx

@@ -1,13 +1,14 @@
 ---
 title: MCP Server Configuration
 ---
+
 ```json {3-6}
 {
   "mcpServers": {
     "nx-plugin-for-aws": {
       "command": "npx",
-      "args": ["-y", "@aws/nx-plugin-mcp@next"]
+      "args": ["-y", "@aws/nx-plugin-mcp"]
     }
   }
 }
-```
+```

package/docs/snippets/mcp/shared-constructs.mdx

@@ -12,9 +12,8 @@ For deploying your MCP Server, the following files are generated:
   - packages/common/constructs/src
     - app
       - mcp-servers
-        - \<project-name>
-          - \<project-name>.ts CDK construct for deploying your MCP Server
-          - Dockerfile Passthrough docker file used by the CDK construct
+        - \<mcp-server-name>
+          - \<mcp-server-name>.ts CDK construct for deploying your MCP Server
 </FileTree>
 </Fragment>
 <Fragment slot="terraform">
@@ -22,8 +21,8 @@ For deploying your MCP Server, the following files are generated:
   - packages/common/terraform/src
     - app
       - mcp-servers
-        - \<project-name>
-          - \<project-name>.tf Module for deploying your MCP Server
+        - \<mcp-server-name>
+          - \<mcp-server-name>.tf Module for deploying your MCP Server
     - core
       - agent-core
         - runtime.tf Generic module for deploying to Bedrock AgentCore Runtime

package/docs/snippets/pdk-migration/example/01-migrate-api.mdx

@@ -23,9 +23,9 @@ If you used OpenAPI or TypeSpec as your modelling language, or have handlers imp
 
 #### Generate a TypeScript Smithy API
 
-Run the <Link path="/guides/ts-smithy-api">`ts#smithy-api` generator</Link> to set up your api project in `packages/api`:
+Run the <Link path="/guides/ts-smithy-api">`ts#api` generator</Link> with `framework` set to `smithy` to set up your api project in `packages/api`:
 
-<RunGenerator generator="ts#smithy-api" noInteractive requiredParameters={{ name: 'api', namespace: 'com.aws', auth: 'IAM' }} />
+<RunGenerator generator="ts#api" noInteractive requiredParameters={{ name: 'api', framework: 'smithy', namespace: 'com.aws', auth: 'iam' }} />
 
 You will notice this generates a `model` project, as well as a `backend` project. The `model` project contains your Smithy model, and `backend` contains your server implementation.
 
@@ -128,12 +128,14 @@ You can consider the `api/backend` project as somewhat equivalent to Type Safe A
 
 One of the main differences between Type Safe API and the `ts#smithy-api` generator is that handlers are implemented using the [Smithy Server Generator for TypeScript](https://smithy.io/2.0/languages/typescript/ts-ssdk/index.html), rather than Type Safe API's own generated handler wrappers (found in the `api/generated/typescript/runtime` project).
 
-The shopping list application's lambda handlers rely on the `@aws-sdk/client-dynamodb` package, so let's install that first:
+The shopping list application's lambda handlers rely on the `@aws-sdk/client-dynamodb` package, so let's install that into the `@shopping-list/api` project:
 
-<InstallCommand pkg="@aws-sdk/client-dynamodb" />
+<InstallCommand pkg="@aws-sdk/client-dynamodb" project="@shopping-list/api" />
 
 Then, let's copy the `handlers/src/dynamo-client.ts` file from the PDK project to `backend/src/operations` so it's available for our handlers.
 
+The `ts#smithy-api` generator scaffolds an example `Echo` operation. Since we removed this from our model, delete the corresponding handler in `backend/src/operations/echo.ts`. We'll register our migrated operations in `service.ts` further below.
+
 To migrate the handlers, you can follow these general steps:
 
 <Steps>
@@ -583,7 +585,7 @@ Additionally, update `packages/api/backend/project.json` and update `metadata.ap
     "generator": "ts#smithy-api",
 -    "apiName": "api",
 +    "apiName": "my-api",
-    "auth": "IAM",
+    "auth": "iam",
     "modelProject": "@shopping-list/api-model",
     "ports": [3001]
   },

package/docs/snippets/pdk-migration/example/02-migrate-website.mdx

@@ -11,21 +11,21 @@ import InstallCommand from '@components/install-command.astro';
 
 The `CloudscapeReactTsWebsiteProject` used in the shopping list application configured a React website with CloudScape and Cognito authentication built in.
 
-This project type leveraged [`create-react-app`](https://github.com/facebook/create-react-app), which is now deprecated. For migrating the website in this guide, we will use the <Link path="/guides/react-website">`ts#react-website` generator</Link>, which uses more modern and supported technologies, namely [Vite](https://vite.dev/).
+This project type leveraged [`create-react-app`](https://github.com/facebook/create-react-app), which is now deprecated. For migrating the website in this guide, we will use the <Link path="/guides/react-website">`ts#website` generator</Link>, which uses more modern and supported technologies, namely [Vite](https://vite.dev/).
 
 As part of the migration, we will also move from PDK's configured React Router to [TanStack Router](https://tanstack.com/router), which adds additional type-safety to website routing.
 
 #### Generate a React Website
 
-Run the <Link path="/guides/react-website">`ts#react-website` generator</Link> to set up your website project in `packages/website`:
+Run the <Link path="/guides/react-website">`ts#website` generator</Link> with `framework` set to `react` to set up your website project in `packages/website`. Since the shopping list application is built with CloudScape components, we also set `ux` to `cloudscape` (the default is `shadcn`):
 
-<RunGenerator generator="ts#react-website" noInteractive requiredParameters={{ name: 'website' }} />
+<RunGenerator generator="ts#website" noInteractive requiredParameters={{ name: 'website', framework: 'react', ux: 'cloudscape' }} />
 
 #### Add Cognito Authentication
 
-The React website generator above doesn't bundle cognito authentication by default like `CloudscapeReactTsWebsiteProject`, instead it's added explicitly via the <Link path="/guides/react-website-auth">`ts#react-website#auth` generator</Link>.
+The React website generator above doesn't bundle cognito authentication by default like `CloudscapeReactTsWebsiteProject`, instead it's added explicitly via the <Link path="/guides/react-website-auth">`ts#website#auth` generator</Link>.
 
-<RunGenerator generator="ts#react-website#auth" noInteractive requiredParameters={{ project: 'website', cognitoDomain: 'shopping-list' }} />
+<RunGenerator generator="ts#website#auth" noInteractive requiredParameters={{ project: 'website', cognitoDomain: 'shopping-list' }} />
 
 This adds React components which manage the appropriate redirects to ensure users log in using the Cognito hosted UI. This also adds a CDK construct to deploy the Cognito resources in `packages/common/constructs`, called `UserIdentity`.
 
@@ -57,9 +57,26 @@ This generates the necessary client providers and build targets for your website
 
 #### Add AWS Northstar Dependency
 
-The `CloudscapeReactTsWebsiteProject` automatically included a dependency on `@aws-northstar/ui` which is used in our shopping list application, so we add it here:
+The `CloudscapeReactTsWebsiteProject` automatically included a dependency on `@aws-northstar/ui` which is used in our shopping list application, so we add it to the `@shopping-list/website` project:
 
-<InstallCommand pkg="@aws-northstar/ui" />
+<InstallCommand pkg="@aws-northstar/ui" project="@shopping-list/website" />
+
+`@aws-northstar/ui` bundles a code editor component which depends on `ace-builds`, using a webpack-specific import that Vite cannot resolve. Since our shopping list application doesn't use this component, we exclude it from the bundle by adding it to the `external` configuration within the existing `build` options in `packages/website/vite.config.mts`:
+
+```diff lang="ts"
+// packages/website/vite.config.mts
+  build: {
+    outDir: '../../dist/packages/website/bundle',
+    emptyOutDir: true,
+    reportCompressedSize: true,
+    commonjsOptions: {
+      transformMixedEsModules: true,
+    },
++    rollupOptions: {
++      external: ['ace-builds/webpack-resolver'],
++    },
+  },
+```
 
 #### Move the Components and Pages
 
@@ -79,12 +96,14 @@ Note that you'll now have some build errors visible in your IDE, we'll need to m
 
 #### Migrate from React Router to TanStack Router
 
-Since we're using [file-based routing](https://tanstack.com/router/latest/docs/framework/react/routing/file-based-routing), we can use the website local development server to manage automatically generating route configuration. Let's start the local website server:
+Since we're using [file-based routing](https://tanstack.com/router/latest/docs/framework/react/routing/file-based-routing), we can use the website local development server to manage automatically generating route configuration.
+
+Let's start the local website server:
 
-<NxCommands commands={["serve-local website"]} />
+<NxCommands commands={["dev website"]} />
 
 :::tip
-We're using the `serve-local` target here, which also starts local servers for any APIs which have been connected with `connection`, and hot-reloads if your website, model, or backend changes! This allows us to test our API and website locally before we've even written any CDK code.
+We're using the `dev` target here, which also starts local servers for any APIs which have been connected with `connection`, and hot-reloads if your website, model, or backend changes! This allows us to test our API and website locally before we've even written any CDK code.
 :::
 
 You'll see some errors, but the local website server should start on port `4200`, as well as the local Smithy API server on port `3001`.

package/docs/snippets/pdk-migration/example/03-migrate-infra.mdx

@@ -46,7 +46,7 @@ Since the Nx Plugin for AWS uses [Checkov](https://www.checkov.io/) for security
 
 ```diff lang="ts"
 // constructs/database.ts
-+import { suppressRules } from ':shopping-list/common-constructs';
++import { suppressRules } from '@shopping-list/common-constructs';
 ...
 +suppressRules(
 +  this.shoppingListTable,
@@ -69,7 +69,7 @@ The `UserIdentity` construct can generally be swapped out without changes by adj
 
 ```diff lang="ts"
 -import { UserIdentity } from "@aws/pdk/identity";
-+import { UserIdentity } from ':shopping-list/common-constructs';
++import { UserIdentity } from '@shopping-list/common-constructs';
 ...
 const userIdentity = new UserIdentity(this, `${id}UserIdentity`);
 ```
@@ -93,7 +93,7 @@ Follow the below steps:
     ```diff lang="ts"
     // stacks/application-stack.ts
     -import { MyApi } from "../constructs/apis/myapi";
-    +import { Api } from ':shopping-list/common-constructs';
+    +import { Api } from '@shopping-list/common-constructs';
     ...
     -const myapi = new MyApi(this, "MyApi", {
     -  databaseConstruct,
@@ -139,7 +139,7 @@ Finally, we add the `Website` construct from `packages/common/constructs/src/app
 
 ```diff lang="ts"
 -import { Website } from "../constructs/websites/website";
-+import { Website } from ':shopping-list/common-constructs';
++import { Website } from '@shopping-list/common-constructs';
 ...
 -new Website(this, "Website", {
 -  userIdentity,

package/docs/snippets/pdk-migration/faq/type-safe-api.mdx

@@ -26,7 +26,7 @@ For Python, the [python-fastapi](https://openapi-generator.tech/docs/generators/
 
 ##### Client
 
-For TypeScript clients, you can use the <Link path="/guides/react-website">`ts#react-website` generator</Link> and <Link path="/guides/connection">`connection` generator</Link> with an example `ts#smithy-api` to see how clients are generated and integrated with a website. This configures build targets which generate clients by invoking our `open-api#ts-client` or `open-api#ts-hooks` generators. You can use these generators yourself by pointing them at your OpenAPI Specification.
+For TypeScript clients, you can use the <Link path="/guides/react-website">`ts#website` generator</Link> and <Link path="/guides/connection">`connection` generator</Link> with an example `ts#api` (with `framework` set to `smithy`) to see how clients are generated and integrated with a website. This configures build targets which generate clients by invoking our `open-api#ts-client` or `open-api#ts-hooks` generators. You can use these generators yourself by pointing them at your OpenAPI Specification.
 
 For other languages, you can also see if any of the generators from [OpenAPI Generator](https://openapi-generator.tech/docs/generators#client-generators) fit your needs.
 
@@ -77,117 +77,11 @@ For TypeScript, check out [Smithy TypeScript](https://github.com/smithy-lang/smi
 
 Type Safe API provided a Projen project type named `SmithyShapeLibraryProject` which configured a project which contained Smithy models which could be reused by multiple Smithy-based APIs.
 
-The most straightforward way to achieve this is to do the following:
+The equivalent is the <Link path="/guides/smithy-project">`smithy#project` generator</Link> with `type` set to `shapes`:
 
-###### Create a Shape Library
+<RunGenerator generator="smithy#project" requiredParameters={{ name: 'my-shapes', type: 'shapes' }} />
 
-<Steps>
-
-1. Create your shape library using the `smithy#project` generator:
-
-    <RunGenerator generator="smithy#project" />
-
-    Specify any name for the `serviceName` option, as we will remove the `service` shape.
-
-    :::note
-    This generator is hidden at the time of writing and so you will need to execute it via the CLI.
-    :::
-
-1. Replace the default model in `src` with the shapes you wish to define
-
-1. Update `smithy-build.json` to remove the `plugins` and any unused maven dependencies
-
-1. Replace `build.Dockerfile` with minimal build steps:
-
-    ```docker
-    // build.Dockerfile
-    FROM public.ecr.aws/docker/library/node:24 AS builder
-
-    # Output directory
-    RUN mkdir /out
-
-    # Install Smithy CLI
-    # https://smithy.io/2.0/guides/smithy-cli/cli_installation.html
-    WORKDIR /smithy
-    ARG TARGETPLATFORM
-    RUN if [ "$TARGETPLATFORM" = "linux/arm64" ]; then ARCH="aarch64"; else ARCH="x86_64"; fi && \
-        mkdir -p smithy-install/smithy && \
-        curl -L https://github.com/smithy-lang/smithy/releases/download/1.61.0/smithy-cli-linux-$ARCH.zip -o smithy-install/smithy-cli-linux-$ARCH.zip && \
-        unzip -qo smithy-install/smithy-cli-linux-$ARCH.zip -d smithy-install && \
-        mv smithy-install/smithy-cli-linux-$ARCH/* smithy-install/smithy
-    RUN smithy-install/smithy/install
-
-    # Copy project files
-    COPY smithy-build.json .
-    COPY src src
-
-    # Smithy build with Maven cache mount
-    RUN --mount=type=cache,target=/root/.m2/repository,id=maven-cache \
-        smithy build
-
-    RUN cp -r build/* /out/
-
-    # Export the /out directory
-    FROM scratch AS export
-    COPY --from=builder /out /
-    ```
-
-</Steps>
-
-###### Consume the Shape Library
-
-In your service model project(s), make the following changes to consume the shape library:
-
-<Steps>
-
-1. Update the `compile` target in `project.json` to add the workspace as build context, and a dependency on the shape library's `build` target
-
-    ```json {10,15} "--build-context workspace=." "@my-project/shapes:build"
-    // project.json
-    {
-      "cache": true,
-      "outputs": ["{workspaceRoot}/dist/{projectRoot}/build"],
-      "executor": "nx:run-commands",
-      "options": {
-        "commands": [
-          "rimraf dist/packages/api/model/build",
-          "make-dir dist/packages/api/model/build",
-          "docker build --build-context workspace=. -f packages/api/model/build.Dockerfile --target export --output type=local,dest=dist/packages/api/model/build packages/api/model"
-        ],
-        "parallel": false,
-        "cwd": "{workspaceRoot}"
-      },
-      "dependsOn": ["@my-project/shapes:build"]
-    }
-    ```
-
-1. Update the `build.Dockerfile` to copy the `src` directory from your shape library. For example, assuming the shape library is located in `packages/shapes`:
-
-    ```docker {5}
-    // build.Dockerfile
-    # Copy project files
-    COPY smithy-build.json .
-    COPY src src
-    COPY --from=workspace packages/shapes/src shapes
-    ```
-
-1. Update `smithy-build.json` to add the shapes directory to its `sources`:
-
-    ```json {4} "shapes/"
-    // smithy-build.json
-    {
-      "version": "1.0",
-      "sources": ["src/", "shapes/"],
-      "plugins": {
-      ...
-    }
-    ```
-
-</Steps>
-
-:::note
-Please express your interest on the [GitHub issue here](https://github.com/awslabs/nx-plugin-for-aws/issues/304) if you have a use case for a dedicated Smithy shape library generator.
-:::
+Move the shapes from your `SmithyShapeLibraryProject` into the generated project's `src` folder, then refer to the <Link path="/guides/smithy-project#depending-on-a-shape-library">Smithy project guide</Link> for how to wire the library up as a dependency of your API's model.
 
 #### Interceptors
 
@@ -273,7 +167,7 @@ new MyApi(this, 'MyApi', {
 
 You will need to "stub" your service/router for your service to compile if using the `ts#smithy-api` and the TypeScript Server SDK, eg:
 
-```ts {4}
+```ts {3}
 // service.ts
 export const Service: ApiService<ServiceContext> = {
   ...

package/docs/snippets/prerequisites.mdx

@@ -10,10 +10,7 @@ import Snippet from '@components/snippet.astro';
 
 ### Recommended
 
-- [Docker](https://www.docker.com/) is required for some generators. [Multi-platform builds](https://docs.docker.com/build/building/multi-platform/) must be set up.
-- [Terraform >= 1.12](https://developer.hashicorp.com/terraform/install) is required if you choose to use this for infrastructure as code instead of CDK
-  - verify by running `terraform --version`
-- If you are using [VSCode](https://code.visualstudio.com/), we recommend installing the [Nx Console VSCode Plugin](https://marketplace.visualstudio.com/items?itemName=nrwl.angular-console).
+<Snippet name="recommended-prerequisites" parentHeading="Recommended" />
 
 :::tip[AI Assistant Setup]
 If you use an AI Assistant such as Kiro, Kiro CLI, Cursor, Claude Code or Cline, you may also wish to <Link path="/get_started/building-with-ai">install the Nx Plugin for AWS MCP server.</Link>

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

@@ -0,0 +1,39 @@
+---
+title: RDB Architecture
+---
+
+The deployed database has the following architecture. By default, an [Amazon RDS Proxy](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-proxy.html) sits in front of the Aurora cluster to pool connections and to enable [IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html) — see [Disable RDS Proxy](#disable-rds-proxy) for the alternative. The architecture is the same whether you select the PostgreSQL or MySQL engine; only the Aurora engine flavor differs.
+
+```d2 inline=true
+direction: right
+
+app: Application\n(Lambda, Agent, ...) {
+  shape: hexagon
+}
+
+proxy: RDS Proxy {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/rds.svg
+}
+
+migrations: Migrations Lambda {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/lambda.svg
+}
+
+aurora: Aurora\n(PostgreSQL or MySQL) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/aurora.svg
+}
+
+secrets: Secrets Manager\n(DB credentials) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/secrets-manager.svg
+}
+
+app -> proxy: SQL (IAM auth)
+proxy -> aurora
+migrations -> aurora: Schema migrations
+migrations -> secrets: Admin credentials
+aurora -> secrets: Generates and rotates\nadmin credentials
+```

package/docs/snippets/rdb/cluster-instances.mdx

@@ -0,0 +1,31 @@
+---
+title: Cluster Instances
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+Configure the writer and reader instances for your Aurora cluster.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from '@my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  writer: ClusterInstance.serverlessV2('writer'),
+  readers: [ClusterInstance.serverlessV2('reader')],
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  instance_count = 2  # 1 writer + 1 reader
+}
+```
+</Fragment>
+</Infrastructure>

package/docs/snippets/rdb/deletion-protection.mdx

@@ -0,0 +1,64 @@
+---
+title: Deletion Protection
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+The Aurora cluster is protected by two independent guards, so that turning off either one alone cannot delete your data:
+
+<Infrastructure>
+<Fragment slot="cdk">
+- `deletionProtection`, enforced by RDS.
+- `RemovalPolicy.RETAIN`, enforced by CloudFormation, which leaves the cluster in place when it is removed from the stack.
+</Fragment>
+<Fragment slot="terraform">
+- `deletion_protection`, enforced by RDS.
+- `lifecycle { prevent_destroy = true }` on the cluster in `common/terraform/src/core/rdb/aurora/aurora.tf`, enforced by Terraform, which fails any plan that would destroy the cluster.
+</Fragment>
+</Infrastructure>
+
+#### Deleting the Database
+
+You can disable protection for environments where database deletion is expected, such as short-lived development or preview stacks.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { RemovalPolicy } from 'aws-cdk-lib';
+import { MyDatabase } from '@my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  deletionProtection: false,
+  removalPolicy: RemovalPolicy.DESTROY,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  deletion_protection = false
+  skip_final_snapshot = true
+}
+```
+
+`prevent_destroy` must be a literal — Terraform does not allow it to reference a variable — so it cannot be turned off from `main.tf`. Also remove the `lifecycle` block from the cluster in `common/terraform/src/core/rdb/aurora/aurora.tf`:
+
+```hcl title="packages/common/terraform/src/core/rdb/aurora/aurora.tf" del={4-6}
+resource "aws_rds_cluster" "database" {
+  # ...
+
+  lifecycle {
+    prevent_destroy = true
+  }
+}
+```
+
+:::caution
+This module is shared by every database in your workspace, so removing the block removes that guard for all of them.
+:::
+</Fragment>
+</Infrastructure>