Azure APIM v2 vs Classic: What Changed and What Breaks

In this article

• What Actually Changed
• The Networking Model Changed Completely
• Features That Are Missing or Different
• What Breaks in Terraform
• A Practical Migration Approach
• 1. Inventory and Impact Assessment
• 2. Parallel Deployment
• 3. Traffic Cutover
• 4. Update Your IaC
• Common Pitfalls We See
• Quick Decision Guide
• Should You Migrate Now?
• The Bottom Line

If you manage APIs on Azure, you have probably seen the writing on the wall. Microsoft is moving API Management to a new platform, and Microsoft is investing heavily in v2, while classic tiers remain supported for now. The new StandardV2 and BasicV2 tiers promise faster provisioning, better scaling, and a simplified networking model.

That all sounds great on paper. In practice, the migration from classic to v2 isn’t a simple SKU swap. You cannot migrate an existing classic instance to v2 in-place; you need to deploy a new v2 instance and move your configuration over. There are meaningful differences in networking, feature availability, and Terraform resource behaviour that can break your infrastructure if you aren’t prepared.

Note: Microsoft also released a Premium v2 tier (now GA), which adds VNet injection, availability zones, workspaces, and scaling up to 30 units. If you need VNet injection (not just VNet integration), Premium v2 is your path forward. One important caveat: VNet injection in Premium v2 is currently create-time only. You cannot switch between injection and integration after deployment, so this is a decision you make at provisioning time.

We have worked through v2 migrations with clients. Here is what we learned.

What Actually Changed

The v2 tiers aren’t just a pricing refresh. Microsoft rebuilt the underlying compute platform. A StandardV2 instance deploys in minutes instead of the 30-45 minutes you are used to with classic Premium. Scale units are gone, replaced by a more granular capacity model. VNet integration replaces the old VNet injection approach. Availability zone support remains a Premium-tier feature (classic Premium and Premium v2 only); StandardV2 does not include AZ support.

Genuine improvements across the board. But the details matter.

Azure docs: APIM v2 tier overview · Compare APIM tiers

The Networking Model Changed Completely

Most teams get tripped up here. Classic Premium APIM supported VNet injection: the APIM instance got a NIC in your VNet subnet, with a private IP, and you could control traffic with NSGs and route tables just like any other Azure resource.

StandardV2 drops VNet injection entirely. Instead, it uses VNet integration, conceptually closer to how App Service VNet integration works. In practice, that means your APIM gets a path into your private network for backend calls, but the gateway itself remains publicly accessible unless you put it behind a Private Endpoint. Note that Private Endpoint on APIM only supports inbound traffic to the Gateway endpoint; it does not cover self-hosted gateways or workspace gateways. Premium v2 brings back simplified VNet injection for full network isolation, but at a higher price point than StandardV2.

With classic VNet injection in internal mode, your APIM got a private IP on your VNet for free. StandardV2 plus an inbound Private Endpoint can provide private inbound access, and together with outbound VNet integration can support end-to-end private client/backend flows. But it is a different deployment model from classic internal VNet injection, with different networking behaviour and operational characteristics. Subnet requirements changed too: v2 requires a dedicated subnet delegated to Microsoft.ApiManagement/service, with different sizing requirements than classic. And the required NSG rules for v2 subnets differ from classic, so copying your existing NSG rules will break things.

If you run APIM in internal mode behind an Application Gateway (a very common pattern), expect to redesign the network path entirely.

Azure docs: VNet integration for APIM v2 · Private Endpoints for APIM · VNet reference (NSG rules)

Features That Are Missing or Different

The official feature comparison is the authoritative source. Here is a simplified view of the features that matter most for migration decisions:

Feature	Classic Developer	Classic Premium	BasicV2	StandardV2	Premium v2
Production SLA	No	Yes	Yes	Yes	Yes
VNet injection	Yes	Yes	No	No	Yes (create-time only)
Outbound VNet integration	No	No	No	Yes	Yes
Inbound Private Endpoint	Yes	Yes	No	Yes	Yes
Multi-region	No	Yes	No	No	No
Self-hosted gateway	Yes (1 node)	Yes	No	No	No
Availability zones	No	Yes	No	No	Yes
Workspaces	No	No	No	No	Yes
Backup and restore	Yes	Yes	No	No	No
Capacity model	1 unit (fixed)	Scale units (up to 12)	Units (up to 5)	Units (up to 10)	Units (up to 30)
Deployment time	30-45 min	30-45 min	5-10 min	5-10 min	5-10 min

