Bedrock reference

Depth behind the Bedrock guide.

Model-id resolution

The gateway resolves a Claude id in this order:

1. A built-in table of released Claude models, keyed by their dated ids. No extra permission, no network call.
2. Bedrock itself, via ListInferenceProfiles then ListFoundationModels, for anything the table does not hold. This is the path that needs the two List actions in the guide's policy; the answer is cached per region, so it costs one lookup rather than one per request, and it can only ever resolve to a model your account can reach.
3. Unchanged, when neither resolves it. A Bedrock id sent directly is always forwarded exactly as written.

Bedrock names its newer models without a date, so claude-opus-5 matches anthropic.claude-opus-5 directly. For an older family that Bedrock publishes only as dated snapshots, an undated id names the model rather than a snapshot, and from v1.10.269 it resolves to the newest published snapshot: claude-sonnet-4-5 reaches claude-sonnet-4-5-20250929-v1:0. Newest wins rather than first because AWS returns these listings in no guaranteed order, and first-match would leave the same request served by a different snapshot from one region or account to the next. On earlier releases that form does not resolve, so send the dated id or set a model alias.

The cross-region inference-profile prefix comes from the provider's configured region (Claude 4 and newer are profile-only in most regions, which is what makes the prefix necessary):

Configured region	Prefix
us-*	us.
eu-*	eu.
ap-*	apac.
ca-*	ca.

Discovery is not limited to that prefix: where a model is published only under the cross-region global. profile, it returns that instead. Models from other families keep their Bedrock ids, since only Claude has a canonical id to convert from.

Claude 5 availability by region

No undated id is in the built-in table, so claude-opus-5, claude-sonnet-5, and claude-fable-5 resolve only through discovery, and availability differs by region in a way a fixed mapping could not handle:

Region family	What discovery finds
us-*	All three under the us. prefix
eu-*	Opus and sonnet under eu.; fable only as global.anthropic.claude-fable-5
ap-*	None carry apac.; all three come from global.

To pin an exact id instead, map the short name with a model alias, which is applied before the request reaches the provider and so takes precedence over all resolution above. To list what your account can use as an alias target:

aws bedrock list-inference-profiles --region <region> \
  --query 'inferenceProfileSummaries[].inferenceProfileId' --output text

Static keys and cross-account access

Use a static access-key pair when the gateway has no AWS workload identity (a Cloudflare Worker has no access to AWS workload metadata), or when Bedrock lives in a different AWS account than the gateway, which a workload role cannot reach. Create an IAM user in the account that holds the model access, attach the guide's policy, and mint a key:

aws iam create-user --user-name anyray-bedrock
aws iam attach-user-policy --user-name anyray-bedrock --policy-arn "$POLICY_ARN"
aws iam create-access-key --user-name anyray-bedrock

Paste the pair into the provider config (guide, step 2). The key is long-lived, so it goes on your normal rotation schedule.

A new IAM user needs its own use-case approval

Bedrock evaluates the Anthropic use-case attestation per principal, not per account: a freshly created IAM user gets ResourceNotFoundException asking for the use-case form, even in an account that already invokes Claude successfully. Read the account's form as an admin with bedrock get-use-case-for-model-access, then submit it as the new user with bedrock put-use-case-for-model-access. The BedrockUseCaseAttestation statement in the guide's policy is what permits that; without it the failure arrives later and elsewhere, as AccessDenied on Converse reading "not authorized to perform the required AWS Marketplace actions".

The CloudFormation role

The stack creates the role with the logical id TaskRole. Find its generated name with aws cloudformation describe-stack-resources --stack-name <stack> --logical-resource-id TaskRole, then attach the policy with aws iam attach-role-policy.

Attach a managed policy rather than adding an inline one. The template declares the role's inline policies, so CloudFormation reconciles that list on every stack update and can remove an inline policy you added by hand. A managed-policy attachment is not declared in the template, so it survives; it appears in drift detection, which is expected. One TaskRole backs all three services in the stack, and only the gateway calls Bedrock; scope the policy's Resource if you want to narrow that.

VPC and private subnets

The CloudFormation stack needs no networking change: its tasks run with their own outbound access to AWS, and that holds when the load balancer is internal as well, because the tasks reach Bedrock directly rather than through the load balancer. A gateway in private subnets needs either a NAT gateway or VPC interface endpoints for com.amazonaws.<region>.bedrock-runtime and com.amazonaws.<region>.bedrock. VPC endpoints are regional, so a Bedrock region different from the gateway's own region cannot use one and needs ordinary internet egress.