Migrating from v1.x to v2.x

This guide will help you migrate your NTC modules from version 1.x to 2.x. The v2 release includes significant improvements and breaking changes that require careful planning.

What's New in v2

🚀 Major Features

1. AWS Terraform Provider v6 Support

   • Optional region attribute on the root module (falls back to provider default)
   • Single provider configuration for multiple regions
   • Simplified provider aliasing

2. AWS European Sovereign Cloud (ESC) Compatibility

   • Full support for sovereign cloud partitions
   • Region-aware resource deployment
   • Partition-specific configurations

3. Simplified Module Architecture

   • Consolidated module calls (fewer separate modules)
   • Reduced complexity in multi-region deployments
   • Easier maintenance

💥 Breaking Changes

Important

v2.x includes breaking changes that require updates to your Terraform configurations. You cannot simply change the version number - migration steps are required.

Change	Impact	Action Required
AWS Provider v6	Provider configuration changes	Update required_providers block
New region attribute	Module configuration	Add region parameter to modules (optional but recommended)
Consolidated modules	Module structure changes	Refactor module calls (see module-specific guides)
State resource paths	Terraform state	Apply state migrations using moved blocks

Migration Strategy

Option 1: All at Once (Recommended for Small Deployments)

Upgrade all NTC modules in a single migration window.

Pros:

• ✅ Single migration effort
• ✅ Consistent versioning across all modules

Cons:

• ⚠️ Requires more testing upfront
• ⚠️ Larger blast radius if issues occur

Option 2: Gradual Migration (Recommended for Large Deployments)

Upgrade modules one by one over time.

Pros:

• ✅ Lower risk per migration
• ✅ Easier rollback if needed
• ✅ Flexible timeline

Cons:

• ⚠️ Mixed v1/v2 environment during transition
• ⚠️ May require multiple AWS Provider versions across repositories

Migration Order Recommendation

For gradual migration, follow this order to minimize dependencies:

1. NTC Parameters
2. NTC Organizations + NTC Guardrail Templates
3. NTC Account Factory + NTC Account Baseline Templates, NTC Account Lifecycle Templates
4. NTC Identity Center
5. Security modules (NTC Log Archive, NTC Security Tooling)
6. Connectivity modules (NTC VPC, NTC Core Network, NTC IPAM, NTC Route53)

Prerequisites

Before starting the migration:

1. Terraform Version Requirements

terraform {
  required_version = "1.11.1" # replace with your Terraform/OpenTofu version
  
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"
    }
  }
}

2. Backup Your Terraform State

# For remote state (S3)
aws s3 cp s3://your-bucket/path/to/terraform.tfstate ./terraform.tfstate.backup

# For remote state (Spacelift etc.)
# Create a state version snapshot via UI or API

3. Test Environment

Test First

Never migrate production directly. Always test in a non-production environment first. 
Always read the plan stage carefully and check if any unexpected changes appear.

Recommended testing approach:

1. Perform the migration in a test environment or on non-productive accounts.
2. Document any issues
3. Apply learnings to production migration

Migration Steps

Critical: Upgrade AWS Provider to v6 Before Upgrading NTC Modules

The recommended migration approach is a two-phase process:

1. Phase 1 — Upgrade the AWS provider from v5 to v6 while keeping NTC modules at v1.x, then apply.
2. Phase 2 — Upgrade NTC modules from v1.x to v2.x, then apply.

Why this matters: AWS provider v6 introduces a region attribute on resources. When you apply with the v6 provider while still on NTC v1.x, Terraform writes the region attribute into the state for all existing resources. This is especially important for resources managed through non-default (aliased) providers — without this intermediate step, those resources may show as needing recreation during the NTC v2 upgrade because their state lacks the region attribute.

Do NOT skip Phase 1. Upgrading the provider and NTC modules simultaneously increases the risk of unnecessary resource recreation.

Step 1: Upgrade AWS Provider to v6 (Keep NTC at v1.x)

Update only the provider version constraint. Do not change NTC module versions yet.

v1.x (Before)

terraform {
  required_version = "1.11.1" # replace with your Terraform/OpenTofu version

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "eu-central-1"
}

provider "aws" {
  alias  = "euc2"
  region = "eu-central-2"
}

