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

Step 1: Update Provider Configuration

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"
}

v2.x (After)

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 2: Update Module Versions

Change 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 3: 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 4: 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 5: 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 6: 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 7: Apply Changes

terraform apply

Monitor the apply output for any errors.

Step 8: 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