Terraform Provider Upgrade Agent Skill

# Step 1: Get current and latest versions
mcp_terraform_get_latest_provider_version(namespace="hashicorp", name="azurerm")
# Current: 3.117.0, Latest: 4.51.0 → Major version change (likely breaking)
# Current: 3.117.0, Latest: 3.118.0 → Minor version change (likely non-breaking)
# Current: 3.117.0, Latest: 3.117.1 → Patch version (non-breaking)

# Step 2: Discover available guide names
mcp_terraform_get_provider_capabilities(namespace="hashicorp", name="azurerm", version="latest")

# Step 3: Get the provider_doc_id for the upgrade guide
mcp_terraform_search_providers(provider_namespace="hashicorp", provider_name="azurerm", service_slug="4.0-upgrade-guide", provider_document_type="guides", provider_version="latest")

# Step 4: Fetch the upgrade guide content
mcp_terraform_get_provider_details(provider_doc_id="<id-from-search_providers>")

# Search for all Terraform files
find . -name "*.tf"

# Search for provider version constraints
grep -r "required_providers" --include="*.tf"
grep -r "version.*=" --include="versions.tf"

mcp_terraform_get_latest_provider_version(namespace="hashicorp", name="azurerm")

mcp_terraform_get_provider_capabilities(
  namespace="hashicorp",
  name="azurerm",
  version="latest"
)

mcp_terraform_search_providers(
  provider_namespace="hashicorp",
  provider_name="azurerm",
  service_slug="4.0-upgrade-guide",
  provider_document_type="guides",
  provider_version="latest"
)

mcp_terraform_get_provider_details(
  provider_doc_id="<id-from-search_providers>"
)

# Generate a single regex alternation from ALL removed resources found in the upgrade guide
# Replace the values inside the parentheses with the actual list from the guide
REMOVED_RESOURCES=(
  "old_resource_type_1"
  "old_resource_type_2"
  "old_resource_type_3"
  # ... add every resource listed as removed in the upgrade guide
)

# Build a regex pattern and search all .tf files at once
PATTERN=$(IFS="|"; echo "${REMOVED_RESOURCES[*]}")
grep -rE "($PATTERN)" --include="*.tf" -l   # list affected files
grep -rE "($PATTERN)" --include="*.tf"       # show full context

# Alternatively, search for any resource block whose type begins with the
# provider prefix (e.g. azurerm_) and cross-reference against the removed list
grep -rE '^\s*resource\s+"<provider_prefix>[^"]+"' --include="*.tf"

# Check for removed data source types
grep -rE 'data\s+"(old_data_source_1|old_data_source_2)"' --include="*.tf"

# Check for deprecated provider block arguments
grep -rE '(deprecated_argument_1|deprecated_argument_2)\s*=' --include="*.tf" -l

mcp_terraform_search_providers(
  provider_namespace="hashicorp",
  provider_name="azurerm",
  service_slug="sql_server",
  provider_document_type="resources",
  provider_version="3.117.1"
)
mcp_terraform_get_provider_details(provider_doc_id="<id-from-search>")

mcp_terraform_search_providers(
  provider_namespace="hashicorp",
  provider_name="azurerm",
  service_slug="mssql_server",
  provider_document_type="resources",
  provider_version="latest"
)
mcp_terraform_get_provider_details(provider_doc_id="<id-from-search>")

# Before
resource "azurerm_sql_server" "sql_server" {
  name                         = "example-sqlserver"
  resource_group_name          = azurerm_resource_group.rg.name
  location                     = azurerm_resource_group.rg.location
  version                      = "12.0"
  administrator_login          = "sqladmin"
  administrator_login_password = var.sql_password
}

# After
resource "azurerm_mssql_server" "sql_server" {
  name                         = "example-sqlserver"
  resource_group_name          = azurerm_resource_group.rg.name
  location                     = azurerm_resource_group.rg.location
  version                      = "12.0"
  administrator_login          = "sqladmin"
  administrator_login_password = var.sql_password
}

moved {
  from = azurerm_sql_server.sql_server
  to   = azurerm_mssql_server.sql_server
}