Key observations from this matrix:

Classic Premium is still the only tier with multi-region deployment. If you need multi-region today, there is no v2 alternative yet.

Classic Developer is the cheapest tier with VNet injection. For non-production environments that need internal-mode APIM inside a VNet, it remains a valid choice despite having no SLA.

BasicV2 has the fewest networking features of any v2 tier: no VNet injection, no VNet integration, and no inbound Private Endpoint. Teams that assume BasicV2 can replace classic Developer for secure dev/test will find it cannot if private networking is required.

StandardV2 gives you outbound VNet integration and inbound Private Endpoint, but the gateway, management plane, and developer portal remain publicly accessible unless you configure Private Endpoint and then disable public network access. It is a different deployment model from classic internal mode.

Premium v2 brings back VNet injection, but with a create-time constraint: you choose injection or integration at provisioning and cannot switch afterwards. It also does not yet support multi-region or self-hosted gateway.

Pricing varies by region and currency. V2 tiers also include bundled API request volumes with overage pricing and scale-out unit costs, so the base SKU price is not the full picture. Total solution cost should include surrounding networking components (Private Endpoint, private DNS, Application Gateway or Front Door, and firewall depending on your pattern).

Check the official feature comparison before planning your migration. Microsoft is closing gaps regularly, but your timeline might not align with theirs.

Azure docs: Feature comparison across tiers · APIM migration guide

What Breaks in Terraform

If you manage APIM with Terraform (and you should), the v2 migration introduces several changes to the azurerm_api_management resource:

# Classic Premium with VNet injection
resource "azurerm_api_management" "classic" {
  name                = "apim-contoso-prd"
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name
  publisher_name      = "Contoso"
  publisher_email     = "api@contoso.com"
  sku_name            = "Premium_1"

  virtual_network_type = "Internal"

  virtual_network_configuration {
    subnet_id = azurerm_subnet.apim.id
  }
}

# StandardV2 with VNet integration + Private Endpoint
resource "azurerm_api_management" "v2" {
  name                = "apim-contoso-prd"
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name
  publisher_name      = "Contoso"
  publisher_email     = "api@contoso.com"
  sku_name            = "StandardV2_1"

  virtual_network_type = "None"  # VNet integration is separate

  # VNet integration handled via subnet delegation
  # Private Endpoint handled via azurerm_private_endpoint
}

Watch for several Terraform gotchas here.

First, the sku_name format changed: Premium_1 becomes StandardV2_1, and the capacity number works differently. Second, the virtual_network_type and virtual_network_configuration blocks no longer apply for v2 networking. VNet integration is configured differently, and inbound private access requires a separate azurerm_private_endpoint resource. Third, you cannot change sku_name from Premium_1 to StandardV2_1 on an existing resource. Terraform treats it as a destroy-and-recreate, so you need a migration strategy with parallel deployment. Finally, the v2 subnet needs Microsoft.ApiManagement/service delegation added to your azurerm_subnet resource.

If you use Terraform modules for APIM, expect to refactor them significantly. The resource inputs look similar enough to seem compatible but differ enough to fail in surprising ways.

Azure docs: Migrate to APIM v2 platform · Terraform azurerm_api_management

A Practical Migration Approach

Microsoft does not support in-place migration from classic to v2 tiers. You have to deploy a new v2 instance and move your APIs, policies, and backends over. Here is an approach that works:

1. Inventory and Impact Assessment

Before touching infrastructure, document all your APIs and their backends, paying special attention to which backends live in private VNets (those are the ones affected by the networking change). Map out your current networking topology: VNet injection mode (internal/external), Application Gateway frontends, DNS configuration. Identify all APIM-related resources in your Terraform state and their dependencies. And figure out who calls your APIs and what changes they will see during migration.

2. Parallel Deployment

Don’t attempt an in-place migration. Deploy a new v2 instance alongside the classic one:

• Deploy StandardV2 with VNet integration and Private Endpoint
• Configure the same APIs, policies, and backends on the v2 instance
• Use Terraform, ARM/Bicep export, or Azure API Center to replicate configuration (note: the older APIM DevOps Resource Kit was archived by Microsoft in Feb 2024)
• Test thoroughly with private backend connectivity

3. Traffic Cutover

Once the v2 instance is validated:

• Update DNS records or Application Gateway backend pools to point to the v2 instance
• Keep the classic instance running in parallel for rollback
• Monitor error rates and latency for 48-72 hours
• Decommission the classic instance only after validation

4. Update Your IaC

After cutover, update your Terraform to reflect the new resource structure. Remove the classic resource definition, add Private Endpoint resources, update subnet configurations.

Common Pitfalls We See

DNS resolution inside the VNet catches people first. With classic internal mode, APIM’s private IP was in your VNet and DNS just worked. With v2 and Private Endpoint, you need Private DNS zones configured correctly for azure-api.net resolution. Miss this and your backends can’t reach the APIM gateway.

Application Gateway integration is another one. If you front APIM with App Gateway (common for WAF and certificate management), the backend pool configuration changes. Classic used the VNet-injected private IP. V2 with Private Endpoint uses a different IP that resolves through Private DNS.

Managed identity permissions trip up teams that forget the new v2 instance gets a new identity. If your classic APIM uses managed identity to access Key Vault, storage, or other resources, update your RBAC assignments before cutover.

Finally, test your custom policy expressions even though most policies work identically. We have seen edge cases with context.Deployment properties returning different values on v2.

Azure docs: Private DNS zones · APIM with Application Gateway

Quick Decision Guide

If you are deciding between classic and v2 today, here is how to think about it based on your workload pattern.

Internal APIs behind a VNet. If your APIs serve internal consumers and need full network isolation, Premium v2 is the cleanest path because it supports VNet injection natively. If Premium v2 pricing is too high, StandardV2 with a Private Endpoint gives you inbound private access, but outbound calls to backends require VNet integration rather than full injection. Evaluate whether that distinction matters for your traffic flow.

Public-facing APIs that need WAF protection. Put Azure Front Door in front of APIM StandardV2. Front Door handles global load balancing, caching, and WAF, while APIM handles API policies and rate limiting. Application Gateway is an alternative if you need regional WAF only, but Front Door is the better default for public APIs. See APIM vs Front Door vs Application Gateway for a deeper comparison of when to use each.

Cost-sensitive workloads with simple API needs. StandardV2 is significantly cheaper than Premium (classic or v2) and deploys in minutes. If you do not need VNet injection, multi-region, or self-hosted gateways, StandardV2 covers the common cases well.

Multi-region requirement. Stay on classic Premium for now. Neither StandardV2 nor Premium v2 supports multi-region deployment yet. Microsoft will likely add it, but there is no announced date. Do not architect around a feature that does not exist.

New production APIM deployments. Default to v2. Pick StandardV2 or Premium v2 based on your networking requirements and start with the modern architecture from day one. For non-production environments that need the classic internal/external VNet deployment model at the lowest cost, the classic Developer tier can still be a rational exception: it supports VNet injection, costs significantly less than any v2 tier, but has no SLA and should never be treated as a production-equivalent alternative.

Should You Migrate Now?

It depends on your constraints. If you need multi-region, wait: StandardV2 doesn’t support it yet. If you are on classic Standard or Basic, migrate soon because these tiers are already deprecated and Microsoft is pushing hard. Premium with VNet injection requires the most careful planning since the networking redesign is the biggest effort; start with a proof of concept in a non-production environment. For new production instances, default to v2. The classic Developer tier remains a valid option for non-production environments that need classic VNet deployment at the lowest cost.

One important distinction: the stv1 platform retirement (completed in 2024) is a separate thing from moving to v2 tiers. The stv1-to-stv2 migration was a compute platform upgrade for classic tiers (Developer, Basic, Standard, Premium). Moving to the v2 tiers (BasicV2, StandardV2, Premium v2) is a different decision with different trade-offs. Microsoft hasn’t announced retirement dates for the classic tiers themselves, but the direction is clear.

Azure docs: stv1 platform retirement · Migration guide

The Bottom Line

The move to APIM v2 is the right direction. Faster deployments, better scaling, and a cleaner networking model are all wins. But it isn’t a drop-in replacement, especially for enterprises running APIM in internal mode with VNet injection.

Plan the migration as an infrastructure project, not a SKU change. Inventory your current setup, deploy in parallel, validate thoroughly, and update your IaC after cutover. Block out two to three weeks for the full cycle: inventory, parallel deploy, validation, and cutover. Start with your lowest-risk environment, prove out the networking path, and work up from there.