@aws/nx-plugin-mcp 0.119.0 → 0.121.0

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

@@ -0,0 +1,172 @@
+---
+title: Agent Bedrock Deployment
+---
+import Link from '@components/link.astro';
+import Infrastructure from '@components/infrastructure.astro';
+
+### Infrastructure as Code
+
+If you selected `BedrockAgentCoreRuntime` for `computeType`, the relevant CDK or Terraform infrastructure is generated which you can use to deploy your Agent to [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agents-tools-runtime.html).
+
+<Infrastructure>
+<Fragment slot="cdk">
+A CDK construct is generated for your agent, named based on the `name` you chose when running the generator, or `<ProjectName>Agent` by default.
+
+You can use this CDK construct in a CDK application:
+
+```ts
+import { MyProjectAgent } from ':my-scope/common-constructs';
+
+export class ExampleStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    new MyProjectAgent(this, 'MyProjectAgent');
+  }
+}
+```
+
+:::note[CDK Construct]
+This construct uses the [`aws-cdk-lib/aws-bedrockagentcore` module](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_bedrockagentcore-readme.html).
+:::
+</Fragment>
+<Fragment slot="terraform">
+A Terraform module is generated for you, named based on the `name` you chose when running the generator, or `<ProjectName>-agent` by default.
+
+Pass the shared <Link path="/guides/runtime-config#writing-configuration">`runtime_config_appconfig`</Link> module's outputs into the agent module:
+
+```terraform
+module "my_project_agent" {
+  source = "../../common/terraform/src/app/agents/my-project-agent"
+
+  appconfig_application_id  = module.runtime_config_appconfig.application_id
+  appconfig_application_arn = module.runtime_config_appconfig.application_arn
+}
+```
+</Fragment>
+</Infrastructure>
+
+:::note[Bedrock Model Permissions]
+The generated agent construct grants permission to invoke all Bedrock foundation models and inference profiles by default (`bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream` on `arn:aws:bedrock:*:*:foundation-model/*` and `arn:aws:bedrock:*:*:inference-profile/*`).
+
+You may wish to scope this down to the specific model(s) your agent uses. You can find the default model used by Strands agents in the [Strands documentation](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/model-providers/amazon-bedrock/#default-model); see the [Strands model providers guide](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/model-providers/) for configuring a different model.
+:::
+
+:::caution[Docker Required]
+[Docker](https://www.docker.com/) is required to build and deploy your Agent. Make sure you have installed and launched Docker to avoid errors such as:
+
+```
+ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.
+```
+:::
+
+### Authentication
+
+The generator provides an `auth` option to configure authentication for your Agent. You can choose between `IAM` (default) or `Cognito` authentication when generating your agent.
+
+#### IAM
+
+By default, your Agent will be secured using IAM authentication, simply deploy it without any arguments:
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts {5}
+import { MyProjectAgent } from ':my-scope/common-constructs';
+
+export class ExampleStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    new MyProjectAgent(this, 'MyProjectAgent');
+  }
+}
+```
+
+You can grant access to invoke your agent on Bedrock AgentCore Runtime using the `grantInvokeAccess` method, for example:
+
+```ts {8}
+import { MyProjectAgent } from ':my-scope/common-constructs';
+
+export class ExampleStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    const agent = new MyProjectAgent(this, 'MyProjectAgent');
+    const lambdaFunction = new Function(this, ...);
+
+    agent.grantInvokeAccess(lambdaFunction);
+  }
+}
+```
+</Fragment>
+<Fragment slot="terraform">
+```terraform {5-6}
+# Agent
+module "my_project_agent" {
+  # Relative path to the generated module in the common/terraform project
+  source = "../../common/terraform/src/app/agents/my-project-agent"
+
+  appconfig_application_id  = module.runtime_config_appconfig.application_id
+  appconfig_application_arn = module.runtime_config_appconfig.application_arn
+}
+```
+
+To grant access to invoke your agent, you will need to add a policy such as the following, referencing the `module.my_project_agent.agent_core_runtime_arn` output:
+
+```terraform
+{
+  Effect = "Allow"
+  Action = [
+    "bedrock-agentcore:InvokeAgentRuntime"
+  ]
+  Resource = [
+    module.my_project_agent.agent_core_runtime_arn,
+    "${module.my_project_agent.agent_core_runtime_arn}/*"
+  ]
+}
+```
+</Fragment>
+</Infrastructure>
+
+#### Cognito Authentication
+
+When you select `Cognito` authentication, the generator configures the agent to use Cognito for authentication.
+
+<Infrastructure>
+<Fragment slot="cdk">
+The generated construct accepts an `identity` prop which configures Cognito authentication:
+
+```ts {8}
+import { MyProjectAgent, UserIdentity } from ':my-scope/common-constructs';
+
+export class ExampleStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    const identity = new UserIdentity(this, 'Identity');
+
+    new MyProjectAgent(this, 'MyProjectAgent', {
+      identity,
+    });
+  }
+}
+```
+
+The `UserIdentity` construct can be generated using the <Link path="/guides/react-website-auth">`ts#react-website#auth` generator</Link>, or you can create your own CDK `UserPool` and `UserPoolClient`.
+</Fragment>
+<Fragment slot="terraform">
+The generated module accepts `user_pool_id` and `user_pool_client_ids` variables for Cognito authentication:
+
+```terraform {8-9}
+module "user_identity" {
+  source = "../../common/terraform/src/core/user-identity"
+}
+
+module "my_project_agent" {
+  source = "../../common/terraform/src/app/agents/my-project-agent"
+
+  appconfig_application_id  = module.runtime_config_appconfig.application_id
+  appconfig_application_arn = module.runtime_config_appconfig.application_arn
+
+  user_pool_id         = module.user_identity.user_pool_id
+  user_pool_client_ids = [module.user_identity.user_pool_client_id]
+}
+```
+</Fragment>
+</Infrastructure>
+
+:::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 agent directly. Note that the connection generator will only support `IAM` or `Cognito` authentication.
+:::

