@aws/nx-plugin 1.0.0-rc.3 → 1.0.0-rc.30

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

@@ -0,0 +1,449 @@
+terraform {
+  required_version = ">= 1.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "<%- awsProviderVersion %>"
+    }
+<%_ if (cedarPolicy) { _%>
+    external = {
+      source  = "hashicorp/external"
+      version = "<%- externalProviderVersion %>"
+    }
+<%_ } _%>
+    random = {
+      source  = "hashicorp/random"
+      version = "<%- randomProviderVersion %>"
+    }
+  }
+}
+
+variable "additional_iam_policy_statements" {
+  description = "Additional IAM policy statements to attach to the gateway service role. Connection generators (e.g. agentcore-gateway#mcp-connection) append `InvokeAgentRuntime*` entries here."
+  type = list(object({
+    Effect   = string
+    Action   = list(string)
+    Resource = list(string)
+  }))
+  default = []
+}
+
+variable "tool_dependencies" {
+  description = "Target ids whose tools must be queryable before `gateway_url` is consumable. Set this to the gateway's own target ids (e.g. from agentcore-gateway#mcp-connection) when another gateway aggregates this one: the readiness probe waits until this gateway serves those tools, since a parent gateway fetches them at target creation."
+  type        = list(string)
+  default     = []
+}
+
+variable "enable_waf" {
+  description = "Associate a regional WAFv2 web ACL (default AWS managed rule groups) with the gateway to inspect inbound requests."
+  type        = bool
+  default     = true
+}
+<%_ if (cedarPolicy) { _%>
+
+variable "policy_dependencies" {
+  description = "Values the Cedar policies must wait for, e.g. gateway target ids. Policies referencing a target's actions only validate once the target has registered them."
+  type        = list(string)
+  default     = []
+}
+<%_ } _%>
+
+data "aws_caller_identity" "current" {}
+data "aws_region" "current" {}
+
+locals {
+  aws_account_id = data.aws_caller_identity.current.account_id
+  aws_region     = data.aws_region.current.id
+<%_ if (cedarPolicy) { _%>
+  policies_dir   = "${path.module}/../../../../../../../<%- projectDirectory %>/policies"
+<%_ } _%>
+}
+
+resource "random_id" "unique_suffix" {
+  byte_length = 4
+}
+
+# IAM role for the gateway service
+resource "aws_iam_role" "gateway_role" {
+  name = "<%- nameClassName %>-GatewayRole-${random_id.unique_suffix.hex}"
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Sid    = "AgentCoreGatewayAssumeRolePolicy"
+        Effect = "Allow"
+        Principal = {
+          Service = "bedrock-agentcore.amazonaws.com"
+        }
+        Action = "sts:AssumeRole"
+        Condition = {
+          StringEquals = {
+            "aws:SourceAccount" = local.aws_account_id
+          }
+          ArnLike = {
+            "aws:SourceArn" = "arn:aws:bedrock-agentcore:${local.aws_region}:${local.aws_account_id}:*"
+          }
+        }
+      }
+    ]
+  })
+}
+
+<%_ if (cedarPolicy) { _%>
+# Inline policy giving the gateway role the permissions it needs:
+#   - Policy evaluation permissions, including CheckAuthorizePermissions
+#     which the gateway readiness probe requires during creation.
+#     Authorization actions are evaluated against both the policy engine ARN
+#     and the gateway's own ARN (which cannot be referenced here without a
+#     dependency cycle, so it is scoped to this account and region's gateways)
+#   - Additional statements appended by connection generators (e.g. InvokeAgentRuntime*)
+resource "aws_iam_role_policy" "gateway_role_policy" {
+  name = "<%- nameClassName %>-GatewayPolicy"
+  role = aws_iam_role.gateway_role.id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = concat([
+      {
+        Sid    = "PolicyEvaluation"
+        Effect = "Allow"
+        Action = [
+          "bedrock-agentcore:GetPolicyEngine",
+          "bedrock-agentcore:AuthorizeAction",
+          "bedrock-agentcore:PartiallyAuthorizeActions",
+          "bedrock-agentcore:CheckAuthorizePermissions",
+        ]
+        Resource = [
+          aws_bedrockagentcore_policy_engine.this.policy_engine_arn,
+          "arn:aws:bedrock-agentcore:${local.aws_region}:${local.aws_account_id}:gateway/*",
+        ]
+      }
+    ], var.additional_iam_policy_statements)
+  })
+}
+<%_ } else { _%>
+# Inline policy for statements appended by connection generators
+# (e.g. InvokeAgentRuntime*)
+resource "aws_iam_role_policy" "gateway_role_policy" {
+  count = length(var.additional_iam_policy_statements) > 0 ? 1 : 0
+  name  = "<%- nameClassName %>-GatewayPolicy"
+  role  = aws_iam_role.gateway_role.id
+
+  policy = jsonencode({
+    Version   = "2012-10-17"
+    Statement = var.additional_iam_policy_statements
+  })
+}
+<%_ } _%>
+<%_ if (cedarPolicy) { _%>
+
+# Policy engine (name must match ^[A-Za-z][A-Za-z0-9_]*$ — no hyphens)
+resource "aws_bedrockagentcore_policy_engine" "this" {
+  name        = "<%- nameClassName %>_PolicyEngine_${random_id.unique_suffix.hex}"
+  description = "Cedar policy engine for <%- nameClassName %>"
+}
+<%_ } _%>
+
+resource "aws_bedrockagentcore_gateway" "this" {
+  # Cap the name so the 11-char service suffix keeps the gateway id within its
+  # 50-char limit (30 prefix + "-<8 hex>" + 11 = 50).
+  name        = "${substr("<%- nameClassName %>", 0, 30)}-${random_id.unique_suffix.hex}"
+  description = "AgentCore Gateway for <%- nameClassName %>"
+  role_arn    = aws_iam_role.gateway_role.arn
+
+  protocol_type = "MCP"
+  protocol_configuration {
+    mcp {
+      search_type        = "SEMANTIC"
+      supported_versions = ["2025-03-26"]
+    }
+  }
+
+  authorizer_type = "AWS_IAM"
+<%_ if (cedarPolicy) { _%>
+
+  policy_engine_configuration {
+    arn  = aws_bedrockagentcore_policy_engine.this.policy_engine_arn
+    mode = "ENFORCE"
+  }
+
+  depends_on = [aws_iam_role_policy.gateway_role_policy]
+<%_ } _%>
+}
+
+# WAFv2 protection for the gateway. AgentCore Gateway requires a REGIONAL web
+# ACL; CloudFront (global) is not supported.
+resource "aws_wafv2_web_acl" "gateway_waf" {
+  #checkov:skip=CKV2_AWS_31:Logging configuration is defined below in aws_wafv2_web_acl_logging_configuration.gateway_waf_logging; Checkov does not resolve the separate resource
+  count = var.enable_waf ? 1 : 0
+
+  name  = "<%- nameClassName %>-waf-${random_id.unique_suffix.hex}"
+  scope = "REGIONAL"
+
+  default_action {
+    allow {}
+  }
+
+  rule {
+    name     = "CRSRule"
+    priority = 0
+
+    override_action {
+      none {}
+    }
+
+    statement {
+      managed_rule_group_statement {
+        name        = "AWSManagedRulesCommonRuleSet"
+        vendor_name = "AWS"
+
+        # Count instead of Block: the CRS 8 KB body limit is too restrictive
+        # for typical MCP tool payloads.
+        rule_action_override {
+          name = "SizeRestrictions_BODY"
+          action_to_use {
+            count {}
+          }
+        }
+      }
+    }
+
+    visibility_config {
+      cloudwatch_metrics_enabled = true
+      metric_name                = "<%- nameClassName %>WebAcl-CRS"
+      sampled_requests_enabled   = true
+    }
+  }
+
+  rule {
+    name     = "KnownBadInputsRule"
+    priority = 1
+
+    override_action {
+      none {}
+    }
+
+    statement {
+      managed_rule_group_statement {
+        name        = "AWSManagedRulesKnownBadInputsRuleSet"
+        vendor_name = "AWS"
+      }
+    }
+
+    visibility_config {
+      cloudwatch_metrics_enabled = true
+      metric_name                = "<%- nameClassName %>WebAcl-KnownBadInputs"
+      sampled_requests_enabled   = true
+    }
+  }
+
+  visibility_config {
+    cloudwatch_metrics_enabled = true
+    metric_name                = "<%- nameClassName %>WebAcl"
+    sampled_requests_enabled   = true
+  }
+
+  lifecycle {
+    create_before_destroy = true
+  }
+}
+
+resource "aws_wafv2_web_acl_association" "gateway_waf" {
+  count = var.enable_waf ? 1 : 0
+
+  resource_arn = aws_bedrockagentcore_gateway.this.gateway_arn
+  web_acl_arn  = aws_wafv2_web_acl.gateway_waf[0].arn
+}
+
+# WAF request logs. WAFv2 requires the `aws-waf-logs-` name prefix.
+resource "aws_cloudwatch_log_group" "gateway_waf_logs" {
+  #checkov:skip=CKV_AWS_158:Using default CloudWatch log encryption
+  #checkov:skip=CKV_AWS_338:Log retention set to one year which is sufficient for WAF logs
+  count = var.enable_waf ? 1 : 0
+
+  name              = "aws-waf-logs-<%- nameKebabCase %>-${random_id.unique_suffix.hex}"
+  retention_in_days = 365
+}
+
+resource "aws_wafv2_web_acl_logging_configuration" "gateway_waf_logging" {
+  count = var.enable_waf ? 1 : 0
+
+  log_destination_configs = [aws_cloudwatch_log_group.gateway_waf_logs[0].arn]
+  resource_arn            = aws_wafv2_web_acl.gateway_waf[0].arn
+}
+<%_ if (cedarPolicy) { _%>
+
+# Anchor for the policy_dependencies variable — depends_on only accepts
+# static references, so the policies depend on this resource instead.
+resource "terraform_data" "policy_dependencies" {
+  input = var.policy_dependencies
+}
+
+# Policies are EJS templates rendered by render-cedar.cjs with `gatewayArn`
+# and `accountId` in scope.
+data "external" "rendered_policies" {
+  for_each = fileset(local.policies_dir, "**/*.cedar")
+
+  program = ["node", "${path.module}/render-cedar.cjs"]
+  query = {
+    template   = "${local.policies_dir}/${each.value}"
+    gatewayArn = aws_bedrockagentcore_gateway.this.gateway_arn
+    accountId  = local.aws_account_id
+  }
+}
+
+# One Policy per .cedar file in the project's policies/ directory.
+#
+# Policy resource names are derived from the file basename and normalised
+# to PascalCase. The AgentCore Policy resource `name` regex requires
+# `^[A-Za-z][A-Za-z0-9_]*$` — no hyphens — so the join() reassembles the
+# basename with each segment Title-cased.
+resource "aws_bedrockagentcore_policy" "policies" {
+  for_each = fileset(local.policies_dir, "**/*.cedar")
+
+  policy_engine_id = aws_bedrockagentcore_policy_engine.this.policy_engine_id
+  # Policy names are unique account-wide, so append this gateway's unique
+  # suffix to avoid collisions with other gateways.
+  name = join("", concat([
+    for word in split("-", replace(replace(trimsuffix(each.value, ".cedar"), "_", "-"), "/", "-")) :
+    "${upper(substr(word, 0, 1))}${substr(word, 1, length(word))}"
+  ], ["_${random_id.unique_suffix.hex}"]))
+  description = "Policy loaded from ${each.value}"
+  # 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.
+  validation_mode = "IGNORE_ALL_FINDINGS"
+  definition {
+    cedar {
+      statement = data.external.rendered_policies[each.value].result.rendered
+    }
+  }
+
+  depends_on = [terraform_data.policy_dependencies]
+}
+<%_ } _%>
+
+# A parent gateway fetches this gateway's tools when it registers it as a
+# target, so this gateway must already serve them — its own targets register
+# their tools asynchronously after creation. Probe `tools/list` over SigV4
+# until the configured `tool_dependencies` are served, and route `gateway_url`
+# through this resource so a parent gateway target waits for readiness. Only
+# runs when this gateway is aggregated by another (empty `tool_dependencies`).
+resource "null_resource" "gateway_ready" {
+  count = length(var.tool_dependencies) > 0 ? 1 : 0
+
+  triggers = {
+    gateway_url       = aws_bedrockagentcore_gateway.this.gateway_url
+    region            = local.aws_region
+    tool_dependencies = join(",", var.tool_dependencies)
+  }
+
+  provisioner "local-exec" {
+    command = <<-EOT
+      uv run --with boto3<%= boto3Version %> --with httpx<%= httpxVersion %> --with mcp<%= mcpVersion %> python -c "
+import asyncio
+import os
+import time
+
+import boto3
+import httpx
+from botocore.auth import SigV4Auth
+from botocore.awsrequest import AWSRequest
+from mcp import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+
+gateway_url = os.environ['GATEWAY_URL']
+region = os.environ['REGION']
+credentials = boto3.Session(region_name=region).get_credentials()
+signer = SigV4Auth(credentials, 'bedrock-agentcore', region)
+
+
+class SigV4Auth_(httpx.Auth):
+    requires_request_body = True
+
+    def auth_flow(self, request):
+        aws_request = AWSRequest(
+            method=request.method,
+            url=str(request.url),
+            data=request.content,
+            headers=dict(request.headers),
+        )
+        signer.add_auth(aws_request)
+        request.headers.update(dict(aws_request.headers))
+        yield request
+
+
+async def list_tools():
+    async with streamablehttp_client(
+        gateway_url, auth=SigV4Auth_(), timeout=120
+    ) as (read, write, _):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            result = await session.list_tools()
+            return [t.name for t in result.tools]
+
+
+# The built-in semantic-search tool is always present, so require at least one
+# more tool before declaring the gateway ready to serve its aggregated targets.
+deadline = time.time() + 5 * 60
+while True:
+    try:
+        tools = asyncio.run(list_tools())
+        if len([t for t in tools if t != 'x_amz_bedrock_agentcore_search']) > 0:
+            break
+        last = f'gateway serves no aggregated tools yet (got {tools})'
+    except Exception as e:
+        last = str(e)
+    if time.time() >= deadline:
+        raise SystemExit(f'Gateway {gateway_url} not ready: {last}')
+    time.sleep(5)
+
+print(f'Gateway {gateway_url} is serving tools')
+"
+    EOT
+    environment = {
+      GATEWAY_URL = self.triggers.gateway_url
+      REGION      = self.triggers.region
+    }
+  }
+}
+
+# Add gateway URL to runtime config
+module "add_gateway_url_to_runtime_config" {
+  source = "../../../core/runtime-config/entry"
+
+  namespace = "agentcore"
+  key       = "gateways"
+  value     = { "<%- nameClassName %>" = aws_bedrockagentcore_gateway.this.gateway_url }
+
+  depends_on = [aws_bedrockagentcore_gateway.this]
+}
+
+output "gateway_id" {
+  description = "ID of the Bedrock AgentCore Gateway"
+  value       = aws_bedrockagentcore_gateway.this.gateway_id
+}
+
+output "gateway_arn" {
+  description = "ARN of the Bedrock AgentCore Gateway"
+  value       = aws_bedrockagentcore_gateway.this.gateway_arn
+}
+
+output "gateway_url" {
+  description = "MCP endpoint URL of the Bedrock AgentCore Gateway. When `tool_dependencies` is set, this value flows through the readiness probe so consumers (e.g. a parent gateway target) wait until the gateway serves its aggregated tools."
+  value = length(var.tool_dependencies) > 0 ? (
+    null_resource.gateway_ready[0].triggers.gateway_url
+  ) : aws_bedrockagentcore_gateway.this.gateway_url
+}
+
+output "gateway_role_arn" {
+  description = "ARN of the IAM role assumed by the gateway service"
+  value       = aws_iam_role.gateway_role.arn
+}
+
+output "waf_web_acl_arn" {
+  description = "ARN of the WAFv2 web ACL associated with the gateway, or null if WAF is disabled"
+  value       = var.enable_waf ? aws_wafv2_web_acl.gateway_waf[0].arn : null
+}

