Migrate APIM to compute stv2

Migrate APIM to compute stv2

Time is ticking to move your APIM services to the stv2 compute. Let’s explore a practical use case and discuss the available migration paths and considerations before executing the migration. 

Introduction

If you are running Azure API management services, surely you have noticed the following message in the Azure portal : “Support for the single-tenant v1 (STv1) platform ends on 8/31/24. Migrate instances before that date to the new platform version (STv2) for continued support and access to new features”

The message is crystal clear, we need to move our APIM to stv2 asap. To ensure a successful migration, it is important to analyze our architecture, consider customer constraints, explore possible approaches, and evaluate the risks. Let’s take a sample case and see how to approach the migration.

For more information about migration procedure check out the Microsoft documentation at the following link.

A sample case

Let’s use a sample application. I have a Chatbot app hosted on App Container Apps exposed to the outside world via Front Door. The Chatbot app consumes the OpenAI API via Azure API Management. The APIM instance is configured in internal mode, and we manage the private DNS zone to resolve the APIM internal load balancer.
The following picture shows our starting point.

Migration paths and impact analysis

There are basically two procedures depending on whether your APIM instance leverages the VNET injection or not. In this article we will only look at VNET integrated APIM because it is the most commonly used scenario by enterprises.

There are two paths: in-place migration and a parallel setup.

With the “in-place” migration option, a new stv2 APIM gateway is created side by side to the stv1. Since it is the same APIM instance, the configuration is loaded in the new gateway transparently. Once the migration is completed (meaning the stv2 gateway is up and running) Azure will automatically switch the default APIM DNS; if you are using custom domains it is up to you to manage the DNS and decide when to route the traffic to the stv2 instance. The in-place migration is triggered by simply associating APIM instance to a new subnet.

You can also opt a parallel setup by creating a brand new APIM instance (newly created gateways default to the STv2 compute) and reroute the traffic to the new instance once it is fully functional and validated.

To analyze the migration impact (on users, the solution and dependencies) we should start by asking to our customers the main questions at the following link. These questions are key to decide which migration path suits our customer the best. 

At the end, it is all boils down to network configuration.

Q: What is the Network mode of the API Management instance?

A: In my case, it’s Internal

Q: Are custom domains configured?

A: Yes, the APIM domain is managed by a private DNS zone

Q: Is a firewall involved?

A: No, the ingress is via AFD/ACA.

Q: Any known dependencies taken by upstream/downstream on the IPs involved?

A: No, APIM is not directly connected to AFD via PLS. Egress stays private (no internet traffic therefore the APIM VIP is not used).

Q: Is it a multi-geo deployment?

A: No, only a single subnet is involved.

Q: Can we modify the existing instance or is a parallel setup required?

A: Both are viable options, depending on the impact / risks.

Q: Can there be downtime?

A: Preferably not. If needed, it should be during non-business hours.

Next step is to assessing the migration impact on four points: Ingress, Egress, APIM and Supporting services.

Option 1 : in place

Inbound : No impact because ACA uses the APIM default hostname to forward the requests to gateway. The APIM configuration is not going to change therefore there is no need to change neither AFD nor ACA configuration.

There is a minimal Impact on the NSG to update few rules.

Outbound: No impact because there are no dependencies on the APIM VIP (for example we are not calling external dependencies that are implementing IP filter).

APIM Service: No impact because a new APIM gateway that leverage the new compute model (stv2) will be created side by side sharing the same configuration. When the gateway will be up and running we have 48 hours to validate the stv2, switch the DNS, validate the solution end to end and switch back to stv1 in case of errors.

Supporting Services: The Infrastructure-as-Code. has to be updated to create a new subnet and the IPv4 standard, to change the NSG rules and to associate APIM to the new subnet.

Risks :  The upgrade procedure is fully automated therefore the risk of human errors are negligible. The side-by-side migration is a safe approach however there is always a risk that something goes wrong. In that worst-case, the Microsoft support is there to help.

Option 2 : parallel setup

The parallel setup approach comes with almost zero-risks but is the most costly as it requires to reconfigure all the dependencies (reports, dashboards, alerts, etc…). Another annoying part is the APIM analytics will start from scratch with the new instance. 

In-place migration

For my scenario both options fits the customer requirements (zero downtime). The option 1 comes with less moving parts therefore it’s my preferred choice.

Let’s proceed by implementing few changes in the network :

• Create a new subnet (e.g. 10.2.0.0/27) in the existing VNET.
• Create a new IPv4 (make sure a DNS name is configured).
• Modify the NSG (load balancer inbound and key vault outbound).

To trigger the migration, go to the Azure Portal, select your API Management service and click on network section. Change the subnet to use the newly created one and specify the IP v4 created at the previous step. In the top navigation bar, select Save to apply the new network configuration.

When the upgrade procedure starts the APIM service will be locked (readonly) for the time of the migration. In my case the migration took less than 30 minutes. 

Once the migration is completed the new VIPs (private and public) will be displayed in the Azure Portal.

The last step is to update the private DNS to change the name resolution from 10.2.0.5 to 10.6.0.4. You might consider to lower the TTL for a quick change propagation.

That’s all. In my sample case, everything went extremely smoothly. I can now leverage the new compute model and the resiliency and security benefits it brings.

For this blog post, we triggered the migration using the Azure Portal. However, it is advised to automate everything as code. Remember to update the APIM service resource by changing the API version (e.g., 2023-05-01-preview), passing the newly created subnet id, and by adding the publicIpAddressId value.

Conclusion

The cloud landscape is dynamic, constantly evolving with the addition of new services, the phasing out of old ones, and the introduction of new features.

While the PaaS model drastically reduces operational tasks, it’s essential to be aware that it is not a zero-operation model. In this article we explored how to migrate Azure API Management to the stv2 platform without impact of our user base. May the PaaS force be with you!

Photo by Annie Spratt on Unsplash