package/docs/snippets/agent/runtime-arn.mdx

@@ -0,0 +1,64 @@
+---
+title: Bedrock AgentCore Runtime ARN
+---
+import Link from '@components/link.astro';
+import Infrastructure from '@components/infrastructure.astro';
+
+To invoke your Agent deployed to Bedrock AgentCore Runtime, you can send a POST request to the Bedrock AgentCore Runtime dataplane endpoint with your URL-encoded runtime ARN.
+
+You can obtain the runtime ARN from your infrastructure as follows:
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts {9}
+import { CfnOutput } from 'aws-cdk-lib';
+import { MyProjectAgent } from ':my-scope/common-constructs';
+
+export class ExampleStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    const agent = new MyProjectAgent(this, 'MyProjectAgent');
+
+    new CfnOutput(this, 'AgentArn', {
+      value: agent.agentCoreRuntime.agentRuntimeArn,
+    });
+  }
+}
+```
+</Fragment>
+<Fragment slot="terraform">
+```terraform {5-6, 10}
+# Agent
+module "my_project_agent" {
+  # Relative path to the generated module in the common/terraform project
+  source = "../../common/terraform/src/app/agents/my-project-agent"
+
+  appconfig_application_id  = module.runtime_config_appconfig.application_id
+  appconfig_application_arn = module.runtime_config_appconfig.application_arn
+}
+
+output "agent_arn" {
+  value = module.my_project_agent.agent_core_runtime_arn
+}
+```
+</Fragment>
+</Infrastructure>
+
+The ARN will have the following format: `arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>`.
+
+You can then URL-encode the ARN by replacing `:` with `%3A` and `/` with `%2F`.
+
+:::tip[Browser Console]
+This is straightforward in a browser console or Node REPL using the built in `encodeURIComponent` method:
+
+```js
+encodeURIComponent('arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>')
+```
+:::
+
+The Bedrock AgentCore Runtime dataplane URL for invoking the agent is as follows:
+
+```
+https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations
+```
+
+The exact way to invoke this URL depends upon the authentication method used.

package/docs/snippets/api/api-architecture.mdx

@@ -0,0 +1,93 @@
+---
+title: API Architecture
+---
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+The deployed application has the following architecture:
+
+<Tabs syncKey="http-rest">
+<TabItem label="REST API" _filter={{ computeType: 'ServerlessApiGatewayRestApi' }}>
+```d2 inline=true
+direction: right
+
+client: Client {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/client.svg
+}
+
+waf: WAF {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/waf.svg
+}
+
+apigw: API Gateway\n(REST API) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/api-gateway.svg
+}
+
+lambda: Lambda {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/lambda.svg
+}
+
+cw: CloudWatch\n(Logs, Metrics) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/cloudwatch.svg
+  near: top-right
+}
+
+xray: X-Ray\n(Traces) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/xray.svg
+  near: bottom-right
+}
+
+client -> waf
+waf -> apigw
+apigw -> lambda
+lambda -> cw
+lambda -> xray
+```
+
+REST APIs include an [AWS WAFv2](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) Web ACL in front of the API Gateway stage with the AWS managed default ruleset enabled.
+</TabItem>
+<TabItem label="HTTP API" _filter={{ computeType: 'ServerlessApiGatewayHttpApi' }}>
+```d2 inline=true
+direction: right
+
+client: Client {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/client.svg
+}
+
+apigw: API Gateway\n(HTTP API) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/api-gateway.svg
+}
+
+lambda: Lambda {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/lambda.svg
+}
+
+cw: CloudWatch\n(Logs, Metrics) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/cloudwatch.svg
+  near: top-right
+}
+
+xray: X-Ray\n(Traces) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/xray.svg
+  near: bottom-right
+}
+
+client -> apigw
+apigw -> lambda
+lambda -> cw
+lambda -> xray
+```
+
+HTTP APIs do not support WAF directly — if you need WAF protection, choose REST API instead or front the HTTP API with a CloudFront distribution.
+</TabItem>
+</Tabs>

package/docs/snippets/api/api-choice-note.mdx

@@ -0,0 +1,6 @@
+---
+title: Choose between REST and HTTP
+---
+:::note[API Type Choice]
+You can choose between either a [REST API](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-rest-api.html) or [HTTP API](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html) to deploy your API, please refer to the [API Gateway Developer Guide](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html) to help you decide.
+:::

package/docs/snippets/api/cors-configuration-cdk-note.mdx

@@ -0,0 +1,25 @@
+---
+title: CORS configuration CDK
+---
+import Link from '@components/link.astro';
+
+:::note[CDK CORS Configuration]
+If your solution includes a website you can configure its CloudFront distribution as the only permitted CORS origin in the API gateway / API AWS Lambda integrations for HTTP / REST APIs.
+You can call the API `restrictCorsTo` method with website constructs, CloudFront distributions, origin strings, or a mix of them.
+
+```ts
+import { MyApi, MyWebsite } from ':my-scope/common-constructs';
+
+export class ExampleStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    const api = new MyApi(this, 'MyApi', {
+      integrations: MyApi.defaultIntegrations(this).build(),
+    });
+    const website = new MyWebsite(this, 'MyWebsite');
+    api.restrictCorsTo(website, 'http://localhost:4200');
+  }
+}
+```
+
+The `MyWebsite` construct can be generated using the <Link path="/guides/react-website">`ts#react-website` generator</Link>
+:::