package/src/utils/agent-core-constructs/files/terraform/app/agentcore-gateway/__nameKebabCase__/render-cedar.cjs.template

@@ -0,0 +1,13 @@
+// Renders a Cedar policy EJS template for the <%- nameClassName %> Terraform
+// module. Invoked by the `external` data source with JSON on stdin:
+//   { "template": "<path>", "gatewayArn": "...", "accountId": "..." }
+const ejs = require('ejs');
+const fs = require('fs');
+
+let input = '';
+process.stdin.on('data', (chunk) => (input += chunk));
+process.stdin.on('end', () => {
+  const { template, ...vars } = JSON.parse(input);
+  const rendered = ejs.render(fs.readFileSync(template, 'utf-8'), vars);
+  process.stdout.write(JSON.stringify({ rendered }));
+});

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

@@ -4,15 +4,15 @@ terraform {
   required_providers {
     aws = {
       source  = "hashicorp/aws"
-      version = ">= 6.23"
+      version = "<%- awsProviderVersion %>"
     }
     null = {
       source  = "hashicorp/null"
-      version = ">= 3.0"
+      version = "<%- nullProviderVersion %>"
     }
     random = {
       source  = "hashicorp/random"
-      version = ">= 3.0"
+      version = "<%- randomProviderVersion %>"
     }
   }
 }
