@aws/nx-plugin 1.0.0-rc.7 → 1.0.0-rc.71

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

@@ -0,0 +1,282 @@
+terraform {
+  required_version = ">= 1.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "<%- awsProviderVersion %>"
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = "<%- randomProviderVersion %>"
+    }
+  }
+}
+
+variable "model_id" {
+  description = "Amazon Bedrock model or inference profile used by default."
+  type        = string
+  default     = "global.anthropic.claude-sonnet-4-6"
+}
+
+variable "model_resource_arns" {
+  description = "Bedrock model and inference-profile ARNs the execution role may invoke. Defaults to every foundation model plus this account's Bedrock resources in the deployment region; replace with narrower ARNs to restrict baseline model access."
+  type        = set(string)
+  default     = null
+}
+
+variable "additional_execution_role_policy_statements" {
+  description = "Additional least-privilege IAM policy statements required by configured optional capabilities (e.g. customer-owned Gateways, memory, custom browsers or code interpreters, skills, secrets). Sid and Condition are optional; null fields are omitted from the rendered policy."
+  type = list(object({
+    Sid       = optional(string)
+    Effect    = string
+    Action    = list(string)
+    Resource  = list(string)
+    Condition = optional(any)
+  }))
+  default = []
+}
+
+data "aws_caller_identity" "current" {}
+data "aws_partition" "current" {}
+data "aws_region" "current" {}
+
+resource "random_id" "unique_suffix" {
+  byte_length = 4
+}
+
+locals {
+  account_id = data.aws_caller_identity.current.account_id
+  partition  = data.aws_partition.current.partition
+  region     = data.aws_region.current.region
+
+  # Capped at 31 characters so the suffix keeps the deployed Harness name
+  # within its 40-character limit.
+  harness_name_prefix = "<%- harnessNamePrefix %>"
+  harness_name        = "${local.harness_name_prefix}_${random_id.unique_suffix.hex}"
+
+  # Set var.model_resource_arns to narrow the default model access.
+  model_resource_arns = var.model_resource_arns != null ? var.model_resource_arns : [
+    "arn:${local.partition}:bedrock:*::foundation-model/*",
+    "arn:${local.partition}:bedrock:${local.region}:${local.account_id}:*",
+  ]
+}
+
+resource "aws_iam_role" "execution_role" {
+  name = "${local.harness_name_prefix}-HarnessRole-${random_id.unique_suffix.hex}"
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect = "Allow"
+      Principal = {
+        Service = "bedrock-agentcore.amazonaws.com"
+      }
+      Action = "sts:AssumeRole"
+      Condition = {
+        StringEquals = {
+          "aws:SourceAccount" = local.account_id
+        }
+        ArnLike = {
+          "aws:SourceArn" = "arn:${local.partition}:bedrock-agentcore:${local.region}:${local.account_id}:*"
+        }
+      }
+    }]
+  })
+}
+
+# Baseline permissions per the AgentCore Harness security guidance; extend for
+# customer-owned resources via var.additional_execution_role_policy_statements.
+# https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-security.html
+resource "aws_iam_role_policy" "execution_role" {
+  name = "${local.harness_name_prefix}-HarnessPolicy"
+  role = aws_iam_role.execution_role.id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = concat([
+      {
+        Sid    = "BedrockModelInvocation"
+        Effect = "Allow"
+        Action = [
+          "bedrock:InvokeModel",
+          "bedrock:InvokeModelWithResponseStream",
+        ]
+        Resource = local.model_resource_arns
+      },
+      {
+        #checkov:skip=CKV_AWS_355:EcrPublicTokenAccess requires a wildcard resource; ecr-public:GetAuthorizationToken has no resource-level permission
+        Sid      = "EcrPublicTokenAccess"
+        Effect   = "Allow"
+        Action   = ["ecr-public:GetAuthorizationToken"]
+        Resource = ["*"]
+      },
+      {
+        #checkov:skip=CKV_AWS_355:StsForEcrPublicPull requires a wildcard resource; sts:GetServiceBearerToken has no resource-level permission
+        Sid      = "StsForEcrPublicPull"
+        Effect   = "Allow"
+        Action   = ["sts:GetServiceBearerToken"]
+        Resource = ["*"]
+      },
+      {
+        #checkov:skip=CKV_AWS_355:XRayTracingAccess requires a wildcard resource; the X-Ray segment and sampling APIs have no resource-level permission
+        #checkov:skip=CKV_AWS_290:XRayTracingAccess requires a wildcard resource; the X-Ray segment and sampling APIs have no resource-level permission
+        Sid    = "XRayTracingAccess"
+        Effect = "Allow"
+        Action = [
+          "xray:PutTraceSegments",
+          "xray:PutTelemetryRecords",
+          "xray:GetSamplingRules",
+          "xray:GetSamplingTargets",
+        ]
+        Resource = ["*"]
+      },
+      {
+        Sid    = "CloudWatchLogsGroup"
+        Effect = "Allow"
+        Action = [
+          "logs:CreateLogGroup",
+          "logs:DescribeLogStreams",
+        ]
+        Resource = [
+          "arn:${local.partition}:logs:${local.region}:${local.account_id}:log-group:/aws/bedrock-agentcore/runtimes/*",
+        ]
+      },
+      {
+        Sid      = "CloudWatchLogsDescribeGroups"
+        Effect   = "Allow"
+        Action   = ["logs:DescribeLogGroups"]
+        Resource = ["arn:${local.partition}:logs:${local.region}:${local.account_id}:log-group:*"]
+      },
+      {
+        Sid    = "CloudWatchLogsStream"
+        Effect = "Allow"
+        Action = [
+          "logs:CreateLogStream",
+          "logs:PutLogEvents",
+        ]
+        Resource = [
+          "arn:${local.partition}:logs:${local.region}:${local.account_id}:log-group:/aws/bedrock-agentcore/runtimes/*:log-stream:*",
+        ]
+      },
+      {
+        #checkov:skip=CKV_AWS_355:CloudWatchMetricsPublish requires a wildcard resource; cloudwatch:PutMetricData is scoped by the namespace condition instead
+        #checkov:skip=CKV_AWS_290:CloudWatchMetricsPublish requires a wildcard resource; cloudwatch:PutMetricData is scoped by the namespace condition instead
+        Sid      = "CloudWatchMetricsPublish"
+        Effect   = "Allow"
+        Action   = ["cloudwatch:PutMetricData"]
+        Resource = ["*"]
+        Condition = {
+          StringEquals = {
+            "cloudwatch:namespace" = "bedrock-agentcore"
+          }
+        }
+      },
+      {
+        Sid    = "AgentCoreWorkloadIdentity"
+        Effect = "Allow"
+        Action = [
+          "bedrock-agentcore:GetWorkloadAccessToken",
+          "bedrock-agentcore:GetWorkloadAccessTokenForJWT",
+        ]
+        Resource = [
+          "arn:${local.partition}:bedrock-agentcore:${local.region}:${local.account_id}:workload-identity-directory/default",
+          "arn:${local.partition}:bedrock-agentcore:${local.region}:${local.account_id}:workload-identity-directory/default/workload-identity/harness_${local.harness_name}-*",
+        ]
+      },
+      # The service names the managed memory from the harness name plus a
+      # generated suffix, so this scopes to that prefix.
+      {
+        Sid    = "AgentCoreManagedMemory"
+        Effect = "Allow"
+        Action = [
+          "bedrock-agentcore:CreateEvent",
+          "bedrock-agentcore:DeleteEvent",
+          "bedrock-agentcore:GetEvent",
+          "bedrock-agentcore:ListEvents",
+          "bedrock-agentcore:RetrieveMemoryRecords",
+        ]
+        Resource = [
+          "arn:${local.partition}:bedrock-agentcore:${local.region}:${local.account_id}:memory/${local.harness_name}-*",
+        ]
+      },
+      {
+        Sid    = "AgentCoreBrowserDefault"
+        Effect = "Allow"
+        Action = [
+          "bedrock-agentcore:StartBrowserSession",
+          "bedrock-agentcore:StopBrowserSession",
+          "bedrock-agentcore:GetBrowserSession",
+          "bedrock-agentcore:ListBrowserSessions",
+          "bedrock-agentcore:UpdateBrowserStream",
+          "bedrock-agentcore:ConnectBrowserAutomationStream",
+          "bedrock-agentcore:ConnectBrowserLiveViewStream",
+        ]
+        Resource = [
+          "arn:${local.partition}:bedrock-agentcore:${local.region}:aws:browser/*",
+        ]
+      },
+      {
+        Sid    = "AgentCoreCodeInterpreterDefault"
+        Effect = "Allow"
+        Action = [
+          "bedrock-agentcore:StartCodeInterpreterSession",
+          "bedrock-agentcore:StopCodeInterpreterSession",
+          "bedrock-agentcore:GetCodeInterpreterSession",
+          "bedrock-agentcore:ListCodeInterpreterSessions",
+          "bedrock-agentcore:InvokeCodeInterpreter",
+        ]
+        Resource = [
+          "arn:${local.partition}:bedrock-agentcore:${local.region}:aws:code-interpreter/*",
+        ]
+      },
+      ], [
+      # Null Sid/Condition fields are dropped from the rendered policy.
+      for statement in var.additional_execution_role_policy_statements :
+      { for key, value in statement : key => value if value != null }
+    ])
+  })
+}
+
+# Omitting authorizer_configuration uses IAM inbound authorization; add a
+# custom_jwt_authorizer block to change that.
+resource "aws_bedrockagentcore_harness" "this" {
+  harness_name       = local.harness_name
+  execution_role_arn = aws_iam_role.execution_role.arn
+
+  model {
+    bedrock_model_config {
+      model_id = var.model_id
+    }
+  }
+
+  # Read at plan time; the walk up from path.module reaches the workspace root.
+  system_prompt {
+    text = file("${path.module}/../../../../../../../<%- promptPathFromTerraform %>")
+  }
+
+  depends_on = [aws_iam_role_policy.execution_role]
+}
+
+module "add_harness_arn_to_runtime_config" {
+  source = "../../../core/runtime-config/entry"
+
+  namespace = "agentcore"
+  key       = "harnesses"
+  value     = { "<%- nameClassName %>" = aws_bedrockagentcore_harness.this.arn }
+}
+
+output "harness_id" {
+  description = "ID of the Amazon Bedrock AgentCore Harness"
+  value       = aws_bedrockagentcore_harness.this.harness_id
+}
+
+output "harness_arn" {
+  description = "ARN of the Amazon Bedrock AgentCore Harness"
+  value       = aws_bedrockagentcore_harness.this.arn
+}
+
+output "execution_role_arn" {
+  description = "ARN of the IAM role assumed by the Harness"
+  value       = aws_iam_role.execution_role.arn
+}

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 %>"
     }
   }
 }
