Skip to content

aws-ia/terraform-aws-agentcore

BranchesTags

Repository files navigation

Bedrock AgentCore Module

The Amazon Bedrock AgentCore Terraform module provides a high-level, object-oriented approach to creating and managing Amazon Bedrock AgentCore resources using Terraform. This module abstracts away the complexity of the L1 resources and provides a higher level implementation.

Overview

The module provides support for Amazon Bedrock AgentCore Runtime, Runtime Endpoints, and Gateways. This allows you to deploy custom container-based runtimes for your Bedrock agents and create gateways, which serve as integration points between agents and external services.

This module simplifies the process of:

  • Creating and configuring Bedrock AgentCore Runtimes
  • Setting up AgentCore Runtime Endpoints
  • Creating and managing AgentCore Gateways
  • Managing IAM permissions for your runtimes and gateways
  • Configuring network access and security settings

Features

  • Custom Container Support: Deploy your own container images from Amazon ECR
  • Flexible Networking: Support for both PUBLIC and VPC network modes
  • IAM Role Management: Automatic creation of IAM roles with appropriate permissions
  • Environment Variables: Pass configuration to your runtime container
  • JWT Authorization: Optional JWT authorizer configuration for secure access
  • Endpoint Management: Create and manage runtime endpoints for client access
  • Gateway Support: Create and manage AgentCore Gateways for model context communication
  • Protocol Configuration: Configure MCP protocol settings for gateways
  • Gateway Security: Implement JWT authorization and KMS encryption for gateways
  • Granular Permissions: Control gateway create, read, update, and delete permissions
  • OAuth2 Outbound Authorization: Configure OAuth client for gateway outbound authorization
  • API Key Outbound Authorization: Configure API key for gateway outbound authorization

Usage

AgentCore Runtime and Endpoint

module "agentcore" {
  source  = "aws-ia/agentcore/aws"
  version = "0.0.2"

  # Enable Agent Core Runtime
  create_runtime = true
  runtime_name = "MyCustomRuntime"
  runtime_description = "Custom runtime for my Bedrock agent"
  runtime_container_uri = "123456789012.dkr.ecr.us-east-1.amazonaws.com/bedrock/agent-runtime:latest"
  runtime_network_mode = "PUBLIC"
  # Environment variables for the runtime
  runtime_environment_variables = {
    "LOG_LEVEL" = "INFO"
    "ENV" = "production"
  }
  # Enable Agent Core Runtime Endpoint
  create_runtime_endpoint = true
  runtime_endpoint_name = "MyRuntimeEndpoint"
  runtime_endpoint_description = "Endpoint for my custom runtime"
}

With JWT Authorization

module "agentcore" {
  source  = "aws-ia/agentcore/aws"
  version = "0.0.2"

  # Enable Agent Core Runtime
  create_runtime = true
  runtime_name = "SecureRuntime"
  runtime_container_uri = "123456789012.dkr.ecr.us-east-1.amazonaws.com/bedrock/agent-runtime:latest"

  # Configure JWT authorization
  runtime_authorizer_configuration = {
    custom_jwt_authorizer = {
      discovery_url = "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example/.well-known/jwks.json"
      allowed_audience = ["client-id-1", "client-id-2"]
    }
  }

  # Enable Agent Core Runtime Endpoint
  create_runtime_endpoint = true
  runtime_endpoint_name = "SecureEndpoint"
}

With Custom IAM Role

module "agentcore" {
  source  = "aws-ia/agentcore/aws"
  version = "0.0.2"

  # Enable Agent Core Runtime with custom IAM role
  create_runtime = true
  runtime_name = "CustomRoleRuntime"
  runtime_container_uri = "123456789012.dkr.ecr.us-east-1.amazonaws.com/bedrock/agent-runtime:latest"
  runtime_role_arn = "arn:aws:iam::123456789012:role/my-custom-bedrock-role"

  # Enable Agent Core Runtime Endpoint
  create_runtime_endpoint = true
  runtime_endpoint_name = "CustomRoleEndpoint"
}

AgentCore Gateway

Create and configure an MCP gateway:

module "agentcore" {
  source  = "aws-ia/agentcore/aws"
  version = "0.0.2"

  # Enable Agent Core Gateway
  create_gateway = true
  gateway_name = "MyMCPGateway"
  gateway_description = "Gateway for Model Context Protocol connections"

  # Configure the gateway protocol (MCP)
  gateway_protocol_type = "MCP"
  gateway_protocol_configuration = {
    mcp = {
      instructions = "Custom instructions for MCP tools and resources"
      search_type = "DEFAULT"
      supported_versions = ["1.0.0"]
    }
  }

