Deploy an Azure API Management self-hosted gateway to Azure Container Apps

Availability

This article provides the steps to deploy the self-hosted gateway component of Azure API Management to Azure Container Apps.

Deploy a self-hosted gateway to a container app to access APIs that are hosted in the same Azure Container Apps environment.

Prerequisites

• Complete the following quickstart: Create an Azure API Management instance.

• For Azure CLI:

  You can use the local Azure CLI.

  • If you prefer, install the Azure CLI to run CLI reference commands.

  • Local Azure CLI, see how to install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

    • Sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.

    • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.

    • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

  Note

  The Azure CLI command examples in this article require the containerapp Azure CLI extension. If you haven't used az containerapp commands, the extension is installed dynamically when you run your first az containerapp command. Learn more about Azure CLI extensions.

Provision gateway in your API Management instance

Before deploying a self-hosted gateway, provision a gateway resource in your Azure API Management instance. For steps, see Provision a self-hosted gateway. In the examples in this article, the gateway is named my-gateway.

Get gateway deployment settings from API Management

To deploy the gateway, you need the gateway's Token and Configuration endpoint values. You can find them in the Azure portal:

1. Sign in to the Azure portal, and navigate to your API Management instance.
2. In the left menu, under Deployment and infrastructure, select Gateways.
3. Select the gateway resource you provisioned, and select Deployment.
4. Copy the Token and Configuration endpoint values.

Deploy the self-hosted gateway to a container app

You can deploy the self-hosted gateway container image to a container app using the Azure portal, Azure CLI, or other tools. This article shows steps using the Azure CLI.

Create a container apps environment

First, create a container apps environment using the az containerapp env create command:

#!/bin/bash
az containerapp env create --name my-environment --resource-group myResourceGroup \
    --location chinanorth3

# PowerShell syntax
az containerapp env create --name my-environment --resource-group myResourceGroup `
    --location chinanorth3

This command creates:

• A container app environment named my-environment that you use to group container apps.
• A log analytics workspace

Create a container app for the self-hosted gateway

To deploy the self-hosted gateway to a container app in the environment, run the az containerapp create command.

First set variables for the Token and Configuration endpoint values from the API Management gateway resource.

#!/bin/bash
endpoint="<API Management configuration endpoint>"
token="<API Management gateway token>"

# PowerShell syntax
$endpoint="<API Management configuration endpoint>"
$token="<API Management gateway token>"

Create the container app using the az containerapp create command:

#!/bin/bash
az containerapp create --name my-gateway \
    --resource-group myResourceGroup --environment 'my-environment' \
    --image "mcr.microsoft.com/azure-api-management/gateway:2.5.0" \
    --target-port 8080 --ingress external \
    --min-replicas 1 --max-replicas 3 \
    --env-vars "config.service.endpoint"="$endpoint" "config.service.auth"="$token" "net.server.http.forwarded.proto.enabled"="true"

# PowerShell syntax
az containerapp create --name my-gateway `
    --resource-group myResourceGroup --environment 'my-environment' `
    --image "mcr.microsoft.com/azure-api-management/gateway:2.5.0" `
    --target-port 8080 --ingress external `
    --min-replicas 1 --max-replicas 3 `
    --env-vars "config.service.endpoint"="$endpoint" "config.service.auth"="$token" "net.server.http.forwarded.proto.enabled"="true"

This command creates:

• A container app named my-gateway in the myResourceGroup resource group. In this example, the container app is created using the mcr.microsoft.com/azure-api-management/gateway:2.5.0 image. Learn more about the self-hosted gateway container images.

• Support for external ingress to the container app on port 8080.

• A minimum of 1 and a maximum of 3 replicas of the container app.

• A connection from the self-hosted gateway to the API Management instance using configuration values passed in environment variables. For details, see the self-hosted gateway container configuration settings.

  Note

  Azure Container Apps ingress forwards HTTPS requests to the self-hosted gateway container app as HTTP. Here, the net.server.http.forwarded.proto.enabled environment variable is set to true so that the self-hosted gateway uses the X-Forwarded-Proto header to determine the original protocol of the request.

Confirm that the container app is running

1. Sign in to the Azure portal, and navigate to your container app.

2. On the container app's Overview page, check that the Status is Running.

3. Send a test request to the status endpoint on /status-012345678990abcdef. For example, use a curl command similar to the following.

   curl -i https://my-gateway.happyvalley-abcd1234.chinanorth3.azurecontainerapps.io/status-012345678990abcdef
   

   A successful request returns a 200 OK response.

Confirm that the gateway is healthy

1. Sign in to the Azure portal, and navigate to your API Management instance.

2. In the left menu, under Deployment and infrastructure, select Gateways.

3. On the Overview page, check the Status of your gateway. If the gateway is healthy, it reports regular gateway heartbeats.

   

Example scenario

The following example shows how you can use the self-hosted gateway to access an API hosted in a container app in the same environment. As shown in the following diagram, the self-hosted gateway can be accessed from the internet, while the API is only accessible within the container apps environment.