@@ -70,6 +70,30 @@ variable "additional_iam_policy_statements" {
   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
+
+  validation {
+    condition     = !var.enable_vpc || (var.vpc_id != null && var.subnet_ids != null)
+    error_message = "vpc_id and subnet_ids must be set when enable_vpc is true."
+  }
+}
+
+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 "tags" {
   description = "Tags to apply to resources"
   type        = map(string)
@@ -95,8 +119,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,30 +293,64 @@ 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]
 }
 
+# Security group for the agent core runtime, used when running inside a VPC
+resource "aws_security_group" "agent_core_runtime" {
+  count = var.enable_vpc ? 1 : 0
+
+  #checkov:skip=CKV2_AWS_5:Attached to the runtime via network_configuration; Checkov cannot resolve this reference
+  name_prefix = "${var.agent_runtime_name}-runtime-"
+  description = "Security group for the ${var.agent_runtime_name} agent core runtime"
+  vpc_id      = var.vpc_id
+  tags        = var.tags
+}
+
+resource "aws_vpc_security_group_egress_rule" "agent_core_runtime_https" {
+  count = var.enable_vpc ? 1 : 0
+
+  security_group_id = aws_security_group.agent_core_runtime[0].id
+  cidr_ipv4         = "0.0.0.0/0"
+  from_port         = 443
+  to_port           = 443
+  ip_protocol       = "tcp"
+  description       = "Allow outbound HTTPS to AWS service endpoints"
+}
+
 # Bedrock AgentCore Agent Runtime
 resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
   agent_runtime_name = "${var.agent_runtime_name}_${random_id.unique_suffix.hex}"