  # Optional JWT authorization
  gateway_authorizer_type = "CUSTOM_JWT"
  gateway_authorizer_configuration = {
    custom_jwt_authorizer = {
      discovery_url = "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example/.well-known/jwks.json"
      allowed_audience = ["client-id-1", "client-id-2"]
    }
  }

  # Optional KMS encryption
  gateway_kms_key_arn = "<INSERT_KEY_HERE>"

  # Manage gateway permissions
  gateway_allow_create_permissions = true
  gateway_allow_update_delete_permissions = true
}

Automatic Cognito User Pool Creation

The module can automatically create a Cognito User Pool to handle JWT authentication when no JWT auth information is provided:

module "agentcore" {
  source  = "aws-ia/agentcore/aws"
  version = "0.0.2"

  # Enable Agent Core Gateway
  create_gateway = true
  gateway_name = "GatewayWithAutoCognito"
  gateway_authorizer_type = "CUSTOM_JWT"
  # No gateway_authorizer_configuration - a Cognito User Pool will be created automatically

}

In this scenario, the module will:

  1. Create a Cognito User Pool
  2. Configure a domain for the User Pool
  3. Set up a User Pool client with the necessary OAuth configuration
  4. Configure the gateway's JWT authorizer to use the User Pool

Architecture

The module creates the following resources:

  1. Agent Core Runtime: A container-based runtime environment for your Bedrock agent
  2. IAM Role and Policy: Permissions for the runtime to access AWS services
  3. Agent Core Runtime Endpoint: An endpoint for client applications to interact with the runtime
  4. Agent Core Gateway: A gateway for Model Context Protocol (MCP) connections
  5. Gateway IAM Role and Policy: Permissions for the gateway to access AWS services

The IAM role includes permissions for:

  • ECR image access
  • CloudWatch Logs
  • X-Ray tracing
  • CloudWatch metrics
  • Bedrock model invocation
  • Workload identity token management

Prerequisites

To use this module, you need:

  1. An AWS account with appropriate permissions
  2. Terraform >= 1.0.7
  3. AWS provider >= 4.0.0
  4. AWSCC provider >= 0.24.0
  5. A container image in Amazon ECR (for the runtime)

Examples

The module includes examples demonstrating different use cases:

Agent Runtime with STRANDS Framework

The agent-runtime example demonstrates:

  • Creating an ECR repository
  • Building and pushing a Docker image
  • Creating a Bedrock Agent Runtime and Endpoint
  • Implementing a STRANDS framework agent with tool-calling capabilities

This example includes:

  • A Python implementation using the STRANDS framework
  • Tools for calculations, weather information, and greetings
  • Testing scripts for local and deployed testing

Advanced Configuration

Network Configuration

The module supports both PUBLIC and VPC network modes:

# Public network mode (default)
runtime_network_mode = "PUBLIC"

# VPC network mode (requires additional configuration)
runtime_network_mode = "VPC"

Environment Variables

Pass configuration to your runtime container:

runtime_environment_variables = {
  "LOG_LEVEL" = "DEBUG"
  "MODEL_ID" = "anthropic.claude-3-sonnet-20240229-v1:0"
  "MAX_TOKENS" = "4096"
}

Tags

Add tags to your resources:

runtime_tags = {
  Environment = "production"
  Project     = "ai-assistants"
  Owner       = "data-science-team"
}

runtime_endpoint_tags = {
  Environment = "production"
  Project     = "ai-assistants"
  Owner       = "data-science-team"
}

gateway_tags = {
  Environment = "production"
  Project     = "ai-assistants"
  Owner       = "data-science-team"
}

Requirements

Name Version
terraform >= 1.0.7
aws >= 4.0.0
awscc >= 0.24.0
random >= 3.6.0
time >= 0.9.0

Providers

Name Version
aws >= 4.0.0
awscc >= 0.24.0
random >= 3.6.0
time >= 0.9.0

Modules

No modules.

Resources

