APIM STv1 to STv2 migration through Terraform

Question

Has anyone been able to migrate an existing APIM instance running on an STv1 platform to STv2 using only Terraform (manual updates through the Azure Portal are prohibited)? We can create fresh new STv2 instances, but we can't seem to find any documentation for the migration process, and our efforts (even including Hashicorp support) have been unfruitful. Some context:

• We use Developer & Premium APIM instaces injected into Internal-mode VNETs (PublicIP, Network Security Groups, API version, etc., all STv2 pre-reqs are properly covered)
• AzureRM 2.98 and 3.0 providers tested but none of them work for migrating APIM to a new subnet
• Only Terraform + Azure DevOps changes are allowed

Any inputs on a working and tested process will be much appreciated.

Thanks!

UPDATE: Here's the APIM code I'm using, it's pretty basic for my test use-case. My understanding is that after covering the STv2 requirements (which I did), updating the subnet_id to a new one should upgrade APIM as part of the subnet move, but that doesn't happen. It just does not move the instance to the new subnet, although plan shows the correct subnet update and apply finishes successfully.

´´´´

    ############ APIM Configuration ##############
    resource "azurerm_api_management" "apim" {
      depends_on           = [azurerm_public_ip.ip, azurerm_subnet_network_security_group_association.nsg2subnet]
      name                 = "apim-${var.api_management["name"]}" # prefix with apim-
      location             = var.location
      min_api_version      = "2021-01-01-preview" # min version required for STV2
      resource_group_name  = var.rg_name
      public_ip_address_id = azurerm_public_ip.ip.id
      publisher_name       = var.api_management["publisher_name"]
      publisher_email      = var.api_management["publisher_email"]
      sku_name             = var.api_management["sku_name"]
      virtual_network_type = "Internal" 
      virtual_network_configuration {
        subnet_id = var.api_management["subnet_id"]
      }
    
      tenant_access {
        enabled = var.enable_management_api_access
      }
      zones = []
    
      dynamic "additional_location" {
        for_each = var.multiregion_configs
    
        content {
          location = additional_location.value["location"]
          virtual_network_configuration {
            subnet_id = additional_location.value["subnet_id"]
          }
        }
      }
  dynamic "identity" {
    for_each = [var.identity]
    content {
      type         = identity.value["type"]
      identity_ids = identity.value["type"] == "UserAssigned" || identity.value["type"] == "SystemAssigned, UserAssigned" ? [identity.value["id"]] : null
    }
  }

  policy {
    xml_content = coalesce(var.policy, local.default_policy)
  }

  security {
    tls_rsa_with_aes128_gcm_sha256_ciphers_enabled = true
  }

  tags = local.tags

}
´´´´

Answer 1

As of now, manual intervention is required to migrate APIM STv1 to STv2 through Terraform. This migration cannot be done automatically.

Using Terraform to migrate a complex Azure API Management (APIM) instance from STv1 to STv2 platform can pose some challenges. This is especially true for Developer and Premium APIM instances that are in Internal-mode VNETs.

Understanding the Requirement & Potential challenges:

Migration of APIM from STv1 to STv2: This means modifying the APIM service's basic framework while keeping the current settings and connections intact. Direct Migration Support: A possible explanation for the challenges faced is that Terraform did not offer a straightforward way to upgrade an APIM instance from STv1 to STv2.

My terraform configuration:

provider "azurerm" {
  features {}
}

resource "azurerm_resource_group" "example" {
  name     = "demvksb1-rg"
  location = "East US"
}


resource "azurerm_api_management" "example_stv1" {
  name                = "demvksb1-apim-stv1"
  location            = azurerm_resource_group.example.location
  resource_group_name = azurerm_resource_group.example.name
  publisher_name      = "My Company"
  publisher_email     = "[email protected]"
  sku_name            = "Developer_1"  # Choose the appropriate SKU


}

Output:

The problem araised when I tried to Migrating an existing Azure API Management (APIM) instance from a Standard Tier V1 (STv1) to a Standard Tier V2 (STv2)

The problem is with this

Terraform may struggle with complex Azure migrations due to limitations in handling stateful resource transitions and specific Azure service nuances, often requiring manual interventions or supplementary scripts.

reference:

https://learn.microsoft.com/en-us/azure/api-management/migrate-stv1-to-stv2?tabs=portal

https://techcommunity.microsoft.com/t5/fasttrack-for-azure/migrating-api-management-platform-version-from-stv1-to-stv2/ba-p/3951108

https://github.com/hashicorp/terraform-provider-azurerm/issues/20939

https://github.com/MicrosoftDocs/azure-docs/issues/116427

Answer 2

As an update, Hashicorp confirmed that there is a limitation on the current APIM module that prevents it from being able to migrate APIM to a new subnet (and upgrading to stv2). They will be releasing a new patch covering this gap soon through this PR: https://github.com/hashicorp/terraform-provider-azurerm/pull/24569/files

Thanks!