@aws/nx-plugin-mcp 1.0.0-rc.8 → 1.0.0-rc.80

package/docs/guides/py-rdb.mdx

@@ -0,0 +1,265 @@
+---
+title: Python Relational Database
+description: Create a Python relational database project
+generator: py#rdb
+---
+
+import { FileTree, CardGrid, Tabs, TabItem } from '@astrojs/starlight/components';
+import Astro from '@astrojs/react';
+import ConnectionCard from '@components/connection-card.astro';
+import Infrastructure from '@components/infrastructure.astro';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Snippet from '@components/snippet.astro';
+import OptionFilter from '@components/option-filter.astro';
+
+This generator creates a new Python relational database project backed by [Amazon Aurora](https://aws.amazon.com/rds/aurora/) (PostgreSQL or MySQL), [SQLModel](https://sqlmodel.tiangolo.com/) for data modelling, and [Alembic](https://alembic.sqlalchemy.org/) for schema migrations. It generates the application code and infrastructure needed to provision and manage a database using AWS CDK or Terraform, with declarative schema definition, automatic migration deployment, and a database client.
+
+## Usage
+
+### Generate a Relational Database
+
+<RunGenerator generator="py#rdb" />
+
+### Options
+
+<GeneratorParameters generator="py#rdb" />
+
+## Generator Output
+
+The generator creates the following project structure in the `<directory>/<name>` directory:
+
+<FileTree>
+  - \<name>
+    - \_\_init\_\_.py Package exports (`get_engine`, `session_context`)
+    - connection.py Database engine and session factory with IAM authentication
+    - utils.py Runtime config and local development helpers
+    - migration_handler.py Lambda handler that runs Alembic migrations during deployment
+    - create_db_user_handler.py Lambda handler that creates the application database user during deployment
+    - models
+      - example.py Example SQLModel table definition
+  - migrations
+    - versions Alembic-generated migration scripts
+    - env.py Alembic environment (connects to the database)
+    - script.py.mako Alembic migration script template
+  - alembic.ini Alembic configuration
+  - config.json Local development connection details and runtime config key
+  - Dockerfile.migration Container image for the migration handler
+  - Dockerfile.create-db-user Container image for the create-db-user handler
+  - project.json Project configuration and build targets
+</FileTree>
+
+Local development scripts are shared across all database projects and generated into `packages/common/scripts/`:
+
+<FileTree>
+  - packages/common/scripts/src/rdb
+    - pull-image.ts Pulls the database container image
+    - start-container.ts Starts a local database container
+    - wait-for-postgres-db.ts Waits for the local database to be ready (PostgreSQL)
+    - wait-for-mysql-db.ts Waits for the local database to be ready (MySQL)
+</FileTree>
+
+### Infrastructure
+
+<Snippet name="rdb/infrastructure" />
+
+#### Architecture
+
+<Snippet name="rdb/architecture" />
+
+## Local Development
+
+### Data Modelling
+
+The generated project uses [SQLModel](https://sqlmodel.tiangolo.com/) to define your database schema. The workflow is model-first: add or update SQLModel table classes under your database project's `<name>/models/` directory, then generate a migration from those model changes.
+
+Example model:
+
+```python title="packages/my_db/my_db/models/example.py"
+from sqlalchemy import Column, String
+from sqlmodel import Field, SQLModel
+
+
+class ExampleModel(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(sa_column=Column(String(255), nullable=False))
+    description: str | None = Field(default=None, sa_column=Column(String(255), nullable=True))
+```
+
+Import your models in `<name>/models/__init__.py` so Alembic can discover them during autogeneration.
+
+### Creating Migrations
+
+After adding or updating models, use Alembic to generate and apply migration scripts. The generated `alembic` target automatically starts a local database container before running:
+
+<NxCommands commands={['run <project>:alembic revision --autogenerate -m "describe your change"']} />
+
+This generates a new migration script under `migrations/versions/`. Review the generated script before applying it.
+
+Apply the migration to your local database:
+
+<NxCommands commands={['run <project>:migrate']} />
+
+When you deploy the AWS stack, the generated infrastructure automatically applies the generated migrations to the deployed database.
+
+### Applying Existing Migrations
+
+When you pull migration files created by other developers, apply them to your local database:
+
+<NxCommands commands={['run <project>:migrate']} />
+
+### Running Alembic Commands
+
+The generated `alembic` target exposes the Alembic CLI, so you can run any Alembic command against the local database. See the [Alembic command reference](https://alembic.sqlalchemy.org/en/latest/ops.html) for available commands.
+
+<NxCommands commands={['run <project>:alembic <alembic-command>']} />
+
+### Stopping the Local Database
+
+Stopping `dev` (e.g. with `Ctrl+C`) automatically removes the local database container, but preserves the named volume so your data persists across restarts.
+
+:::caution[Windows]
+Due to limitations with signal handling on Windows, the container is not automatically removed when `dev` is stopped. You will need to remove it manually:
+
+```bash
+<engine> rm -f <scope>-<db-name>
+```
+
+Replace `<engine>` with your container engine (`docker` or `finch`), `<scope>` with your Nx workspace scope (e.g. `proj`), and `<db-name>` with your database project name (e.g. `my-db`).
+:::
+
+## Connecting to the Database
+
+Import `session_context` from your database package and use it as an async context manager to obtain an `AsyncSession`:
+
+```python
+from sqlmodel import select
+
+from my_scope.my_db import session_context
+from my_scope.my_db.models.example import ExampleModel
+
+async def example():
+    async with session_context() as session:
+        results = (await session.execute(select(ExampleModel))).all()
+```
+
+The database client automatically:
+- Retrieves database configuration from AWS AppConfig at runtime
+- Generates temporary authentication tokens via `boto3` RDS Signer for IAM authentication
+- Establishes TLS connections using `ssl.create_default_context()`
+
+<Snippet name="runtime-config-app-id-note" parentHeading="Connecting to the Database" />
+
+## Deploying your Database
+
+<Snippet name="rdb/deploying" parentHeading="Deploying your Database" />
+
+### Image Scanning
+
+<Snippet name="trivy-image-scan" parentHeading="Image Scanning" />
+
+### RDS Proxy Configuration
+
+<Snippet name="rdb/rds-proxy" parentHeading="RDS Proxy Configuration" />
+
+#### SSL Requirements When Connecting Without RDS Proxy
+
+The Amazon RDS CA bundle must be in the runtime's system trust store.
+
+##### Container Runtimes
+
+<Tabs>
+<TabItem label="Amazon Linux">
+
+```dockerfile
+ADD https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem /etc/pki/ca-trust/source/anchors/global-bundle.pem
+RUN update-ca-trust
+```
+
+</TabItem>
+<TabItem label="Debian">
+
+```dockerfile
+ADD https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem /usr/local/share/ca-certificates/rds-global-bundle.crt
+RUN update-ca-certificates
+```
+
+</TabItem>
+</Tabs>
+
+##### Zip Lambda Functions
+
+For zip-deployed Lambda functions (such as a <Link path="guides/fastapi">`py#api` FastAPI</Link>), the Amazon Linux 2023 Lambda execution environment's built-in CA trust store includes the Amazon Root CAs used by RDS.
+
+When using RDS Proxy, you do not need to configure the RDS CA bundle in the runtime that connects to the database.
+
+### Cluster Instances
+
+<Snippet name="rdb/cluster-instances" />
+
+### Serverless Capacity
+
+<Snippet name="rdb/serverless-capacity" />
+
+### Engine Version
+
+<Snippet name="rdb/engine-version" />
+
+### Deletion Protection
+
+<Snippet name="rdb/deletion-protection" />
+
+### Removal Policy
+
+<Snippet name="rdb/removal-policy" />
+
+### Logging and Monitoring
+
+<OptionFilter when={{ engine: 'postgres' }}>
+<Snippet name="rdb/logging-postgres" />
+</OptionFilter>
+
+<OptionFilter when={{ engine: 'mysql' }}>
+<Snippet name="rdb/logging-mysql" />
+</OptionFilter>
+
+<Snippet name="rdb/performance-insights" />
+
+### Encryption Key Rotation
+
+<Snippet name="rdb/encryption-key-rotation" />
+
+## 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:
+
+<CardGrid>
+  <ConnectionCard
+    title="Python Agent to Relational Database"
+    description="Connect a Python Agent to an 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="FastAPI to Relational Database"
+    description="Connect a FastAPI to an 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 MCP Server to Relational Database"
+    description="Connect a Python MCP Server to an 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"
+  />
+</CardGrid>

package/docs/guides/python-lambda-function.mdx

@@ -54,7 +54,7 @@ If the `functionPath` option is provided, the generater will add the necessary f
 
 <Snippet name="shared-constructs" />
 
-The generator creates infrastructure as code for deploying your function based on your selected `iacProvider`:
+The generator creates infrastructure as code for deploying your function based on your selected `iac`:
 
 <Infrastructure>
 <Fragment slot="cdk">

package/docs/guides/react-website-auth.mdx

@@ -43,7 +43,7 @@ You will find the following changes in your React website:
 
 <Snippet name="shared-constructs" />
 
-You will also find the following infrastructure code generated based on your selected `iacProvider`:
+You will also find the following infrastructure code generated based on your selected `iac`:
 
 <Infrastructure>
 <Fragment slot="cdk">
@@ -79,6 +79,11 @@ browser: Web Browser {
   icon: /nx-plugin-for-aws/icons/aws/client.svg
 }
 
+waf: WAF {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/waf.svg
+}
+
 cognito: Cognito\n(User + Identity Pool) {
   shape: image
   icon: /nx-plugin-for-aws/icons/aws/cognito.svg
@@ -93,11 +98,88 @@ backend: Authenticated\nAWS Resources {
   shape: rectangle
 }
 
-browser -> cognito: Sign in
+browser -> waf: Sign in
+waf -> cognito
 cognito -> iam
 browser -> backend: IAM/Cognito
 ```
 
+#### Threat protection
+
+The User Pool is created on the Cognito [Plus feature plan](https://docs.aws.amazon.com/cognito/latest/developerguide/feature-plans-features-plus.html) with [threat protection](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-settings-threat-protection.html) set to `AUDIT` mode for standard authentication. In audit mode, Cognito assigns a risk level to each sign-in and logs the assessment to CloudWatch without blocking users.
+
+Once you have observed the risk assessments for your users, you can switch to full-function enforcement to automatically respond to risky activity (for example requiring MFA or blocking sign-in):
+
+<Infrastructure>
+<Fragment slot="cdk">
+Set `standardThreatProtectionMode` to `StandardThreatProtectionMode.FULL_FUNCTION` in `packages/common/constructs/src/core/user-identity.ts`.
+</Fragment>
+<Fragment slot="terraform">
+Set `advanced_security_mode` to `ENFORCED` in the `user_pool_add_ons` block in `packages/common/terraform/src/core/user-identity/identity/identity.tf`.
+</Fragment>
+</Infrastructure>
+
+#### Multi-factor authentication (MFA)
+
+By default users must configure MFA (an SMS code or a time-based one time password) before they can sign in. You can make MFA optional, turn it off entirely, or restrict which second-factor methods are available:
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts
+import { Mfa } from 'aws-cdk-lib/aws-cognito';
+
+new UserIdentity(this, 'Identity', {
+  mfa: Mfa.OPTIONAL,
+  mfaSecondFactor: { sms: false, otp: true },
+});
+```
+
+`mfa` accepts `Mfa.OFF` / `Mfa.OPTIONAL` / `Mfa.REQUIRED`. `mfaSecondFactor.sms` and `mfaSecondFactor.otp` enable or disable each second-factor method independently; they have no effect when `mfa` is `Mfa.OFF`. Setting `mfa: Mfa.REQUIRED` with both methods disabled is rejected at synth time, since nobody could then complete sign-in.
+</Fragment>
+<Fragment slot="terraform">
+```hcl
+module "user_identity" {
+  source = "../../common/terraform/src/core/user-identity"
+
+  mfa = "OPTIONAL"
+  mfa_second_factor_sms = false
+  mfa_second_factor_otp = true
+}
+```
+
+`mfa` accepts `"OFF"` / `"OPTIONAL"` / `"ON"`. `mfa_second_factor_sms` and `mfa_second_factor_otp` enable or disable each second-factor method independently; they have no effect when `mfa` is `"OFF"`.
+</Fragment>
+</Infrastructure>
+
+:::caution[SMS MFA is tied to phone number verification]
+Cognito rejects SMS-based phone number verification unless SMS is also an enabled MFA method whenever MFA is not off, in both CDK and Terraform. Disabling `mfaSecondFactor.sms` / `mfa_second_factor_sms` while `mfa` is on therefore also disables SMS-based phone number verification for the user pool.
+:::
+
+#### Web Application Firewall (WAF)
+
+By default the User Pool is associated with an [AWS WAFv2](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) Web ACL using the `AWSManagedRulesCommonRuleSet` and `AWSManagedRulesKnownBadInputsRuleSet` managed rule groups. You can disable this if you wish to manage your own Web ACL or do not require one:
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts
+new UserIdentity(this, 'Identity', { enableWaf: false });
+```
+</Fragment>
+<Fragment slot="terraform">
+```hcl
+module "user_identity" {
+  source = "../../common/terraform/src/core/user-identity"
+
+  enable_waf = false
+}
+```
+</Fragment>
+</Infrastructure>
+
+:::caution[`EC2MetaDataSSRF_QUERYARGUMENTS` is set to Count]
+This rule flags loopback addresses in query arguments as [SSRF](https://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-list.html) attempts, which would block local sign-in since the Hosted UI receives a `localhost` `redirect_uri`. It is therefore set to [Count](https://docs.aws.amazon.com/waf/latest/developerguide/web-acl-rule-action.html#web-acl-rule-action-count) while local callback URLs are configured — matches are still logged, and every other rule blocks. Remove the local callback URLs to restore it to Block.
+:::
+
 ## Infrastructure Usage
 
 <Infrastructure>
@@ -107,7 +189,7 @@ You will need to add the user identity infrastructure to your stack, declaring i
 ```ts title="packages/infra/src/stacks/application-stack.ts" {3,9}
 import { Stack } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { MyWebsite, UserIdentity } from ':my-scope/common-constructs';
+import { MyWebsite, UserIdentity } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -152,6 +234,21 @@ The user identity module automatically adds the necessary <Link path="guides/rea
 </Fragment>
 </Infrastructure>
 
+:::caution[Remove localhost callback URLs for production]
+The generated User Pool client allows your CloudFront distribution URL (and any custom domain names configured on it) as OAuth callback/logout URLs, plus `http://localhost:4200` and `http://localhost:4300` for local development against the deployed pool.
+
+It is recommended to **remove the `http://localhost` callback/logout URLs for production stages**, keeping the allowlist limited to your real application origins.
+
+<Infrastructure>
+<Fragment slot="cdk">
+Edit the callback/logout URLs in `packages/common/constructs/src/core/user-identity.ts`.
+</Fragment>
+<Fragment slot="terraform">
+Edit the `callback_urls`/`logout_urls` in `packages/common/terraform/src/core/user-identity/identity/identity.tf`.
+</Fragment>
+</Infrastructure>
+:::
+
 ### Granting Access to Authenticated Users
 
 In order to grant authenticated users access to perform certain actions, such as granting permissions to invoke an API, you can add IAM policy statements to the identity pool authenticated role:
@@ -161,14 +258,16 @@ In order to grant authenticated users access to perform certain actions, such as
 ```ts title="packages/infra/src/stacks/application-stack.ts" {12}
 import { Stack } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { MyWebsite, UserIdentity, MyApi } from ':my-scope/common-constructs';
+import { MyWebsite, UserIdentity, MyApi } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string) {
     super(scope, id);
 
     const identity = new UserIdentity(this, 'Identity');
-    const api = new MyApi(this, 'MyApi');
+    const api = new MyApi(this, 'MyApi', {
+      integrations: MyApi.defaultIntegrations(this).build(),
+    });
 
     api.grantInvokeAccess(identity.identityPool.authenticatedRole);