@@ -302,7 +359,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}"
     }
   }
 
@@ -319,8 +376,24 @@ resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
     }
   }
 
+  # Receive the caller's Authorization header (validated by the JWT authorizer).
+  dynamic "request_header_configuration" {
+    for_each = var.authorizer_configuration != null && try(var.authorizer_configuration.custom_jwt_authorizer, null) != null ? [1] : []
+    content {
+      request_header_allowlist = ["Authorization"]
+    }
+  }
+
   network_configuration {
-    network_mode = "PUBLIC"
+    network_mode = var.enable_vpc ? "VPC" : "PUBLIC"
+
+    dynamic "network_mode_config" {
+      for_each = var.enable_vpc ? [1] : []
+      content {
+        security_groups = [aws_security_group.agent_core_runtime[0].id]
+        subnets         = var.subnet_ids
+      }
+    }
   }
 
   protocol_configuration {
@@ -335,7 +408,70 @@ 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
+locals {
+  # For MCP runtimes the ARN flows through the readiness probe, so consumers
+  # wait until the runtime serves MCP.
+  ready_runtime_arn = var.server_protocol == "MCP" ? null_resource.runtime_ready[0].triggers.runtime_arn : aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_arn
+}
+
 output "agent_core_runtime_role_arn" {
   description = "ARN of the Agent Core Runtime IAM role"
   value       = aws_iam_role.agent_core_runtime_role.arn
@@ -352,8 +488,13 @@ 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       = local.ready_runtime_arn
+}
+
+output "invocation_url" {
+  description = "HTTPS invocation URL of the runtime. MCP runtimes get the MCP endpoint (e.g. for use as a Gateway target endpoint), A2A runtimes the A2A endpoint (trailing slash required). For MCP runtimes the value flows through the readiness probe, so consumers wait until the runtime serves MCP."
+  value       = "https://bedrock-agentcore.${local.aws_region}.amazonaws.com/runtimes/${urlencode(local.ready_runtime_arn)}/invocations${var.server_protocol == "A2A" ? "/" : "?qualifier=DEFAULT"}"
 }
 
 output "agent_runtime_id" {
@@ -365,3 +506,8 @@ output "agent_runtime_version" {
   description = "Version of the Bedrock Agent Core runtime"
   value       = aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_version
 }
+
+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       = var.enable_vpc ? aws_security_group.agent_core_runtime[0].id : null
+}

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

@@ -3,7 +3,35 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { type Tree } from '@nx/devkit';
+import { type DependencyDeclaration, type MustDeclare } from '../declared-dependencies';
 import type { Iac } from '../iac';
+import { type IacMetadata } from '../shared-constructs-constants';
+/**
+ * Dependencies a caller must declare to add API Gateway infrastructure.
+ *
+ * Gated on infrastructure having been generated: `addApiGatewayInfra` only runs
+ * on that branch, so a project generated with `infra: 'none'` never receives
+ * these.
+ */
+export declare const API_CONSTRUCTS_DEPENDENCIES: readonly [{
+    readonly name: "@aws-sdk/client-api-gateway";
+    readonly when: (m: IacMetadata) => boolean;
+}, {
+    readonly name: "@aws-sdk/client-iam";
+    readonly when: (m: IacMetadata) => boolean;
+}, {
+    readonly name: "@trpc/server";
+    readonly when: (m: IacMetadata) => boolean;
+}];
+/**
+ * Python version the generated Terraform pins in the account module's inline
+ * `uv run --with` script. Nothing installs it, so it is declared for its version
+ * alone, and only on the Terraform branch that writes the script.
+ */
+export declare const API_CONSTRUCTS_PY_DEPENDENCIES: readonly [{
+    readonly name: "boto3";
+    readonly when: (m: IacMetadata) => boolean;
+}];
 interface BackendOptions {
     type: 'trpc' | 'fastapi' | 'smithy';
     integrationPattern: 'isolated' | 'shared';
@@ -32,7 +60,7 @@ export interface AddApiGatewayConstructOptions {
     backend: TrpcBackendOptions | FastApiBackendOptions | SmithyBackendOptions;
     auth: 'iam' | 'cognito' | 'custom';
 }
-export declare const addApiGatewayInfra: (tree: Tree, options: AddApiGatewayConstructOptions & {
+export declare const addApiGatewayInfra: <const D extends DependencyDeclaration>(tree: Tree, options: AddApiGatewayConstructOptions & {
     iac: Iac;
-}) => Promise<void>;
+}, declaration: D & MustDeclare<typeof API_CONSTRUCTS_DEPENDENCIES, D>) => Promise<void>;
 export {};