@@ -95,8 +95,7 @@ resource "aws_ecr_repository" "agent_core_repository" {
   #checkov:skip=CKV_AWS_136:AES256 encryption is sufficient for ECR repositories
   name = "${lower(var.agent_runtime_name)}_repository_${random_id.unique_suffix.hex}"
 
-  #checkov:skip=CKV_AWS_51:Image tag is reused for latest deployments
-  image_tag_mutability = "MUTABLE"
+  image_tag_mutability = "IMMUTABLE"
   force_delete         = true
 
   image_scanning_configuration {
@@ -270,25 +269,37 @@ data "external" "docker_digest" {
   program = ["sh", "-c", "echo '{\"digest\":\"'$(<%= containers %> inspect ${var.docker_image_tag} --format '{{.Id}}')'\"}' "]
 }
 
+locals {
+  # Content-based, immutable image tag derived from the local image digest
+  image_tag = replace(data.external.docker_digest.result.digest, "sha256:", "")
+}
+
 # Null resource for container image publish
 resource "null_resource" "docker_publish" {
   triggers = {
     docker_digest    = data.external.docker_digest.result.digest
     repository_url   = aws_ecr_repository.agent_core_repository.repository_url
     docker_image_tag = var.docker_image_tag
+    image_tag        = local.image_tag
   }
 
   provisioner "local-exec" {
     command = <<-EOT
       # Get ECR login token
-      aws ecr get-login-password --region ${local.aws_region} | <%= containers %> login --username AWS --password-stdin ${self.triggers.repository_url}
+      aws ecr get-login-password --region "$AWS_REGION" | <%= containers %> login --username AWS --password-stdin "$REPOSITORY_URL"
 
-      # Tag the image
-      <%= containers %> tag ${self.triggers.docker_image_tag} ${self.triggers.repository_url}:latest
+      # Tag the image with the immutable content-based tag
+      <%= containers %> tag "$DOCKER_IMAGE_TAG" "$REPOSITORY_URL:$IMAGE_TAG"
 
       # Push the image
-      <%= containers %> push ${self.triggers.repository_url}:latest
+      <%= containers %> push "$REPOSITORY_URL:$IMAGE_TAG"
     EOT
+    environment = {
+      AWS_REGION       = local.aws_region
+      REPOSITORY_URL   = self.triggers.repository_url
+      DOCKER_IMAGE_TAG = self.triggers.docker_image_tag
+      IMAGE_TAG        = self.triggers.image_tag
+    }
   }
 
   depends_on = [aws_ecr_repository_policy.agent_core_ecr_policy]
@@ -302,7 +313,7 @@ resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
 
   agent_runtime_artifact {
     container_configuration {
-      container_uri = "${aws_ecr_repository.agent_core_repository.repository_url}:latest"
+      container_uri = "${aws_ecr_repository.agent_core_repository.repository_url}:${local.image_tag}"
     }
   }
 
@@ -335,6 +346,63 @@ resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
   ]
 }
 
+# MCP consumers (e.g. gateway targets, which fetch tools at creation) can race
+# the runtime's first cold start, so probe it until it serves MCP. The ARN
+# output is routed through this resource so consumers wait for readiness.
+resource "null_resource" "runtime_ready" {
+  count = var.server_protocol == "MCP" ? 1 : 0
+
+  triggers = {
+    runtime_arn = aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_arn
+  }
+
+  provisioner "local-exec" {
+    command = <<-EOT
+      uv run --with boto3<%= boto3Version %> python -c "
+import boto3
+import json
+import os
+import time
+import uuid
+
+runtime_arn = os.environ['RUNTIME_ARN']
+client = boto3.client('bedrock-agentcore')
+initialize_request = json.dumps({
+    'jsonrpc': '2.0',
+    'id': 1,
+    'method': 'initialize',
+    'params': {
+        'protocolVersion': '2025-03-26',
+        'capabilities': {},
+        'clientInfo': {'name': 'readiness-probe', 'version': '1.0'},
+    },
+})
+
+deadline = time.time() + 5 * 60
+while True:
+    try:
+        client.invoke_agent_runtime(
+            agentRuntimeArn=runtime_arn,
+            runtimeSessionId=f'readiness-probe-{uuid.uuid4()}',
+            contentType='application/json',
+            accept='application/json, text/event-stream',
+            payload=initialize_request,
+        )
+        break
+    except Exception:
+        if time.time() >= deadline:
+            raise
+        time.sleep(5)
+
+print(f'Runtime {runtime_arn} is serving MCP')
+"
+    EOT
+    environment = {
+      RUNTIME_ARN = self.triggers.runtime_arn
+    }
+  }
+}
+
 # Outputs
 output "agent_core_runtime_role_arn" {
   description = "ARN of the Agent Core Runtime IAM role"
@@ -352,8 +420,8 @@ output "agent_runtime_name" {
 }
 
 output "agent_core_runtime_arn" {
-  description = "ARN of the Bedrock Agent Core runtime"
-  value       = aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_arn
+  description = "ARN of the Bedrock Agent Core runtime. For MCP runtimes the value flows through the readiness probe, so consumers wait until the runtime serves MCP."
+  value       = var.server_protocol == "MCP" ? null_resource.runtime_ready[0].triggers.runtime_arn : aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_arn
 }
 
 output "agent_runtime_id" {

package/src/utils/agent-core-constructs/files/terraform/core/agentcore-gateway/gateway.tf.template

@@ -0,0 +1,14 @@
+terraform {
+  required_version = ">= 1.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "<%- awsProviderVersion %>"
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = "<%- randomProviderVersion %>"
+    }
+  }
+}

package/src/utils/api-constructs/api-constructs.d.ts

@@ -2,8 +2,8 @@
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Tree } from '@nx/devkit';
-import { Iac } from '../iac';
+import { type Tree } from '@nx/devkit';
+import type { Iac } from '../iac';
 interface BackendOptions {
     type: 'trpc' | 'fastapi' | 'smithy';
     integrationPattern: 'isolated' | 'shared';