1. Deploy a container app hosting an API in the same environment as the self-hosted gateway
2. Add the API to your API Management instance
3. Call the API through the self-hosted gateway

Deploy a container app hosting an API in the same environment as the self-hosted gateway

For example, deploy an example music album API to a container app. For later access to the API using the self-hosted gateway, deploy the API in the same environment as the self-hosted gateway. For detailed steps and information about the resources used in this example, see Quickstart: Build and deploy from local source code to Azure Container Apps. Abbreviated steps follow:

1. Download Python source code to your local machine. If you prefer, download the source code in another language of your choice.

2. Extract the source code to a local folder and change to the containerapps-albumapi-python-main/src folder.

3. Run the following az containerapp up command to deploy the API to a container app in the same environment as the self-hosted gateway. Note the . at the end of the command, which specifies the current folder as the source for the container app.

   • Bash
   • PowerShell

   #!/bin/bash
   az containerapp up --name albums-api \
       --resource-group myResourceGroup --location chinanorth3 \
       --environment my-environment --source .
   

4. Confirm that the container app is running and accessible externally at the FQDN returned in the command output. By default the API is accessible at the /albums endpoint. Example: https://albums-api.happyvalley-abcd1234.chinanorth3.azurecontainerapps.io/albums/albums.

Configure the API for internal ingress

Now update the container app hosting the sample API to enable ingress only in the container environment. This setting restricts access to the API only from the self-hosted gateway that you deployed.

1. Sign in to the Azure portal, and navigate to your container app.
2. In the left menu, select Ingress.
3. Set Ingress to Enabled.
4. In Ingress traffic, select Limited to Container Apps Environment.
5. Review the remaining settings and select Save.

Add the API to your API Management instance

The following are example steps to add an API to your API Management instance and configure an API backend. For more information, see Add an API to Azure API Management.

Add the API to your API Management instance

1. In the portal, navigate to the API Management instance where you configured the self-hosted gateway.
2. In the left menu, select APIs > + Add API.
3. Select HTTP and select Full. Enter the following settings:
   1. Display name: Enter a descriptive name. Example: Albums API.
   2. Web service URL: Enter the internal FQDN of the container app hosting the API. Example: http://albums-api.internal.happyvalley-abcd1234.chinanorth3.azurecontainerapps.io.
   3. URL scheme: Select HTTP(S).
   4. API URL suffix: Enter a suffix of your choice. Example: albumapi.
   5. Gateways: Select the self-hosted gateway you provisioned. Example: my-gateway.
4. Configure other API settings according to your scenario. Select Create.

Add an API operation

1. In the left menu, select APIs > Albums API.
2. Select + Add operation.
3. Enter operation settings:
   1. Display name: Enter a descriptive name for the operation. Example: Get albums.
   2. URL: Select Get and enter /albums for the endpoint.
   3. Select Save.

Call the API through the self-hosted gateway

Call the API using the FQDN of the self-hosted gateway running in the container app. Find the FQDN on the container app's Overview page in the Azure portal, or run the following az containerapp show command.

#!/bin/bash
az containerapp show --name my-gateway --resource-group myResourceGroup \
    --query "properties.configuration.ingress.fqdn" --output tsv

# PowerShell syntax
az containerapp show --name my-gateway --resource-group myResourceGroup `
    --query "properties.configuration.ingress.fqdn" --output tsv

For example, run the following curl command to call the API at the /albumapi/albums endpoint. If your API requires a subscription key, pass a valid subscription key for your API Management instance as a header in the request:

curl -i https://my-gateway.happyvalley-abcd1234.chinanorth3.azurecontainerapps.io/albumapi/albums -H "Ocp-Apim-Subscription-Key: <subscription-key>"

When the test is successful, the backend responds with a successful HTTP response code and some data.

HTTP/1.1 200 OK
content-length: 751
content-type: application/json
date: Wed, 28 Feb 2024 22:45:09 GMT
[...]

[{"id":1,"title":"You, Me and an App Id","artist":"Daprize","price":10.99,"image_url":"https://aka.ms/albums-daprlogo"},{"id":2,"title":"Seven Revision Army","artist":"The Blue-Green Stripes","price":13.99,"image_url":"https://aka.ms/albums-containerappslogo"},{"id":3,"title":"Scale It Up","artist":"KEDA Club","price":13.99,"image_url":"https://aka.ms/albums-kedalogo"},{"id":4,"title":"Lost in Translation","artist":"MegaDNS","price":12.99,"image_url":"https://aka.ms/albums-envoylogo"},{"id":5,"title":"Lock Down Your Love","artist":"V is for VNET","price":12.99,"image_url":"https://aka.ms/albums-vnetlogo"},{"id":6,"title":"Sweet Container O' Mine","artist":"Guns N Probeses","price":14.99,"image_url":"https://aka.ms/albums-containerappslogo"}]

Related content

• Connected microservices with Azure Container Apps
• Azure API Management's Self-Hosted Gateway on Azure Container Apps