@aws/nx-plugin-mcp 0.119.0 → 0.121.0

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

@@ -0,0 +1,161 @@
+---
+title: Migrate the Infrastruture
+---
+import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
+import CreateNxWorkspaceCommand from '@components/create-nx-workspace-command.astro';
+import RunGenerator from '@components/run-generator.astro';
+import Link from '@components/link.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Drawer from '@components/drawer.astro';
+import InstallCommand from '@components/install-command.astro';
+
+The last project we need to migrate for our shopping list application is the `InfrastructureTsProject`. This is a TypeScript CDK project, for which the Nx Plugin for AWS equivalent is the <Link path="/guides/typescript-infrastructure">`ts#infra` generator</Link>.
+
+As well as the Projen projects, PDK also vended CDK constructs which these projects depend on. We will migrate the shopping list application from these CDK constructs too, in favour of the ones generated by the Nx Plugin for AWS.
+
+:::tip
+A big advantage of the Nx Plugin for AWS over PDK is that the CDK constructs it vends are source code added to your project rather than imported via a third party package. This gives you the control and flexibility to customise them beyond what PDK suppported.
+:::
+
+#### Generate a TypeScript CDK Infrastructure Project
+
+Run the <Link path="/guides/typescript-infrastructure">`ts#infra` generator</Link> to set up your infrastructure project in `packages/infra`:
+
+<RunGenerator generator="ts#infra" noInteractive requiredParameters={{ name: 'infra' }} />
+
+#### Migrate the CDK Infrastructure
+
+The PDK shopping list application instantiated the following constructs within the CDK application stack:
+
+- `DatabaseConstruct` for the DynamoDB table storing shopping lists
+- `UserIdentity` for Cognito resources, imported directly from PDK
+- `MyApi` for deploying the Smithy API, which used the generated TypeScript CDK construct with type-safe integrations, depending on PDK's `TypeSafeRestApi` CDK construct under the hood.
+- `Website` for deploying the Website, wrapping PDK's `StaticWebsite` CDK construct.
+
+Next, we will migrate each of these to the new project.
+
+##### Copy the Application Stack
+
+Copy `packages/infra/src/stacks/application-stack.ts` from the PDK shopping list application to the exact same location in your new project. You'll see some TypeScript errors which we'll address below.
+
+##### Copy the Database Construct
+
+The PDK shopping list application had a `Database` construct in `packages/src/constructs/database.ts`. Copy this to the exact same location in your new project.
+
+Since the Nx Plugin for AWS uses [Checkov](https://www.checkov.io/) for security tests which is a little stricter than PDK Nag, we also need to add some suppressions:
+
+```diff lang="ts"
+// constructs/database.ts
++import { suppressRules } from ':shopping-list/common-constructs';
+...
++suppressRules(
++  this.shoppingListTable,
++  ['CKV_AWS_28', 'CKV_AWS_119'],
++  'Backup and KMS key not required for this project',
++);
+```
+
+In `application-stack.ts`, update the import for the `DatabaseConstruct` to use ESM syntax:
+
+```diff lang="ts"
+// stacks/application-stack.ts
+-import { DatabaseConstruct } from '../constructs/database';
++import { DatabaseConstruct } from '../constructs/database.js';
+```
+
+##### Migrate the UserIdentity Construct
+
+The `UserIdentity` construct can generally be swapped out without changes by adjusting the imports.
+
+```diff lang="ts"
+-import { UserIdentity } from "@aws/pdk/identity";
++import { UserIdentity } from ':shopping-list/common-constructs';
+...
+const userIdentity = new UserIdentity(this, `${id}UserIdentity`);
+```
+
+Note that the underlying constructs used by the new `UserIdentity` construct are vended directly from `aws-cdk-lib`, where PDK used `@aws-cdk/aws-cognito-identitypool-alpha`.
+
+##### Migrate the API Construct
+
+The PDK shopping list application had a construct in `constructs/apis/myapi.ts` which instantiated a CDK construct which Type Safe API generated from your Smithy model.
+
+As well as this construct, since the PDK project used the `@handler` trait, generated lambda function CDK constructs were also generated.
+
+Like Type Safe API, the Nx Plugin for AWS provides type-safety for integrations based on your Smithy model, however it's achieved in a much simpler and more flexible way. Instead of generating an entire CDK construct at build time, only minimal "metadata" is generated, which the `packages/common/constructs/src/app/apis/api.ts` uses in a generic fashion. You can learn more about how to use the construct in the <Link path="/guides/ts-smithy-api">`ts#smithy-api` generator guide</Link>.
+
+Follow the below steps:
+
+<Steps>
+
+1. Instantiate the `Api` construct in `application-stack.ts`
+
+    ```diff lang="ts"
+    // stacks/application-stack.ts
+    -import { MyApi } from "../constructs/apis/myapi";
+    +import { Api } from ':shopping-list/common-constructs';
+    ...
+    -const myapi = new MyApi(this, "MyApi", {
+    -  databaseConstruct,
+    -  userIdentity,
+    -});
+    +const api = new Api(this, 'MyApi', {
+    +  integrations: Api.defaultIntegrations(this).build(),
+    +});
+    ```
+
+    Notice here we use `Api.defaultIntegrations(this).build()` - the default behaviour is to create a lambda function for each operation in our API, which is the same behaviour we had in `myapi.ts`.
+
+1. Grant permissions for the lambda functions to access the DynamoDB table.
+
+    In the PDK shopping list application, the `DatabaseConsruct` was passed into `MyApi`, and it managed adding the relevant permissions to each generated function construct. We'll do this directly in the `application-stack.ts` file by accessing the `Api` construct's type-safe `integrations` property:
+
+    ```ts
+    // stacks/application-stack.ts
+    // Grant our lambda functions scoped access to call Dynamo
+    databaseConstruct.shoppingListTable.grantReadData(
+      api.integrations.getShoppingLists.handler,
+    );
+    [
+      api.integrations.putShoppingList.handler,
+      api.integrations.deleteShoppingList.handler,
+    ].forEach((f) => databaseConstruct.shoppingListTable.grantWriteData(f));
+    ```
+
+1. Grant permissions for authenticated users to invoke the API.
+
+    Within the PDK application's `myapi.ts`, authenticated users were also granted IAM permissions to invoke the API. We will do the equivalent in `application-stack.ts`:
+
+    ```ts
+    // stacks/application-stack.ts
+    api.grantInvokeAccess(userIdentity.identityPool.authenticatedRole);
+    ```
+
+</Steps>
+
+##### Migrate the Website Construct
+
+Finally, we add the `Website` construct from `packages/common/constructs/src/app/static-websites/website.ts` to `application-stack.ts`, since this is the equivalent of the PDK shopping list application's `packages/infra/src/constructs/websites/website.ts`.
+
+```diff lang="ts"
+-import { Website } from "../constructs/websites/website";
++import { Website } from ':shopping-list/common-constructs';
+...
+-new Website(this, "Website", {
+-  userIdentity,
+-  myapi,
+-});
++new Website(this, 'Website');
+```
+
+Notice that we don't pass the identity or API to the website - runtime config is managed within each construct vended by the Nx Plugin for AWS, where `UserIdentity` and `Api` register the necessary values, and `Website` manages deploying it to `/runtime-config.json` on your static website.
+
+Let's build the project now that we've migrated all the relevant parts of the codebase to our new project.
+
+<NxCommands commands={["run-many --target build"]} />
+
+:::caution
+You may see a build failure due to lint issues. These can usually be automatically fixed:
+
+<NxCommands commands={["run-many --target lint --fix"]} />
+:::

package/docs/snippets/pdk-migration/example/04-deploy.mdx

@@ -0,0 +1,229 @@
+---
+title: Deploy
+---
+import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
+import CreateNxWorkspaceCommand from '@components/create-nx-workspace-command.astro';
+import RunGenerator from '@components/run-generator.astro';
+import Link from '@components/link.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Drawer from '@components/drawer.astro';
+import InstallCommand from '@components/install-command.astro';
+
+
+Now we've got our fully migrated codebase, we can look at deploying it. There are two paths we can take at this point.
+
+#### All-New Resources (Simple)
+
+The simplest approach is to treat this as a completely new application, meaning we'll "start again" with a fresh DynamoDB table and Cognito User Pool - losing all users and their shopping lists. For this approach, simply:
+
+<Steps>
+
+1. Delete the DynamoDB table named `shopping_list`
+
+1. Deploy the new application:
+
+    <NxCommands commands={["deploy infra shopping-list-infra-sandbox/*"]} />
+
+</Steps>
+
+🎉 And we're done! 🎉
+
+#### Migrate Existing Stateful Resources with no Outage (More Complex)
+
+In reality, it's more likely that you will want to migrate existing AWS resources so that they are managed by the new codebase, while avoiding any downtime for your customers.
+
+:::danger
+This approach is a bit more nuanced and complex, and this is just an example, so it's STRONGLY recommended to practice in a non-production environment (ideally create a new sandbox stack) and document the exact steps for your application. It is also recommended to write up contingency/rollback plans in case of steps failing or producing unexpected results.
+:::
+
+:::note
+Our PDK shopping list application didn't define any custom domains or DNS. In practice you'd most likely have domains configured for your website and API. For the purpose of this section of the guide, we'll assume that we've set up Route53 with custom DNS names for the website and API.
+:::
+
+For our shopping list application, the stateful resources we care about are the DynamoDB table which contains our users' shopping lists, and the User Pool which contains the details of all of our registered users. Our high level plan will be to retain these two key resources and move them such that they're managed by our new stack, then to update DNS to point to our new website (and API if exposed to customers).
+
+<Steps>
+
+1. Update your new application to reference the existing resources you wish to retain.
+
+    For the shopping list application, we do this for the DynamoDB table
+
+    ```diff lang="ts"
+    // constructs/database.ts
+    -this.shoppingListTable = new Table(this, 'ShoppingList', {
+    -  ...
+    +this.shoppingListTable = Table.fromTableName(
+    +  this,
+    +  'ShoppingList',
+    +  'shopping_list',
+    +);
+    ```
+
+    And for the Cognito User Pool
+
+    ```diff lang="ts"
+    // packages/common/constructs/src/core/user-identity.ts
+    -this.userPool = this.createUserPool();
+    +this.userPool = UserPool.fromUserPoolId(
+    +  this,
+    +  'UserPool',
+    +  '<your-user-pool-id>',
+    +);
+    ```
+
+1. Build and deploy the new application:
+
+    <NxCommands commands={["run-many --target build"]} />
+
+    <NxCommands commands={["deploy infra shopping-list-infra-sandbox/*"]} />
+
+    Now we have our new application stood up referencing the existing resources, not yet taking any traffic.
+
+1. Perform full integration testing to ensure the new application works as expected. For the shopping list application, load the website and check you can sign in and create, view, edit and delete shopping lists.
+
+1. Revert the changes which reference the existing resources in your new application, but do not deploy them yet.
+
+    ```diff lang="ts"
+    // constructs/database.ts
+    +this.shoppingListTable = new Table(this, 'ShoppingList', {
+    +  ...
+    -this.shoppingListTable = Table.fromTableName(
+    -  this,
+    -  'ShoppingList',
+    -  'shopping_list',
+    -);
+    ```
+
+    And for the Cognito User Pool
+
+    ```diff lang="ts"
+    // packages/common/constructs/src/core/user-identity.ts
+    +this.userPool = this.createUserPool();
+    -this.userPool = UserPool.fromUserPoolId(
+    -  this,
+    -  'UserPool',
+    -  '<your-user-pool-id>',
+    -);
+    ```
+
+    And then run a build
+
+    <NxCommands commands={["run-many --target build"]} />
+
+1. Use `cdk import` in your new application's `packages/infra` folder to see which resources we'll be prompted to import.
+
+    ```bash title="New Application"
+    cd packages/infra
+    pnpm exec cdk import shopping-list-infra-sandbox/Application --force
+    ```
+
+    Step through the prompts by hitting enter. The import will fail because the resources are managed by another stack - this is expected, we just did this step to confirm which resources we'll need to retain. You'll see output like this:
+
+    ```bash wrap
+    shopping-list-infra-sandbox/Application/ApplicationUserIdentity/UserPool/smsRole/Resource (AWS::IAM::Role): enter RoleName (empty to skip)
+    shopping-list-infra-sandbox/Application/ApplicationUserIdentity/UserPool/Resource (AWS::Cognito::UserPool): enter UserPoolId (empty to skip)
+    shopping-list-infra-sandbox/Application/Database/ShoppingList/Resource (AWS::DynamoDB::Table): import with TableName=shopping_list (y/n) y
+    ```
+
+    This tells us that there are actually 3 resources we'll need to import into our new stack.
+
+1. Update your old PDK project to set `RemovalPolicy` to `RETAIN` for the resources discovered from the previous step. At the time of writing this is the default for both the User Pool and the DynamoDB table, but we need to update it for the SMS Role we discovered above:
+
+    ```diff lang="ts"
+    // application-stack.ts
+    const userIdentity = new UserIdentity(this, `${id}UserIdentity`, {
+      userPool,
+    });
+
+    +const smsRole = userIdentity.userPool.node.findAll().filter(
+    +  c => CfnResource.isCfnResource(c) &&
+    +    c.node.path.includes('/smsRole/'))[0] as CfnResource;
+    +smsRole.applyRemovalPolicy(RemovalPolicy.RETAIN);
+    ```
+
+1. Deploy your PDK project so that the removal policies are applied
+
+    ```bash title="PDK Application"
+    cd packages/infra
+    npx projen deploy
+    ```
+
+1. Take a look at the CloudFormation console and record the values you were prompted for in the above `cdk import` step
+
+    1. The User Pool ID, eg `us-west-2_XXXXX`
+    2. The SMS Role Name, eg `infra-sandbox-UserIdentityUserPoolsmsRoleXXXXXX`
+
+1. Update your PDK project to reference the existing resources instead of creating them
+
+    ```diff lang="ts"
+    // constructs/database.ts
+    -this.shoppingListTable = new Table(this, 'ShoppingList', {
+    -  ...
+    +this.shoppingListTable = Table.fromTableName(
+    +  this,
+    +  'ShoppingList',
+    +  'shopping_list',
+    +);
+    ```
+
+    And for the Cognito User Pool
+
+    ```diff lang="ts"
+    // application-stack.ts
+    +const userPool = UserPool.fromUserPoolId(
+    +  this,
+    +  'UserPool',
+    +  '<your-user-pool-id>',
+    +);
+    const userIdentity = new UserIdentity(this, `${id}UserIdentity`, {
+    +  // PDK construct accepts UserPool not IUserPool, but this still works!
+    +  userPool: userPool as any,
+    });
+    ```
+
+1. Deploy your PDK project again, this will mean the resources are no longer managed by our PDK project's CloudFormation stack.
+
+    ```bash title="PDK Application"
+    cd packages/infra
+    npx projen deploy
+    ```
+
+1. Now that the resources are unmanaged, we can run `cdk import` in our new application to actually perform the import:
+
+    ```bash title="New Application"
+    cd packages/infra
+    pnpm exec cdk import shopping-list-infra-sandbox/Application --force
+    ```
+
+    Enter the values when prompted, the import should complete successfully.
+
+1. Deploy the new application again to make sure that any changes to these existing resources (now managed by your new stack) are made:
+
+    <NxCommands commands={["deploy infra shopping-list-infra-sandbox/*"]} />
+
+1. Perform a full test of your new application again
+
+1. Update DNS records to point to your new Website (and API if required).
+
+    We recommend a gradual approach using Route53 [Weighted Routing](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy-weighted.html), whereby a fraction of requests are directed to the new application to begin with. As you monitor your metrics you can increase the weight for the new application until no traffic is sent to your old PDK application.
+
+    If you don't have any DNS and used the auto-generated domains for the website and API, you can always look at proxying requests (eg via a [CloudFront HTTP origin](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront_origins-readme.html#from-an-http-endpoint) or [API Gateway HTTP integration(s)](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.HttpIntegration.html)).
+
+1. Monitor PDK application metrics to ensure there is no traffic, and finally destroy the old CloudFormation stack:
+
+    ```bash
+    cd packages/infra
+    npx projen destroy
+    ```
+
+</Steps>
+
+That was quite a bit more involved, but we successfully migrated our users seamlessly to the new application! 🎉🎉🎉
+
+We now have the new benefits of the Nx Plugin for AWS over PDK:
+
+- Faster builds
+- Local API development support
+- A vibe-coding friendly codebase (<Link path="/get_started/building-with-ai">try our MCP server!</Link>)
+- More intuitive type-safe client/server code
+- And more!

package/docs/snippets/pdk-migration/faq/aws-arch.mdx

@@ -0,0 +1,17 @@
+---
+title: AWS Arch
+---
+import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
+import Snippet from '@components/snippet.astro';
+import CreateNxWorkspaceCommand from '@components/create-nx-workspace-command.astro';
+import RunGenerator from '@components/run-generator.astro';
+import Link from '@components/link.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Drawer from '@components/drawer.astro';
+import InstallCommand from '@components/install-command.astro';
+
+[AWS Arch](https://aws.github.io/aws-pdk/developer_guides/aws-arch/index.html) provided mappings between CloudFormation resources and their associated architecture icons for CDK Graph above.
+
+Refer to the [AWS Architecture Icons page](https://aws.amazon.com/architecture/icons/) for icon related resources. [Diagrams](https://diagrams.mingrammer.com/) also provides a way to build diagrams as code.
+
+If you were using this directly, consider forking the project and taking ownership!

package/docs/snippets/pdk-migration/faq/cdk-graph.mdx

@@ -0,0 +1,29 @@
+---
+title: CDK Graph
+---
+import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
+import Snippet from '@components/snippet.astro';
+import CreateNxWorkspaceCommand from '@components/create-nx-workspace-command.astro';
+import RunGenerator from '@components/run-generator.astro';
+import Link from '@components/link.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Drawer from '@components/drawer.astro';
+import InstallCommand from '@components/install-command.astro';
+
+[CDK Graph](https://aws.github.io/aws-pdk/developer_guides/cdk-graph/index.html) builds graphs of your connected CDK resources, and provided two plugins:
+
+#### Diagram Plugin
+
+The [CDK Graph Diagram Plugin](https://aws.github.io/aws-pdk/developer_guides/cdk-graph-plugin-diagram/index.html) generates AWS architecture diagrams from your CDK infrastructure.
+
+For a similar deterministic approach a viable alternative is [CDK-Dia](https://github.com/pistazie/cdk-dia).
+
+With the advancements in Generative AI, many foundation models are capabile of creating high-quality diagrams from your CDK infrastructure. We recommend trying out the [AWS Diagram MCP Server](https://github.com/awslabs/mcp/tree/main/src/aws-diagram-mcp-server). Check out [this blog post](https://aws.amazon.com/blogs/machine-learning/build-aws-architecture-diagrams-using-amazon-q-cli-and-mcp/) for a walkthrough.
+
+#### Threat Composer Plugin
+
+The [CDK Graph Threat Composer Plugin](https://aws.github.io/aws-pdk/developer_guides/cdk-graph-plugin-threat-composer/index.html) generates a starter [Threat Composer](https://github.com/awslabs/threat-composer/) threat model from your CDK code.
+
+This plugin worked by simply filtering a [base threat model](https://github.com/aws/aws-pdk/tree/mainline/packages/cdk-graph-plugin-threat-composer/src/model-generator/base-model) containing example threats, and filtering them based on the resources your stack made use of.
+
+If you're interested in these specific example threats you can copy and filter the base threat model, or use it as context to help a foundation model generate a similar one.

package/docs/snippets/pdk-migration/faq/infrastructure-python-java.mdx

@@ -0,0 +1,19 @@
+---
+title: Infrastructure in Python or Java
+---
+import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
+import Snippet from '@components/snippet.astro';
+import CreateNxWorkspaceCommand from '@components/create-nx-workspace-command.astro';
+import RunGenerator from '@components/run-generator.astro';
+import Link from '@components/link.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Drawer from '@components/drawer.astro';
+import InstallCommand from '@components/install-command.astro';
+
+PDK supported CDK infrastructure written in Python and Java. We do not support this in the Nx Plugin for AWS at the time of writing.
+
+The recommended path forward would be to either migrate your CDK infrastructure to TypeScript, or to use our generators and migrate the common constructs package to your desired language. You can use Generative AI to accelerate these kinds of migrations, for example [Kiro CLI](https://kiro.dev/cli/). You can have an AI agent iterate on the migration until the synthesized CloudFormation templates are identical.
+
+The same applies for Type Safe API's generated infrastructure in Python or Java - you can translate the generic `rest-api.ts` construct from the common constructs package, and implement your own simple metadata generator for your target language (refer to the [APIs Modelled with OpenAPI](#apis-modelled-with-openapi) section).
+
+You can use the <Link path="/guides/python-project">`py#project` generator</Link> for a base Python project to add your CDK code to (and move over your `cdk.json` file, adding relevant targets). You can use Nx's [`@nx/gradle`](https://nx.dev/technologies/java/introduction) plugin for Java projects, or [`@jnxplus/nx-maven`](https://github.com/gridatek/jnxplus/tree/main/packages/nx-maven) for Maven.

package/docs/snippets/pdk-migration/faq/pdk-nag.mdx

@@ -0,0 +1,15 @@
+---
+title: PDK Nag
+---
+import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
+import Snippet from '@components/snippet.astro';
+import CreateNxWorkspaceCommand from '@components/create-nx-workspace-command.astro';
+import RunGenerator from '@components/run-generator.astro';
+import Link from '@components/link.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Drawer from '@components/drawer.astro';
+import InstallCommand from '@components/install-command.astro';
+
+[PDK Nag](https://aws.github.io/aws-pdk/developer_guides/pdk-nag/index.html) wraps [CDK Nag](https://github.com/cdklabs/cdk-nag), and provides a set of [rules specific to building prototypes](https://github.com/aws/aws-pdk/blob/mainline/packages/pdk-nag/src/packs/aws-prototyping-rules.ts).
+
+To migrate from PDK Nag, use CDK Nag directly. If you need the same set of rules you can create a "pack" of your own by following the [documentation here](https://github.com/cdklabs/cdk-nag/blob/main/docs/NagPack.md).

package/docs/snippets/pdk-migration/faq/pipeline.mdx

@@ -0,0 +1,15 @@
+---
+title: Pipeline
+---
+import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
+import Snippet from '@components/snippet.astro';
+import CreateNxWorkspaceCommand from '@components/create-nx-workspace-command.astro';
+import RunGenerator from '@components/run-generator.astro';
+import Link from '@components/link.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Drawer from '@components/drawer.astro';
+import InstallCommand from '@components/install-command.astro';
+
+PDK provided a [`PDKPipelineProject`](https://aws.github.io/aws-pdk/developer_guides/pipeline/index.html) which set up a CDK infrastructure project and made use of a CDK construct which wrapped some [CDK Pipelines](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines-readme.html) resources.
+
+To migrate from this, you can use the CDK Pipelines constructs directly. In practice however it is likely more straightforward to use something like GitHub actions or GitLab CI/CD, where you define [CDK Stages](https://docs.aws.amazon.com/cdk/v2/guide/stages.html) and run the deploy command for the appropiate stage directly.