I recently had to help troubleshoot an issue where an Azure API Management‘s developer portal deployed into a VNet was not accessible after publishing it through an Application Gateway and while there were material available through articles, the instructions weren’t very clear so I wanted to write this blog post to elaborate how to validate and remediate the issue.
Problem
The APIM exhibits the symptom where the Publish button is greyed out as shown in the following screenshot:
… and attempting to launch the developer portal via the Developer portal button will launch the developer portal but only display the side navigation bar with the center pane that never loads:
The following message will eventually be displayed at the bottom right corner:
Unable to start the portal
Check if the settings specified in the configuration file config.design.json are correct or refer to the frequently asked questions.
There are no issues accessing the Gateway URL through the App Gateway works when you attempt to use postman to test the Echo API:
Validating the Issue
One of the common causes for this behavior is if the management endpoint of the APIM is not reachable because it hasn’t been published through the App Gateway. For context, the endpoints for the APIM are listed out in the following table:
| Endpoint | Default |
|---|---|
| Gateway | Default is: <apim-service-name>.azure-api.net. Gateway is the only endpoint available for configuration in the Consumption tier. The default Gateway endpoint configuration remains available after a custom Gateway domain is added. |
| Developer portal | Default is: <apim-service-name>.developer.azure-api.net |
| Management | Default is: <apim-service-name>.management.azure-api.net |
| Configuration API (v2) | Default is: <apim-service-name>.configuration.azure-api.net |
| SCM | Default is: <apim-service-name>.scm.azure-api.net |
Reference document: https://learn.microsoft.com/en-us/azure/api-management/configure-custom-domain?tabs=custom#endpoints-for-custom-domains To confirm this, we can perform a Network trace with the browser as the page loads and several errors should be displayed. Putting the cursor over the error will display the URL that has failed:
As displayed in the screenshot, the failure is related to the APIM management endpoint:
Request URL:
https://development-apim-test.management.azure-api.net/subscriptions/000/resourceGroups/000/providers/Microsoft.ApiManagement/service/development-apim-test/groups?skipWorkspaces=true&api-version=2023-03-01-preview
For the purpose of this demonstration, I have purposely configured the APIM’s custom domains to only have the Developer portal and Gateway endpoint:
The Application Gateway has also been configured to only publish the Developer portal and Gateway endpoint:
- developer.contoso.com
- api.contoso.com
Remediation
The first step to correct this issue is to configure a custom domain for the management endpoint on the APIM:
Create a Management endpoint:
Save the new setting and wait for the APIM to complete the update. Note that the Service is being updated… process can take quite a long time and the new management endpoint would not show up until it is finished:
Once complete, the Management endpoint should be displayed:
- developer.contoso.com
- api.contoso.com
- management.contoso.com
Now that a custom domain for the Management Endpoint has been added to the APIM, we can proceed to configure a new Listener for on the App Gateway:
The Backend Setting:
The health probe:
Note that the health probes for the 3 services are all different:
- API Gateway
- Developer Portal
- Management
The respective paths for the probe are:
- /status-0123456789abcdef
- /signin
- /ServiceStatus
The Interval, Timeout, and UnhealthyThreshold are also not the defaults of the Application Gateway.
These can be found at the following Microsoft documentation in Step #6:
Create application gateway configuration https://docs.azure.cn/en-us/api-management/api-management-howto-integrate-internal-vnet-appgateway#create-application-gateway-configuration Now finally the Rule:
Proceed to create the DNS record for management.contoso.com to point to the App Gateway and the Developer Portal should now load externally.
Hope this helps anyone who may be encountering this issue.
