Architecture Decisions

ADR-002: Terraform AWS Provider v6 Migration

Options for migrating from AWS Terraform provider v5 to v6 to support Bedrock AgentCore resources.

RFC

ADR-002: Terraform AWS Provider v6.x Migration

Status: Pending
Date: 2026-02-08
Blocked by: maxcolchon AgentCore deployment timeline

Context

The Ontopix infrastructure currently uses the AWS Terraform provider ~> 5.0 (pinned in global/main.tf). The maxcolchon project needs to deploy an AI support agent to Amazon Bedrock AgentCore Runtime, which requires ECR (addressed in ADR-001) and AgentCore Terraform resources.

AgentCore resources (aws_bedrockagentcore_*) are only available in provider v6.x (milestone v6.18.0). They do not exist in the 5.x line.

AgentCore resources available in v6.x

Resource	Status
`aws_bedrockagentcore_agent_runtime`	Merged
`aws_bedrockagentcore_runtime_endpoint`	Merged
`aws_bedrockagentcore_api_key_credential_provider`	Merged
`aws_bedrockagentcore_gateway_target`	Merged
`aws_bedrockagentcore_memory`	Merged
`aws_bedrockagentcore_gateway`	Available
`aws_bedrockagentcore_browser`	Pending
`aws_bedrockagentcore_code_interpreter`	Pending
`aws_bedrockagentcore_oauth2_credential_provider`	Pending

Tracking issue: https://github.com/hashicorp/terraform-provider-aws/issues/43424

Decision

To be decided. Options:

Option A: Upgrade global infra to v6.x

Change ~> 5.0 to ~> 6.0 in global/main.tf
All modules (Route53, IAM, CodeArtifact, ECR, cost-alerts) move to v6.x
Pros: single provider version, simplest long-term
Cons: major version may have breaking changes affecting existing resources; requires careful terraform plan review
Risk: v6.x breaking changes could force refactoring of existing modules

Option B: AgentCore in per-project Terraform only

Keep global infra on ~> 5.0
maxcolchon project uses ~> 6.0 in its own Terraform (where it also creates ECR repos per ADR-001)
Pros: no risk to global infra, isolated migration
Cons: split provider versions across the organization, eventual migration still needed

Option C: Upgrade when stable

Wait until AgentCore resources are fully GA and v6.x is mature
Upgrade everything at once with a dedicated migration PR
Pros: least risk, most stable
Cons: blocks AgentCore deployment until then

Migration steps (when decided)

Review the v6.0 upgrade guide for breaking changes
Update global/main.tf: change version = "~> 5.0" to version = "~> 6.0"
Run terraform init -upgrade
Run terraform plan — carefully review for unexpected diffs or resource recreation
Fix any breaking changes in existing modules
Commit updated .terraform.lock.hcl
Apply and verify

References

Terraform AWS Provider v6 upgrade guide
AgentCore support issue #43424
ADR-001: ECR hybrid management — ECR repos are per-project, so AgentCore Terraform could live there too (favors Option B)

ADR-001: Hybrid ECR Management

Architecture decision for managing ECR with central OIDC roles and per-project repositories.

ADR-003: GitHub Actions OIDC Trust Tier Model

Three-tier OIDC trust model for GitHub Actions roles — CI, Deploy, and Release.