# Firewall rule arguments changed from name-based to ID-based
# Before (v3.x)
resource "azurerm_sql_firewall_rule" "allow_azure" {
  name                = "allow-azure-services"
  resource_group_name = azurerm_resource_group.rg.name
  server_name         = azurerm_sql_server.sql_server.name
  start_ip_address    = "0.0.0.0"
  end_ip_address      = "0.0.0.0"
}

# After (v4.x)
resource "azurerm_mssql_firewall_rule" "allow_azure" {
  name             = "allow-azure-services"
  server_id        = azurerm_mssql_server.sql_server.id  # Changed from name to ID
  start_ip_address = "0.0.0.0"
  end_ip_address   = "0.0.0.0"
}

moved {
  from = azurerm_sql_firewall_rule.allow_azure
  to   = azurerm_mssql_firewall_rule.allow_azure
}

# Search for resources that reference the migrated resource
grep -r "azurerm_sql_server.sql_server" --include="*.tf"

# Before
provider "azurerm" {
  features {}
  skip_provider_registration = true  # Deprecated
}

# After
provider "azurerm" {
  features {}
  resource_provider_registrations = "none"  # Modern equivalent
}

terraform {
  required_version = ">= 1.5.0"
  
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "4.51.0"  # Updated from 3.117.1
    }
  }
}

your-terraform-repo/
├── TERRAFORM_UPGRADE_BREAKING_CHANGES.md  ← Place here
├── infra/
├── .github/
└── README.md

# Terraform Provider Upgrade: AzureRM v3.117.1 → v4.51.0

**Date:** 2026-01-27

## Summary

Upgraded HashiCorp AzureRM provider from v3.117.1 to v4.51.0. This major version upgrade included automatic migration of removed SQL resources to their modern MSSQL equivalents.

## What Changed

- Updated `required_providers` version constraint to `4.51.0`
- Migrated removed resources: `azurerm_sql_*` → `azurerm_mssql_*`
- Replaced deprecated `skip_provider_registration` with `resource_provider_registrations`
- Updated argument references from name-based to ID-based

## Breaking Changes Handled

### ✅ Removed Resources Migrated

**1. azurerm_sql_server → azurerm_mssql_server**
- **Files Modified:** `infra/modules/database/main.tf`
- **Changes Applied:**
  - Updated resource type
  - Added `moved` block for automatic state migration
  - All arguments remain compatible
- **Argument Mappings:** No changes required (schema compatible)
- **Default Values:** No new default value changes
- **Documentation:** [azurerm_mssql_server](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/mssql_server)

**2. azurerm_sql_firewall_rule → azurerm_mssql_firewall_rule**
- **Files Modified:** `infra/modules/database/main.tf`
- **Changes Applied:**
  - Updated resource type
  - Changed `server_name` argument to `server_id`
  - Updated reference from `.name` to `.id`
  - Added `moved` block for automatic state migration
- **Argument Mappings:**
  - `resource_group_name` (removed) + `server_name` → `server_id`
  - Now uses: `azurerm_mssql_server.sql_server.id`
- **Default Values:** No new default value changes
- **Documentation:** [azurerm_mssql_firewall_rule](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/mssql_firewall_rule)

**State Migration:** Terraform will automatically migrate state using `moved` blocks on next plan/apply.

## Notes

- All changes are backward compatible with existing state
- `moved` blocks enable automatic state migration
- No manual `terraform state mv` commands required
- Provider block retained with updated `resource_provider_registrations` argument

## Next Steps

1. **Commit these changes** to a feature branch
2. **Run your Terraform workflow** via CI/CD pipeline to validate
3. **Review plan output** to confirm state migrations
4. **Verify no unexpected changes** before merging

## References

- [AzureRM Provider 4.0 Upgrade Guide](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/4.0-upgrade-guide)
- [AzureRM Provider v4.51.0 Release Notes](https://github.com/hashicorp/terraform-provider-azurerm/releases/tag/v4.51.0)
- [Terraform Moved Blocks](https://developer.hashicorp.com/terraform/language/modules/develop/refactoring)
- [Resource Provider Registrations](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/4.0-upgrade-guide#resource-provider-registrations)