If you are running Azure API management services, you’ve probably 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 the migration procedure, check out the Microsoft documentation through 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 with 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 the APIM instance with a new subnet.
You can also opt for a parallel setup by creating a brand new APIM instance (newly created gateways default to the STv2 compute), and then rerouting 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 our customers these questions, which are key to deciding which migration path suits our customers the best.
In the end, it all boils down to network configuration. See this example:
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, AFD and ACA are not directly using the APIM IP address. Egress stays private (there is 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.
The next step is to assess 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 the gateway. The APIM configuration is not going to change, therefore there is no need to change either AFD or ACA configuration. There is a minimal impact on the NSG which must update a 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 filters).
APIM Service: No impact because a new APIM gateway that leverages the new compute model (stv2) will be created side by side sharing the same configuration. When the gateway is 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. The IPv4 standard must be adapted to the NSG rules, and to associate APIM to the new subnet.
Risks: The upgrade procedure is fully automated, so the risk of human error is negligible. The side-by-side migration is a safe approach. However, there is always a risk of something going wrong. In that case, 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 the reconfiguration of all the dependencies (reports, dashboards, alerts, etc.). Moreover, the APIM analytics will start from scratch with the new instance.
In-place migration
In my scenario, both options fit the customer’s requirements (zero downtime). However, option 1 comes with fewer moving parts and therefore it’s my preferred choice.
Let’s proceed by implementing a 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 the network section. Change the subnet to use the newly created one and specify the IP v4 created in 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 (read-only) 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 lowering the TTL for quick change propagation too.
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 impacting our user base. May the PaaS force be with you!
Subscribe to our RSS feed