AWS bedrock-agentcore documentation change
Summary
Restructured documentation with added sections for Required Permissions, Smithy Model Types, and Smithy Feature Support. Updated examples and added explicit IAM policy requirements for service access.
Security assessment
The change adds documentation about required IAM permissions for accessing AWS services (security documentation) but does not address a specific security vulnerability. The IAM policy example demonstrates least-privilege access patterns but is part of normal service configuration guidance rather than a security fix.
Diff
diff --git a/bedrock-agentcore/latest/devguide/gateway-building-smithy-targets.md b/bedrock-agentcore/latest/devguide/gateway-building-smithy-targets.md index 5f901063d..2a478723e 100644 --- a//bedrock-agentcore/latest/devguide/gateway-building-smithy-targets.md +++ b//bedrock-agentcore/latest/devguide/gateway-building-smithy-targets.md @@ -5 +5 @@ -Understanding Smithy Model TargetsCreating a Smithy targetUsing Built-in AWS Service ModelsCustom Smithy ModelsRequired PermissionsTesting Your Smithy Model TargetAdvanced Smithy Model Target ConfigurationsSupported Smithy featuresUnsupported Smithy featuresSmithy considerations +Understanding Smithy Model TargetsRequired PermissionsSmithy Model TypesSmithy Feature SupportCreating a Smithy targetUpdating a Smithy Model TargetTesting Your Smithy Model TargetAdvanced Smithy Model Target Configurations @@ -43,0 +44,228 @@ Key components of Smithy model targets include: +## Required Permissions + +For Smithy model targets that access AWS services, your Gateway's execution role needs permissions to access those services. For example, for a DynamoDB target, your execution role needs permissions to perform DynamoDB operations: + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "dynamodb:GetItem", + "dynamodb:PutItem", + "dynamodb:UpdateItem", + "dynamodb:DeleteItem", + "dynamodb:Query", + "dynamodb:Scan" + ], + "Resource": "arn:aws:dynamodb:*:*:table/*" + } + ] + } + + +## Smithy Model Types + +AgentCore Gateway supports two main types of Smithy models: built-in AWS service models and custom Smithy models. You can choose the approach that best fits your needs. + +Built-in AWS Service Models + + +AgentCore Gateway provides built-in Smithy models for common AWS services via an AWS provided S3 bucket that hosts the Smithy files. You can pass the Smithy file URIs to the create target API. + +When you create a Smithy model target without specifying a custom model in the AgentCoreSDK, the Gateway will use the built-in DynamoDB model. + +Here's an example of creating a Smithy model target for DynamoDB: + + + # Create a Smithy model target for DynamoDB + dynamodb_target = gateway_client.create_mcp_gateway_target( + gateway=gateway, + target_type="smithyModel", + target_name="DynamoDBTarget", + target_description="Target for DynamoDB operations" + ) + + +With this target, your Gateway will expose DynamoDB operations as tools that can be invoked through the MCP interface. + +Custom Smithy Models + + +You can also use custom Smithy models to define your own service APIs. To use a custom Smithy model: + + * **Create a Smithy model** that defines your service API + + * **Convert the Smithy model** to JSON format + + * **Upload the JSON model** to an Amazon S3 bucket + + * **Reference the S3 location** when creating your Smithy model target + + + + +Here's an example of creating a Smithy model target with a custom model: + + + # Create a Smithy model target with a custom model + custom_smithy_target = gateway_client.create_mcp_gateway_target( + gateway=gateway, + target_type="smithyModel", + target_name="CustomServiceTarget", + target_description="Target for custom service API", + target_payload={ + "s3": { + "uri": "s3://your-bucket/path/to/custom-smithy-model.json" + } + } + ) + + +## Smithy Feature Support + +The following table outlines the Smithy features that are supported and unsupported by Gateway: + +Smithy Feature Support Supported Features | Unsupported Features +---|--- +**Service Definitions** + + * Service structure definitions based on Smithy specifications + * Operation definitions with input/output shapes + * Resource definitions + * Trait shapes + +| **Endpoint Rules** + + * Endpoint creation rule sets + * Runtime endpoint determination based on conditions + * Complex URL parameters beyond simple {region} substitution + + +**Protocol Support** + + * RestJson protocol + * Standard HTTP request/response patterns + +| **Protocol Support** + + * RestXml protocol + * JsonRpc protocol + * AwsQuery protocol + * Ec2Query protocol + * Custom protocols + + +**Data Types** + + * Primitive types (string, integer, boolean, float, double) + * Complex types (structures, lists, maps) + * Timestamp handling + * Blob data types + +| **Authentication** + + * Multiple egress authentication types for specific APIs + * Complex authentication schemes requiring runtime decisions + + +**HTTP Bindings** + + * Basic HTTP method bindings + * Simple path parameter bindings + * Query parameter bindings + * Header bindings for simple cases + +| **Operations** + + * Streaming operations + * Operations requiring custom protocol implementations + + + +When using Smithy models with Gateway, be aware of the following limitations: + + * Maximum model size: 10MB + + * Only JSON protocol bindings are fully supported + + * Only RestJson protocol is supported + + * Complex endpoint creation rule sets are not supported + + * Only simple URL parameters like {region} are supported + + + + +Example of a supported Smithy model for a weather service: + + + namespace example.weather + + use aws.protocols#restJson1 + use smithy.framework#ValidationException + + /// Weather service for retrieving weather information + @restJson1 + service WeatherService { + version: "1.0.0", + operations: [GetCurrentWeather] + } + + /// Get current weather for a location + @http(method: "GET", uri: "/weather") + operation GetCurrentWeather { + input: GetCurrentWeatherInput, + output: GetCurrentWeatherOutput, + errors: [ValidationException] + } + + structure GetCurrentWeatherInput { + /// City name or coordinates + @required + @httpQuery("location") + location: String, + + /// Units of measurement (metric or imperial) + @httpQuery("units") + units: Units = metric + } +