@aws/nx-plugin 1.0.0-rc.5 → 1.0.0-rc.51

package/src/utils/agent-core-constructs/files/cdk/core/agentcore-gateway/agentcore-gateway.ts.template

@@ -0,0 +1,497 @@
+import * as cdk from 'aws-cdk-lib';
+import * as agentcore from 'aws-cdk-lib/aws-bedrockagentcore';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import * as kms from 'aws-cdk-lib/aws-kms';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+import * as logs from 'aws-cdk-lib/aws-logs';
+import * as triggers from 'aws-cdk-lib/triggers';
+import * as wafv2 from 'aws-cdk-lib/aws-wafv2';
+import { Construct } from 'constructs';
+import ejs from 'ejs';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as url from 'node:url';
+
+/**
+ * Props for the AgentCoreGateway construct.
+ */
+export interface AgentCoreGatewayProps {
+  /**
+   * Directory of Cedar policy files (`.cedar`, nested folders supported).
+   * When set, a `PolicyEngine` running in `ENFORCE` mode is attached to the
+   * gateway, with one `Policy` per file. Files are EJS templates rendered at
+   * synth time with `gatewayArn` and `accountId` in scope.
+   */
+  readonly cedarPolicyPath?: string;
+  /**
+   * Additional variables available to the Cedar policy EJS templates.
+   */
+  readonly cedarPolicyVariables?: Record<string, string>;
+  /**
+   * Associate a regional WAFv2 web ACL (default AWS managed rule groups) with
+   * the gateway to inspect inbound requests.
+   *
+   * @default true
+   */
+  readonly enableWaf?: boolean;
+  /**
+   * Inbound authorizer for the gateway. Defaults to IAM (SigV4) authentication;
+   * pass `GatewayAuthorizer.usingCognito(...)` or `usingCustomJwt(...)` to
+   * authenticate callers with JWT bearer tokens instead.
+   *
+   * @default GatewayAuthorizer.usingAwsIam()
+   */
+  readonly authorizer?: agentcore.IGatewayAuthorizerConfig;
+}
+
+/**
+ * AgentCore Gateway wired for MCP protocol, exposing attached MCP servers'
+ * tools under `<targetName>___<toolName>` names. Inbound auth defaults to IAM
+ * (SigV4); pass an `authorizer` to use Cognito/JWT instead.
+ */
+export class AgentCoreGateway extends Construct implements iam.IGrantable {
+  public readonly gateway: agentcore.Gateway;
+  public readonly policyEngine?: agentcore.CfnPolicyEngine;
+  /** The WAFv2 web ACL associated with the gateway, if WAF is enabled. */
+  public readonly webAcl?: wafv2.CfnWebACL;
+  private readonly policies: agentcore.CfnPolicy[] = [];
+  private targetReadinessProbe?: triggers.TriggerFunction;
+  private readonly targetRuntimeArns: string[] = [];
+
+  constructor(scope: Construct, id: string, props?: AgentCoreGatewayProps) {
+    super(scope, id);
+
+    this.gateway = new agentcore.Gateway(this, 'Gateway', {
+      // Cap at 39 chars so the 11-char service suffix keeps the gateway id
+      // within its 50-char limit.
+      gatewayName: cdk.Names.uniqueResourceName(this, { maxLength: 39 }),
+      protocolConfiguration: new agentcore.McpProtocolConfiguration({
+        searchType: agentcore.McpGatewaySearchType.SEMANTIC,
+        supportedVersions: [agentcore.MCPProtocolVersion.MCP_2025_03_26],
+      }),
+      authorizerConfiguration:
+        props?.authorizer ?? agentcore.GatewayAuthorizer.usingAwsIam(),
+    });
+
+    if (props?.cedarPolicyPath) {
+      this.policyEngine = new agentcore.CfnPolicyEngine(this, 'PolicyEngine', {
+        name: cdk.Names.uniqueResourceName(this, { maxLength: 48 }),
+        description: `Cedar policy engine for ${id}`,
+      });
+
+      // The stable Gateway L2 does not yet expose policy engine
+      // configuration, so attach it via the underlying CloudFormation
+      // resource.
+      const cfnGateway = this.gateway.node.defaultChild as agentcore.CfnGateway;
+      cfnGateway.policyEngineConfiguration = {
+        arn: this.policyEngine.attrPolicyEngineArn,
+        mode: 'ENFORCE',
+      };
+
+      // Permissions the gateway role needs to evaluate policies, including
+      // CheckAuthorizePermissions, which the CloudFormation handler's
+      // readiness probe requires during gateway creation. Authorization
+      // actions are evaluated against both the policy engine ARN and the
+      // gateway's own ARN (which cannot be referenced here without a circular
+      // dependency, so it is scoped to this account and region's gateways).
+      // The gateway must depend on the policy update — access is validated at
+      // creation.
+      const policyGrant = this.gateway.role.addToPrincipalPolicy(
+        new iam.PolicyStatement({
+          actions: [
+            'bedrock-agentcore:GetPolicyEngine',
+            'bedrock-agentcore:AuthorizeAction',
+            'bedrock-agentcore:PartiallyAuthorizeActions',
+            'bedrock-agentcore:CheckAuthorizePermissions',
+          ],
+          resources: [
+            this.policyEngine.attrPolicyEngineArn,
+            cdk.Stack.of(this).formatArn({
+              service: 'bedrock-agentcore',
+              resource: 'gateway',
+              resourceName: '*',
+            }),
+          ],
+        }),
+      );
+      if (policyGrant.policyDependable) {
+        cfnGateway.node.addDependency(policyGrant.policyDependable);
+      }
+
+      const policiesDir = props.cedarPolicyPath;
+      if (fs.existsSync(policiesDir)) {
+        for (const file of fs
+          .readdirSync(policiesDir, { recursive: true, encoding: 'utf-8' })
+          .filter((f) => f.endsWith('.cedar'))) {
+          const raw = fs.readFileSync(path.join(policiesDir, file), 'utf-8');
+          const statement = cdk.Lazy.string({
+            produce: () =>
+              ejs.render(raw, {
+                gatewayArn: cdk.Token.asString(this.gateway.gatewayArn),
+                accountId: cdk.Token.asString(cdk.Stack.of(this).account),
+                ...props.cedarPolicyVariables,
+              }),
+          });
+          const policyId = `Policy-${file.replace(/\.cedar$/, '').replace(/[\\/]/g, '-')}`;
+          const policy = new agentcore.CfnPolicy(this, policyId, {
+            name: policyId,
+            policyEngineId: this.policyEngine.attrPolicyEngineId,
+            definition: { cedar: { statement } },
+            description: `Policy loaded from ${file}`,
+            // The Cedar analyzer rejects legitimate policies as findings
+            // (e.g. a forbid disabling one tool for every caller is "Overly
+            // Restrictive"), so deploy regardless and rely on the engine's
+            // ENFORCE mode.
+            validationMode: 'IGNORE_ALL_FINDINGS',
+          });
+          // Policy names are unique account-wide, so derive the name from
+          // the construct path to avoid collisions with other gateways.
+          policy.name = cdk.Names.uniqueResourceName(policy, {
+            maxLength: 48,
+          });
+          this.policies.push(policy);
+        }
+      }
+    }
+
+    if (props?.enableWaf ?? true) {
+      this.webAcl = this.createWebAcl();
+    }
+  }
+
+  /**
+   * Create a regional WAFv2 web ACL with the default AWS managed rule groups,
+   * associate it with the gateway, and log requests to CloudWatch.
+   */
+  private createWebAcl(): wafv2.CfnWebACL {
+    const metricPrefix = cdk.Names.uniqueResourceName(this, { maxLength: 40 });
+
+    const webAcl = new wafv2.CfnWebACL(this, 'WebAcl', {
+      defaultAction: { allow: {} },
+      // AgentCore Gateway requires a REGIONAL web ACL; CloudFront (global) is
+      // not supported.
+      scope: 'REGIONAL',
+      visibilityConfig: {
+        cloudWatchMetricsEnabled: true,
+        metricName: `${metricPrefix}WebAcl`,
+        sampledRequestsEnabled: true,
+      },
+      rules: [
+        {
+          name: 'CRSRule',
+          priority: 0,
+          statement: {
+            managedRuleGroupStatement: {
+              name: 'AWSManagedRulesCommonRuleSet',
+              vendorName: 'AWS',
+              // Count instead of Block: the CRS 8 KB body limit is too
+              // restrictive for typical MCP tool payloads.
+              ruleActionOverrides: [
+                {
+                  name: 'SizeRestrictions_BODY',
+                  actionToUse: { count: {} },
+                },
+              ],
+            },
+          },
+          visibilityConfig: {
+            cloudWatchMetricsEnabled: true,
+            metricName: `${metricPrefix}WebAcl-CRS`,
+            sampledRequestsEnabled: true,
+          },
+          overrideAction: {
+            none: {},
+          },
+        },
+        {
+          name: 'KnownBadInputsRule',
+          priority: 1,
+          statement: {
+            managedRuleGroupStatement: {
+              name: 'AWSManagedRulesKnownBadInputsRuleSet',
+              vendorName: 'AWS',
+            },
+          },
+          visibilityConfig: {
+            cloudWatchMetricsEnabled: true,
+            metricName: `${metricPrefix}WebAcl-KnownBadInputs`,
+            sampledRequestsEnabled: true,
+          },
+          overrideAction: {
+            none: {},
+          },
+        },
+      ],
+    });
+
+    new wafv2.CfnWebACLAssociation(this, 'WebAclAssociation', {
+      resourceArn: this.gateway.gatewayArn,
+      webAclArn: webAcl.attrArn,
+    });
+
+    // WAFv2 logging destination requires the `aws-waf-logs-` name prefix.
+    const logsKey = new kms.Key(this, 'WebAclLogsKey', {
+      enableKeyRotation: true,
+    });
+    logsKey.grantEncryptDecrypt(
+      new iam.ServicePrincipal(
+        `logs.${cdk.Stack.of(this).region}.amazonaws.com`,
+      ),
+    );
+    const wafLogGroup = new logs.LogGroup(this, 'WebAclLogs', {
+      logGroupName: `aws-waf-logs-${metricPrefix}-${this.node.addr.slice(-8)}`,
+      retention: logs.RetentionDays.ONE_YEAR,
+      encryptionKey: logsKey,
+    });
+
+    new wafv2.CfnLoggingConfiguration(this, 'WebAclLoggingConfig', {
+      resourceArn: webAcl.attrArn,
+      logDestinationConfigs: [wafLogGroup.logGroupArn],
+    });
+
+    return webAcl;
+  }
+
+  /**
+   * The principal to grant permissions to.
+   */
+  public get grantPrincipal(): iam.IPrincipal {
+    return this.gateway.role.grantPrincipal;
+  }
+
+  /**
+   * Grants an IAM principal permission to invoke this gateway.
+   */
+  public grantInvokeAccess(grantee: iam.IGrantable) {
+    this.gateway.grantInvoke(grantee);
+  }
+
+  /**
+   * Add an MCP server construct as a target of this Gateway.
+   *
+   * The target name defaults to the MCP server construct's `mcpServerName`
+   * (its project's class name in kebab-case, e.g. `TsMcp` -> `ts-mcp`),
+   * which is stable across stacks and unique across projects in the
+   * workspace. It prefixes Cedar action names
+   * (`AgentCore::Action::"<targetName>___<toolName>"`) and the gateway's
+   * tool names (`<targetName>___<toolName>`), so renaming it later is a
+   * breaking change for consumers.
+   */
+  public addMcpServer(
+    server: Construct & {
+      readonly agentCoreRuntime: agentcore.Runtime;
+      readonly mcpServerName: string;
+    },
+    props?: {
+      gatewayTargetName?: string;
+    },
+  ): agentcore.CfnGatewayTarget {
+    return this.addMcpServerTarget({
+      gatewayTargetName: props?.gatewayTargetName ?? server.mcpServerName,
+      mcpServerRuntimeArn: server.agentCoreRuntime.agentRuntimeArn,
+    });
+  }
+
+  /**
+   * Register an MCP server runtime ARN as a Gateway target. Prefer
+   * {@link addMcpServer} when the construct is in scope.
+   */
+  public addMcpServerTarget(props: {
+    gatewayTargetName: string;
+    mcpServerRuntimeArn: string;
+  }): agentcore.CfnGatewayTarget {
+    const region = cdk.Stack.of(this).region;
+    // The endpoint must URL-encode the runtime ARN (':' -> '%3A', '/' -> '%2F').
+    // The ARN is a CDK token, so encode at deploy time via Fn.join/Fn.split.
+    const arn = props.mcpServerRuntimeArn;
+    const encodedArn = cdk.Fn.join(
+      '%2F',
+      cdk.Fn.split('/', cdk.Fn.join('%3A', cdk.Fn.split(':', arn))),
+    );
+    const endpoint = `https://bedrock-agentcore.${region}.amazonaws.com/runtimes/${encodedArn}/invocations?qualifier=DEFAULT`;
+    const target = this.addTarget(props.gatewayTargetName, endpoint);
+
+    // Grant the gateway role invoke access to the target runtime before the
+    // target is created — AgentCore probes the target during creation, which
+    // stalls if the permission is not yet in place.
+    const grant = this.gateway.role.addToPrincipalPolicy(
+      new iam.PolicyStatement({
+        actions: [
+          'bedrock-agentcore:InvokeAgentRuntime',
+          'bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream',
+        ],
+        resources: [
+          props.mcpServerRuntimeArn,
+          `${props.mcpServerRuntimeArn}/*`,
+        ],
+      }),
+    );
+    if (grant.policyDependable) {
+      target.node.addDependency(grant.policyDependable);
+    }
+
+    // Create the target only after the readiness probe has confirmed the
+    // runtime serves MCP.
+    this.targetRuntimeArns.push(props.mcpServerRuntimeArn);
+    const probe = this.getOrCreateTargetReadinessProbe();
+    const probeGrant = probe.grantPrincipal.addToPrincipalPolicy(
+      new iam.PolicyStatement({
+        actions: ['bedrock-agentcore:InvokeAgentRuntime'],
+        resources: [
+          props.mcpServerRuntimeArn,
+          `${props.mcpServerRuntimeArn}/*`,
+        ],
+      }),
+    );
+    if (probeGrant.policyDependable) {
+      probe.trigger.node.addDependency(probeGrant.policyDependable);
+    }
+    target.node.addDependency(probe.trigger);
+
+    return target;
+  }
+
+  /**
+   * Add another Gateway as a target of this Gateway, exposing its tools
+   * under `<targetName>___<innerTargetName>___<toolName>` names.
+   *
+   * The target name defaults to the gateway construct's `gatewayName`
+   * (its project's class name in kebab-case, e.g. `MyGateway` ->
+   * `my-gateway`). It prefixes Cedar action names and the gateway's tool
+   * names, so renaming it later is a breaking change for consumers.
+   *
+   * Both gateways evaluate their own Cedar policies: this gateway
+   * authorizes the prefixed action, then the target gateway authorizes the
+   * inner action for this gateway's role.
+   */
+  public addGateway(
+    gateway: Construct & {
+      readonly gateway: agentcore.Gateway;
+      readonly gatewayName: string;
+    },
+    props?: {
+      gatewayTargetName?: string;
+    },
+  ): agentcore.CfnGatewayTarget {
+    const target = this.addGatewayTarget({
+      gatewayTargetName: props?.gatewayTargetName ?? gateway.gatewayName,
+      // The Gateway L2 only populates gatewayUrl when created from its own
+      // props; fall back to the CloudFormation attribute otherwise.
+      gatewayUrl:
+        gateway.gateway.gatewayUrl ??
+        (gateway.gateway.node.defaultChild as agentcore.CfnGateway)
+          .attrGatewayUrl,
+      gatewayArn: gateway.gateway.gatewayArn,
+    });
+    // AgentCore fetches the target gateway's tools during target creation,
+    // so the target gateway and all of its own targets must exist first.
+    // Construct dependencies resolve at synth time, covering targets added
+    // to the target gateway after this call.
+    target.node.addDependency(gateway);
+    return target;
+  }
+
+  /**
+   * Register another Gateway's MCP endpoint as a target of this Gateway.
+   * Prefer {@link addGateway} when the construct is in scope — it also
+   * orders this gateway's target after the target gateway's own targets,
+   * so its tools are registered before they are fetched.
+   */
+  public addGatewayTarget(props: {
+    gatewayTargetName: string;
+    gatewayUrl: string;
+    gatewayArn: string;
+  }): agentcore.CfnGatewayTarget {
+    const target = this.addTarget(props.gatewayTargetName, props.gatewayUrl);
+
+    // Grant the gateway role invoke access to the target gateway before the
+    // target is created — AgentCore fetches the target's tools during
+    // creation, which fails if the permission is not yet in place.
+    const grant = this.gateway.role.addToPrincipalPolicy(
+      new iam.PolicyStatement({
+        actions: ['bedrock-agentcore:InvokeGateway'],
+        resources: [props.gatewayArn],
+      }),
+    );
+    if (grant.policyDependable) {
+      target.node.addDependency(grant.policyDependable);
+    }
+
+    return target;
+  }
+
+  /**
+   * Create a Gateway target for an MCP endpoint, with outbound calls signed
+   * using this gateway's own execution role.
+   */
+  private addTarget(
+    gatewayTargetName: string,
+    endpoint: string,
+  ): agentcore.CfnGatewayTarget {
+    // The construct id is derived from the target name so the two change
+    // together — target names are unique per gateway, and replacing a target
+    // under an unchanged name fails with AlreadyExists.
+    const target = new agentcore.CfnGatewayTarget(
+      this,
+      `Target-${gatewayTargetName}`,
+      {
+        gatewayIdentifier: this.gateway.gatewayId,
+        name: gatewayTargetName,
+        targetConfiguration: {
+          mcp: {
+            mcpServer: {
+              endpoint,
+            },
+          },
+        },
+        credentialProviderConfigurations: [
+          {
+            credentialProviderType: 'GATEWAY_IAM_ROLE',
+            credentialProvider: {
+              iamCredentialProvider: {
+                service: 'bedrock-agentcore',
+              },
+            },
+          },
+        ],
+      },
+    );
+
+    // Policies referencing this target's actions (e.g.
+    // AgentCore::Action::"<targetName>___<tool>") only validate once the
+    // target has registered them, so create policies after targets.
+    for (const policy of this.policies) {
+      policy.node.addDependency(target);
+    }
+
+    return target;
+  }
+
+  /**
+   * AgentCore fetches each target's tools during target creation, which can
+   * race the MCP runtime's first cold start on a fresh deploy and fail the
+   * target. This trigger probes each runtime until it serves MCP, and targets
+   * are created after it succeeds.
+   */
+  private getOrCreateTargetReadinessProbe(): triggers.TriggerFunction {
+    this.targetReadinessProbe ??= new triggers.TriggerFunction(
+      this,
+      'TargetReadinessProbe',
+      {
+        runtime: lambda.Runtime.NODEJS_22_X,
+        handler: 'index.handler',
+        timeout: cdk.Duration.seconds(210),
+        code: lambda.Code.fromAsset(
+          url.fileURLToPath(new URL('./readiness-probe', <% if (esm) { %>import.meta.url<% } else { %>require('url').pathToFileURL(__filename).href<% } %>)),
+        ),
+        environment: {
+          RUNTIME_ARNS: cdk.Lazy.string({
+            produce: () => this.targetRuntimeArns.join(','),
+          }),
+        },
+      },
+    );
+    return this.targetReadinessProbe;
+  }
+}
+