package/docs/snippets/api/cors-configuration-terraform-note.mdx

@@ -0,0 +1,28 @@
+---
+title: CORS configuration Terraform
+---
+import Link from '@components/link.astro';
+
+:::note[Terraform CORS Configuration]
+If your solution includes a Terraform website module then you can use its CloudFront domain name to restrict CORS.
+Given a CloudFront domain name `<domain_name>`, within the Terraform module for deploying your API add
+- a `cors_allow_origins` property, set to `["http://localhost:4200", "http://localhost:4300", "https://<domain name>"]`, for HTTP APIs. This restricts the API gateway CORS to this distribution and local host.
+- an `ALLOWED_ORIGINS` environment variable, set to `"https://<domain_name>"`, for REST APIs. This sets the CloudFront distribution as the only permitted CORS origin (other than local host) in AWS Lambda integrations. Note that this restriction is not applied to preflight OPTIONS - please +1 [this GitHub issue](https://github.com/awslabs/nx-plugin-for-aws/issues/377) to help prioritise addressing this.
+
+```hcl {4,6,9}
+module "my_api" {
+  source = "../../common/terraform/src/app/apis/my-api"
+
+  asset_bucket_name = module.asset_bucket.bucket_name
+
+  cors_allow_origins = ["http://localhost:4200", "http://localhost:4300", "https://<domain name>"] // Only required for HTTP API
+
+  env = {
+    ALLOWED_ORIGINS = "https://<domain name>" // Only required for REST API
+    ENVIRONMENT = var.environment
+    LOG_LEVEL   = "INFO"
+  }
+}
+```
+The `MyWebsite` construct can be generated using the <Link path="/guides/react-website">`ts#react-website` generator</Link>
+:::

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

@@ -0,0 +1,38 @@
+---
+title: API Shared Constructs
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Infrastructure from '@components/infrastructure.astro';
+
+For deploying your API, the following files are generated:
+
+<Infrastructure>
+<Fragment slot="cdk">
+<FileTree>
+  - packages/common/constructs/src
+    - app
+      - apis
+        - \<project-name>.ts CDK construct for deploying your API
+    - core
+      - api
+        - http-api.ts CDK construct for deploying an HTTP API (if you selected to deploy an HTTP API)
+        - rest-api.ts CDK construct for deploying a REST API (if you selected to deploy a REST API)
+        - utils.ts Utilities for the API constructs
+</FileTree>
+</Fragment>
+<Fragment slot="terraform">
+<FileTree>
+  - packages/common/terraform/src
+    - app
+      - apis
+        - \<project-name>
+          - \<project-name>.tf Module for deploying your API
+    - core
+      - api
+        - http-api
+          - http-api.tf Module for deploying an HTTP API (if you selected to deploy an HTTP API)
+        - rest-api
+          - rest-api.tf Module for deploying a REST API (if you selected to deploy a REST API)
+</FileTree>
+</Fragment>
+</Infrastructure>