Edit

Share via

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

APPLIES TO: Developer | Premium

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

Provision gateway in your Azure 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 this article's examples, 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 go to your Azure API Management instance.
  2. In the left menu, under Deployment + infrastructure, select Self-hosted gateways.
  3. Select the gateway resource you provisioned, and select Settings > 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 centralus

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 Azure API Management gateway resource.

#!/bin/bash
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.9.2" \
    --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 uses the mcr.microsoft.com/azure-api-management/gateway:2.9.2 image. For more information about the self-hosted gateway, see 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 Azure API Management instance by passing configuration values 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 go 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 command.

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

    A successful request returns a 200 OK response.

Tip

Using the CLI, you can also run the az containerapp show command to check the status of the container app.

Confirm that the gateway is healthy

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

  2. In the left menu, under Deployment + infrastructure, select Self-hosted gateways.

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

    Screenshot of gateway status in the portal.

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.

Diagram of example scenario with self-hosted gateway.

  1. Deploy a container app hosting an API in the same environment as the self-hosted gateway.
  2. Add the API to your Azure 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

In this example, you deploy an example music album API to a container app. To access the API later by 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.

    #!/bin/bash
az containerapp up --name albums-api \
    --resource-group myResourceGroup --location centralus \
    --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.centralus.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 go to your container app.
  2. In the left menu, select Networking > 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 Azure API Management instance

The following steps show how to add an API to your Azure 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 Azure portal, go to the API Management instance where you configured the self-hosted gateway.
  2. In the left menu, select APIs > 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.centralus.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 by 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

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.centralus.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"}]

Tip

If you enable logging for your API to Application insights, you can query the logs to see the requests and responses.

Limitations

Self-hosted gateway instances rely on the UDP protocol for heartbeat and rate-limit communications. Because Azure Container Apps currently doesn't support the UDP protocol, neither for ingress nor for internal traffic, the rate-limit policy can't synchronize its counter across instances. Consequently, maintaining three replicas of a self-hosted gateway container app with limit X might result in three times the traffic until limit X is reached.

Azure Container Apps distributes requests linearly across each available and healthy replica. To implement rate limiting, you can divide the desired limit by the number of replicas you want to run and set the resulting value in configuration. This approach has its own downsides as you might not be able to account for adjusted counters if and when your container apps scale.

Related content