package/src/utils/agent-core-constructs/files/cdk/core/agentcore-gateway/readiness-probe/index.js.template

@@ -0,0 +1,55 @@
+/**
+ * Readiness probe for AgentCore Gateway MCP targets.
+ *
+ * AgentCore fetches each target's tools during target creation, which can
+ * race the MCP runtime's first cold start on a fresh deploy. This handler
+ * invokes each runtime with an MCP initialize request — the invocation
+ * blocks through the cold start — retrying for up to 3 minutes.
+ */
+const {
+  BedrockAgentCoreClient,
+  InvokeAgentRuntimeCommand,
+} = require('@aws-sdk/client-bedrock-agentcore');
+
+const client = new BedrockAgentCoreClient();
+
+const DEADLINE_MS = 3 * 60 * 1000;
+const RETRY_INTERVAL_MS = 5 * 1000;
+
+const INITIALIZE_REQUEST = JSON.stringify({
+  jsonrpc: '2.0',
+  id: 1,
+  method: 'initialize',
+  params: {
+    protocolVersion: '2025-03-26',
+    capabilities: {},
+    clientInfo: { name: 'readiness-probe', version: '1.0' },
+  },
+});
+
+const probe = async (agentRuntimeArn) => {
+  const deadline = Date.now() + DEADLINE_MS;
+  for (;;) {
+    try {
+      return await client.send(
+        new InvokeAgentRuntimeCommand({
+          agentRuntimeArn,
+          runtimeSessionId: 'readiness-probe-' + crypto.randomUUID(),
+          contentType: 'application/json',
+          accept: 'application/json, text/event-stream',
+          payload: Buffer.from(INITIALIZE_REQUEST),
+        }),
+      );
+    } catch (e) {
+      if (Date.now() >= deadline) {
+        throw e;
+      }
+      await new Promise((resolve) => setTimeout(resolve, RETRY_INTERVAL_MS));
+    }
+  }
+};
+
+exports.handler = async () => {
+  const arns = (process.env.RUNTIME_ARNS ?? '').split(',').filter(Boolean);
+  await Promise.all(arns.map(probe));
+};