provider "aws" {
  alias  = "euc2"
  region = "eu-west-1"
}

provider "aws" {
  alias  = "use1"
  region = "us-east-1"
}

After Phase 1 (Provider v6, NTC v1.x)

terraform {
  required_version = "1.11.1" # replace with your Terraform/OpenTofu version

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"  # ← Updated to v6
    }
  }
}

# Keep all existing provider aliases — do NOT remove them yet
provider "aws" {
  region = "eu-central-1"
}

provider "aws" {
  alias  = "euc2"
  region = "eu-central-2"
}

provider "aws" {
  alias  = "euw1"
  region = "eu-west-1"
}

provider "aws" {
  alias  = "use1"
  region = "us-east-1"
}

Step 2: Apply the Provider Upgrade

Initialize and apply with the new provider version. This writes the region attribute into the Terraform state for all existing resources.

terraform init -upgrade
terraform plan

Expected plan output:

• ✅ In-place updates adding the region attribute to existing resources
• ❌ NO resource recreations — if you see any, investigate before applying

terraform apply

After this step, your state contains the region attribute for all resources, making the subsequent NTC v2 upgrade safe.

Step 3: Update Module Versions

Now upgrade NTC module source references from v1.x to v2.x:

# Before
module "ntc_organizations" {
  source = "github.com/nuvibit-terraform-collection/terraform-aws-ntc-organizations?ref=1.6.0"
  # ...
}

# After
module "ntc_organizations" {
  source = "github.com/nuvibit-terraform-collection/terraform-aws-ntc-organizations?ref=2.0.0"
  # ...
}

Step 4: Simplify Provider Configuration

With NTC v2 modules handling regions internally, you can now remove unnecessary provider aliases:

terraform {
  required_version = "1.11.1" # replace with your Terraform/OpenTofu version

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"
    }
  }
}

# Default provider region is used as fall back if region input is omitted
provider "aws" {
  region = "eu-central-1"
}

# Regional providers still needed for some exceptions
# but modules now handle regions internally
provider "aws" {
  alias  = "use1"
  region = "us-east-1"
}

Step 5: Add Region Parameter (Optional)

Most v2 modules accept an optional region parameter. If omitted, the module falls back to the provider's default region:

module "ntc_organizations" {
  source = "github.com/nuvibit-terraform-collection/terraform-aws-ntc-organizations?ref=2.0.0"
  
  region = "eu-central-1"  # Optional: Explicitly set region (recommended for clarity)
  
  # Existing configuration...
  service_access_principals = [...]
  organizational_unit_paths = [...]
}

Step 6: Refactor Module Calls (Module-Specific)

Some modules have structural changes. See module-specific guides:

• NTC Organizations Migration - Significant changes
• More module guides coming soon...

Step 7: Apply State Migrations

Use Terraform's moved blocks to migrate state without recreating resources:

# Example: ntc-organizations state migration
moved {
  from = module.ntc_delegated_admins_euc1.aws_organizations_delegated_administrator.example["config.amazonaws.com"]
  to   = module.ntc_organizations.module.admin_delegations.aws_organizations_delegated_administrator.example["config.amazonaws.com"]
}

See module-specific guides for complete state migration blocks.

Step 8: Plan and Review

terraform init -upgrade
terraform plan

Review the plan carefully:

• ✅ Expected: Resource moves, in-place updates
• ⚠️ Partially Expected: For some refactoring cases resources will get recreated (investigate before applying)
• ❌ Unexpected: Resource deletions (investigate before applying)

Step 9: Apply Changes

terraform apply

Monitor the apply output for any errors.

Step 10: Validate

After migration:

1. ✅ Verify resources are functioning
2. ✅ Check AWS Console for resource state
3. ✅ Run integration tests (if available)
4. ✅ Verify logging and monitoring

Module-Specific Migration Guides

Each module may have unique migration requirements. Select your module:

• NTC Organizations - Consolidated admin delegations & service quotas
• More modules coming soon...

Need Help?

If you encounter issues during migration:

1. 📚 Check the Troubleshooting Guide
2. 📖 Review module-specific migration guides
3. 💬 Contact NTC Support via your usual channels
4. 🔍 Search existing issues in module repositories

---

Next Steps:

• Review Prerequisites in detail
• Start with the NTC Organizations migration guide