Skip to main content

ADR-003: Provider Version Constraints

Status: Accepted (Amended 2026-02-27) Date: 2026-02-25 Deciders: @cloud-architect, @product-owner, HITL/Manager

Context​

The three module domains currently have CONFLICTING provider constraints:

ModuleCurrent ConstraintTerraform VersionNotes
iam-identity-center~> 6.0 (awscc ~> 1.0)>= 1.14.0Uses AWS provider v6 + awscc
aws-ecs-fargate>= 5.0, < 6.0>= 1.7EXPLICITLY blocks v6
webNot yet definedTBDNew module

The conflict is concrete and documented in aws-ecs-fargate/versions.tf:

version = ">= 5.0, < 6.0" # terraform-aws-modules/ecs v5.12.1 incompatible with AWS provider v6

Root cause: terraform-aws-modules/ecs v5.x uses aws_ecs_service resource schema that changed in hashicorp/aws v6.0. The terraform-aws-modules/ecs v7.x resolves this and is compatible with hashicorp/aws v6. (https://github.com/terraform-aws-modules/terraform-aws-ecs/releases)

Key facts:

  • terraform-aws-modules/ecs v7.3.1 is referenced in the manager brief as the wrapper target
  • terraform-aws-modules/ecs v7.x requires hashicorp/aws >= 5.95 (release notes confirm)
  • AWS provider v6.0.0 was released 2025-09-04; v6.x is the current major
  • >= 5.0 without upper bound means consumers could get v6 unexpectedly (semver major = breaking)
  • >= 5.0, < 6.0 is overly restrictive now that v7.x ECS module resolves the incompatibility

Decision​

Adopt >= 6.28, < 7.0 as the AWS provider constraint for all three modules.

Rationale:

  1. >= 5.95 ensures terraform-aws-modules/ecs v7.x compatibility (v7 requires 5.95+)
  2. < 7.0 caps at the next major (does not yet exist, but signals consumer intent)
  3. This is NOT ~> 6.0 — the tilde-rocket operator ~> allows only patch upgrades within the minor version. >= 5.95, < 7.0 allows all of 5.95.x through 6.x.y — much more permissive and appropriate for a community-published module
  4. iam-identity-center using ~> 6.0 is too restrictive — change to >= 5.95, < 7.0

awscc provider (iam-identity-center only): Keep ~> 1.0 — the awscc provider is used specifically for aws_ssoadmin_* resources that have AWSCC parity; ~> 1.0 (allows 1.x.y) is appropriate.

Terraform core version: Standardise on >= 1.11.0 across all modules.

  • 1.9.0 introduced nullable in variable blocks (used in iam-identity-center)
  • 1.6.0 introduced native test framework (terraform test)
  • 1.7.0 introduced removed blocks for clean state management
  • 1.9.0 is the lowest common denominator that unlocks all required features
  • 1.11.0 stabilized use_lockfile for S3 native state locking (see ADR-006)

Concrete versions.tf for all modules:

terraform {
  required_version = ">= 1.11.0"   # Original: >= 1.9.0; see Amendment History

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 6.28, < 7.0"   # Original: >= 5.95, < 7.0; see Amendment History
    }
  }
}

For iam-identity-center only, add:

    awscc = {
      source  = "hashicorp/awscc"
      version = ">= 1.0, < 2.0"
    }

Amendment History​

Amendment 1 (2026-02-27): Provider Version Bump​

Changed: AWS provider constraint from >= 5.95, < 7.0 to >= 6.28, < 7.0 Changed: Terraform core from >= 1.9.0 to >= 1.11.0

Rationale:

  • AWS Provider 6.28+ required for S3 conditional writes stability and ECS module v7.3.1 compatibility
  • Terraform 1.11.0 stabilized use_lockfile for S3 native state locking (ADR-006)
  • Original >= 5.95 floor was set for terraform-aws-modules/ecs v7.x minimum; actual deployment validated at 6.28+

Original rationale preserved: The >= 5.95 floor was originally chosen because terraform-aws-modules/ecs v7.x requires AWS provider >= 5.95. The bump to 6.28 narrows the window but all current deployments use 6.28+ anyway.

Consequences​

Positive​

  • All three modules can coexist in a consumer root module without provider conflicts
  • Consumers using AWS provider 5.95-6.x (majority of 2025-2026 enterprise users) are supported
  • Upper bound < 7.0 protects consumers from silent breaking changes when v7 releases

Negative​

  • Consumers locked to AWS provider < 5.95 (pre-September 2025) cannot use these modules without upgrading. In ANZ FSI context, this is acceptable; enterprises on older providers have a clear upgrade path.

Blocking Risks​

RiskProbabilityImpactMitigation
AWS provider v7.0 releases before upper bound is updated, blocking upgradesLMDependabot PR auto-created when v7 pre-release is detected; update upper bound and retest ECS module compatibility before releasing updated constraint

Alternatives Considered​

  1. ~> 5.0 (pessimistic constraint, allows 5.x): Rejected — blocks terraform-aws-modules/ecs v7.x which requires 5.95+
  2. >= 5.0 (no upper bound): Rejected — exposes consumers to AWS provider v6 breaking changes without an explicit compatibility test; violates module publishing best practices (https://developer.hashicorp.com/terraform/registry/modules/publish#requirements — "provider constraints should include an upper bound")
  3. ~> 6.0 (iam-identity-center current): Rejected — blocks 5.95-5.99 range unnecessarily; the tilde-rocket is appropriate for CONSUMER root modules, not published modules that must be composable
  • ADR-006: S3 Native Locking — S3 native state locking requires Terraform >= 1.11.0 (use_lockfile), which drove the Terraform core floor bump in Amendment 1
  • ADR-007: Upstream Dependency Strategy — Governs how upstream terraform-aws-modules version pins are reviewed and updated, including ECS v7.x which set the original 5.95+ AWS provider floor

References​

Coordination Evidence​

Consolidated from .adlc/projects/terraform-aws/ as part of ADR-001→019 SSOT consolidation (2026-02-27).