Name Type
aws_cognito_user.admin resource
aws_cognito_user_pool.default resource
aws_cognito_user_pool_client.default resource
aws_cognito_user_pool_domain.default resource
aws_iam_role.gateway_role resource
aws_iam_role.runtime_role resource
aws_iam_role_policy.gateway_role_policy resource
aws_iam_role_policy.runtime_role_policy resource
aws_iam_role_policy.runtime_slr_policy resource
aws_lambda_permission.cross_account_lambda_permissions resource
awscc_bedrockagentcore_gateway.agent_gateway resource
awscc_bedrockagentcore_runtime.agent_runtime resource
awscc_bedrockagentcore_runtime_endpoint.agent_runtime_endpoint resource
random_password.password resource
random_string.solution_prefix resource
time_sleep.iam_role_propagation resource
aws_caller_identity.current data source
aws_iam_policy_document.service_linked_role data source
aws_region.current data source

Inputs

Name Description Type Default Required
apikey_credential_provider_arn ARN of the API key credential provider created with CreateApiKeyCredentialProvider. Required when enable_apikey_outbound_auth is true. string null no
apikey_secret_arn ARN of the AWS Secrets Manager secret containing the API key. Required when enable_apikey_outbound_auth is true. string null no
create_gateway Whether or not to create an agent core gateway. bool false no
create_runtime Whether or not to create an agent core runtime. bool false no
create_runtime_endpoint Whether or not to create an agent core runtime endpoint. bool false no
enable_apikey_outbound_auth Whether to enable outbound authorization with an API key for the gateway. bool false no
enable_oauth_outbound_auth Whether to enable outbound authorization with an OAuth client for the gateway. bool false no
gateway_allow_create_permissions Whether to allow create permissions for the gateway. bool true no
gateway_allow_update_delete_permissions Whether to allow update and delete permissions for the gateway. bool false no
gateway_authorizer_configuration Authorizer configuration for the agent core gateway. 
object({
    custom_jwt_authorizer = object({
      allowed_audience = optional(list(string))
      allowed_clients  = optional(list(string))
      discovery_url    = string
    })
  })
 null no
gateway_authorizer_type The authorizer type for the gateway. Valid values: AWS_IAM, CUSTOM_JWT. string "CUSTOM_JWT" no
gateway_cross_account_lambda_permissions Configuration for cross-account Lambda function access. Required only if Lambda functions are in different AWS accounts. 
list(object({
    lambda_function_arn      = string
    gateway_service_role_arn = string
  }))
 [] no
gateway_description Description of the agent core gateway. string null no
gateway_exception_level Exception level for the gateway. Valid values: PARTIAL, FULL. string null no
gateway_kms_key_arn The ARN of the KMS key used to encrypt the gateway. string null no
gateway_lambda_function_arns List of Lambda function ARNs that the gateway service role should be able to invoke. Required when using Lambda targets. list(string) [] no
gateway_name The name of the agent core gateway. string "TerraformBedrockAgentCoreGateway" no
gateway_protocol_configuration Protocol configuration for the agent core gateway. 
object({
    mcp = object({
      instructions       = optional(string)
      search_type        = optional(string)
      supported_versions = optional(list(string))
    })
  })
 null no
gateway_protocol_type The protocol type for the gateway. Valid value: MCP. string "MCP" no
gateway_role_arn Optional external IAM role ARN for the Bedrock agent core gateway. If empty, the module will create one internally. string null no
gateway_tags A map of tag keys and values for the agent core gateway. map(string) null no
oauth_credential_provider_arn ARN of the OAuth credential provider created with CreateOauth2CredentialProvider. Required when enable_oauth_outbound_auth is true. string null no
oauth_secret_arn ARN of the AWS Secrets Manager secret containing the OAuth client credentials. Required when enable_oauth_outbound_auth is true. string null no
permissions_boundary_arn The ARN of the IAM permission boundary for the role. string null no
runtime_authorizer_configuration Authorizer configuration for the agent core runtime. 
object({
    custom_jwt_authorizer = object({
      allowed_audience = optional(list(string))
      allowed_clients  = optional(list(string))
      discovery_url    = string
    })
  })
 null no
runtime_container_uri The ECR URI of the container for the agent core runtime. string null no
runtime_description Description of the agent runtime. string null no
runtime_endpoint_agent_runtime_id The ID of the agent core runtime associated with the endpoint. If not provided, it will use the ID of the agent runtime created by this module. string null no
runtime_endpoint_description Description of the agent core runtime endpoint. string null no
runtime_endpoint_name The name of the agent core runtime endpoint. string "TerraformBedrockAgentCoreRuntimeEndpoint" no
runtime_endpoint_tags A map of tag keys and values for the agent core runtime endpoint. map(string) null no
runtime_environment_variables Environment variables for the agent core runtime. map(string) null no
runtime_name The name of the agent core runtime. string "TerraformBedrockAgentCoreRuntime" no
runtime_network_configuration VPC network configuration for the agent core runtime. 
object({
    security_groups = optional(list(string))
    subnets         = optional(list(string))
  })
 null no