package/src/utils/agent-core-constructs/files/terraform/app/agent-core/__nameKebabCase__/__nameKebabCase__.tf.template

@@ -20,6 +20,25 @@ variable "tags" {
   default     = {}
 }
 
+# VPC Configuration (optional)
+variable "enable_vpc" {
+  description = "Run the agent core runtime inside a VPC. Set alongside vpc_id/subnet_ids."
+  type        = bool
+  default     = false
+}
+
+variable "vpc_id" {
+  description = "VPC ID to run the agent core runtime in. Required when enable_vpc is true."
+  type        = string
+  default     = null
+}
+
+variable "subnet_ids" {
+  description = "Subnet IDs to run the agent core runtime in. Required when enable_vpc is true."
+  type        = list(string)
+  default     = null
+}
+
 variable "appconfig_application_id" {
   description = "ID of the shared runtime-config AppConfig application (from `core/runtime-config/appconfig.application_id`). The agent reads its runtime configuration from this application."
   type        = string
@@ -53,6 +72,9 @@ module "agent_core_runtime" {
   agent_runtime_name = "<%= nameClassName %>"
   docker_image_tag = "<%= dockerImageTag %>"
   server_protocol = "<%= serverProtocol.toUpperCase() %>"
+  enable_vpc = var.enable_vpc
+  vpc_id = var.vpc_id
+  subnet_ids = var.subnet_ids
 <%_ if (auth === 'cognito') { _%>
   authorizer_configuration = {
     custom_jwt_authorizer = {
@@ -111,7 +133,17 @@ output "agent_core_runtime_arn" {
   value       = module.agent_core_runtime.agent_core_runtime_arn
 }
 
+output "invocation_url" {
+  description = "HTTPS invocation URL of the runtime<% if (serverProtocol === 'mcp') { %> (the MCP endpoint, e.g. for use as a Gateway target endpoint)<% } else if (serverProtocol === 'a2a') { %> (the A2A endpoint)<% } %>"
+  value       = module.agent_core_runtime.invocation_url
+}
+
 output "appconfig_application_id" {
   description = "AppConfig Application ID for runtime config (passthrough of the shared `appconfig_application_id` input)."
   value       = var.appconfig_application_id
 }
+
+output "security_group_id" {
+  description = "Security group ID of the agent core runtime, for use in ingress rules on resources it must reach (e.g. a database). Null unless enable_vpc is true."
+  value       = module.agent_core_runtime.security_group_id
+}