runtime_network_mode Network mode configuration type for the agent core runtime. Valid values: PUBLIC, VPC. string "PUBLIC" no
runtime_protocol_configuration Protocol configuration for the agent core runtime. string null no
runtime_role_arn Optional external IAM role ARN for the Bedrock agent core runtime. If empty, the module will create one internally. string null no
runtime_tags A map of tag keys and values for the agent core runtime. map(string) null no
user_pool_admin_email Email address for the admin user. string "[email protected]" no
user_pool_allowed_clients List of allowed clients for the Cognito User Pool JWT authorizer. list(string) [] no
user_pool_callback_urls List of allowed callback URLs for the Cognito User Pool client. list(string) 
[
  "http://localhost:3000"
]
 no
user_pool_create_admin Whether to create an admin user in the Cognito User Pool. bool false no
user_pool_logout_urls List of allowed logout URLs for the Cognito User Pool client. list(string) 
[
  "http://localhost:3000"
]
 no
user_pool_mfa_configuration MFA configuration for the Cognito User Pool. Valid values: OFF, OPTIONAL, REQUIRED. string "OFF" no
user_pool_name The name of the Cognito User Pool to create when JWT auth info is not provided. string "AgentCoreUserPool" no
user_pool_password_policy Password policy for the Cognito User Pool. 
object({
    minimum_length    = optional(number, 8)
    require_lowercase = optional(bool, true)
    require_numbers   = optional(bool, true)
    require_symbols   = optional(bool, true)
    require_uppercase = optional(bool, true)
  })
 {} no
user_pool_refresh_token_validity_days Number of days that refresh tokens are valid for. number 30 no
user_pool_tags A map of tag keys and values for the Cognito User Pool. map(string) null no
user_pool_token_validity_hours Number of hours that ID and access tokens are valid for. number 24 no

Outputs

Name Description
agent_gateway_arn ARN of the created Bedrock AgentCore Gateway
agent_gateway_id ID of the created Bedrock AgentCore Gateway
agent_gateway_status Status of the created Bedrock AgentCore Gateway
agent_gateway_status_reasons Status reasons of the created Bedrock AgentCore Gateway
agent_gateway_url URL of the created Bedrock AgentCore Gateway
agent_gateway_workload_identity_details Workload identity details of the created Bedrock AgentCore Gateway
agent_runtime_arn ARN of the created Bedrock AgentCore Runtime
agent_runtime_endpoint_arn ARN of the created Bedrock AgentCore Runtime Endpoint
agent_runtime_endpoint_id ID of the created Bedrock AgentCore Runtime Endpoint
agent_runtime_endpoint_live_version Live version of the created Bedrock AgentCore Runtime Endpoint
agent_runtime_endpoint_status Status of the created Bedrock AgentCore Runtime Endpoint
agent_runtime_endpoint_target_version Target version of the created Bedrock AgentCore Runtime Endpoint
agent_runtime_id ID of the created Bedrock AgentCore Runtime
agent_runtime_status Status of the created Bedrock AgentCore Runtime
agent_runtime_version Version of the created Bedrock AgentCore Runtime
agent_runtime_workload_identity_details Workload identity details of the created Bedrock AgentCore Runtime
cognito_discovery_url OpenID Connect discovery URL for the Cognito User Pool
cognito_domain Domain of the Cognito User Pool
gateway_role_arn ARN of the IAM role created for the Bedrock AgentCore Gateway
gateway_role_name Name of the IAM role created for the Bedrock AgentCore Gateway
runtime_role_arn ARN of the IAM role created for the Bedrock AgentCore Runtime
runtime_role_name Name of the IAM role created for the Bedrock AgentCore Runtime
user_pool_arn ARN of the Cognito User Pool created as JWT authentication fallback
user_pool_client_id ID of the Cognito User Pool Client
user_pool_endpoint Endpoint of the Cognito User Pool created as JWT authentication fallback
user_pool_id ID of the Cognito User Pool created as JWT authentication fallback
using_cognito_fallback Whether the module is using a Cognito User Pool as fallback for JWT authentication

About

No description or website provided.

Topics

ia-automator

Resources

Readme

License

Apache-2.0 license

Code of conduct

Code of conduct

Contributing

Contributing
Activity
Custom properties

Stars

5 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases 2

v0.0.2 Latest
Oct 16, 2025
+ 1 release

Packages

No packages published

Contributors 2

Languages