Use rule-based routing with Azure Container Apps

In this article, you learn how to use rule-based routing with Azure Container Apps. With rule-based routing, you create a fully qualified domain name (FQDN) on your container apps environment. You then use rules to route requests for this FQDN to different container apps, depending on the path of each request.

Routing and authorization model

HTTP route configurations (httpRouteConfigs) operate at the Container Apps environment level. A route can target any container app in the same environment, regardless of the target app's individual ingress setting. Since the route's FQDN is published under the environment's domain, a route can provide a public entry point that forwards requests to a container app that uses internal ingress (external: false). This behavior enables the composition of multiple apps under one host.

Permissions for HTTP route configurations are scoped to the managed environment rather than to individual container apps. Creating, updating, or deleting a route requires the Microsoft.App/managedEnvironments/httpRouteConfigs/write permission on the environment. No extra permission on the target container app is required. This behavior is consistent with the environment being a shared trust boundary, where all container apps in an environment belong to the same customer. Any principal with an environment-scoped role that includes httpRouteConfigs/write permission, such as Contributor on the environment, can create routes that target any container app in that environment.

Important

An HTTP route configuration can expose a container app that uses internal ingress (external: false) if you configure the app as a route target. The external: false setting controls the visibility of the app's own FQDN. By using this configuration, the environment doesn't prevent the app from receiving traffic through an environment-level route. To keep a container app unreachable from outside the environment, don't reference it as a target in any HTTP route configuration. Instead, place the app in a separate environment that has no public routes, or use network-level controls to restrict inbound traffic.

Prerequisites

• Azure account with an active subscription.

  • If you don't have one, you can create one for free.

• Install the Azure CLI.

• Bicep

Setup

1. Run the following command so sign in to Azure from the CLI.

   az login
   

2. To ensure you're running the latest version of the CLI, run the upgrade command.

   az upgrade
   

   Ignore any warnings about modules currently in use.

3. Now that the current extension or module is installed, register the Microsoft.App and Microsoft.OperationalInsights namespaces.

   az provider register --namespace Microsoft.App
   

   az provider register --namespace Microsoft.OperationalInsights
   

Create environment variables

Create the following environment variables.

CONTAINER_APP_1_NAME="my-container-app-1"
CONTAINER_APP_1_IMAGE="mcr.microsoft.com/k8se/quickstart:latest"
CONTAINER_APP_1_TARGET_PORT="80"
CONTAINER_APP_2_NAME="my-container-app-2"
CONTAINER_APP_2_IMAGE="mcr.microsoft.com/dotnet/samples:aspnetapp"
CONTAINER_APP_2_TARGET_PORT="8080"
LOCATION="eastus"
RESOURCE_GROUP="my-container-apps"
ENVIRONMENT_NAME="my-container-apps-env"
ROUTE_CONFIG_NAME="my-route-config"

Create container apps

1. Run the following command to create your first container app. This container app uses the Container Apps quickstart image.

   az containerapp up \
     --name $CONTAINER_APP_1_NAME \
     --resource-group $RESOURCE_GROUP \
     --location $LOCATION \
     --environment $ENVIRONMENT_NAME \
     --image $CONTAINER_APP_1_IMAGE \
     --target-port $CONTAINER_APP_1_TARGET_PORT \
     --ingress external \
     --query properties.configuration.ingress.fqdn
   

2. Run the following command to create your second container app. This container app uses the ASP.NET quickstart image.

   az containerapp up \
     --name $CONTAINER_APP_2_NAME \
     --resource-group $RESOURCE_GROUP \
     --location $LOCATION \
     --environment $ENVIRONMENT_NAME \
     --image $CONTAINER_APP_2_IMAGE \
     --target-port $CONTAINER_APP_2_TARGET_PORT \
     --ingress external \
     --query properties.configuration.ingress.fqdn
   

3. Create HTTP route configuration.

   Create the following file and save it as routing.yml.

   rules:
     - description: App 1 rule
       routes:
         - match:
             prefix: /app1
           action:
             prefixRewrite: /
       targets:
         - containerApp: my-container-app-1
     - description: App 2 rule
       routes:
         - match:
             path: /app2
           action:
             prefixRewrite: /
         - match:
             path: /
       targets:
         - containerApp: my-container-app-2
   

   This configuration defines two routing rules for HTTP traffic.

   Note

   The order of the routing rules matters.

   More specific prefixes need to be before less specific prefixes.

   For example, if the first rule matches the prefix /api, that will be used even if the second rule uses the prefix /api/v1.

   Property	Description
   description	Human-readable label for the rule
   routes.match.prefix	URL path prefix to match. For example, /api.
   routes.action.prefixRewrite	What to replace the matched prefix with before forwarding.
   targets.containerApp	The name of the container app where matching route request are sent.

   These rules allow different paths on your domain to route to different container apps while also modifying the request path before it reaches the destination app.

   Other properties not listed that may affect your routes include the following.

   Property	Description
   route.match.path	Exact match path definition.
   route.match.pathSeparatedPrefix	Matches routes on '/' boundaries rather than any text. For example, if you set the value to /product, then it will match on /product/1, but not /product1.
   route.match.caseSensitive	Controls whether or not route patterns match with case sensitivity.
   target.label	Route to a specific labeled revision within a container app.
   target.revision	Route to a specific revision within a container app.

4. Run the following command to create the HTTP route configuration.

   az containerapp env http-route-config create \
     --http-route-config-name $ROUTE_CONFIG_NAME \
     --resource-group $RESOURCE_GROUP \
     --name $ENVIRONMENT_NAME \
     --yaml routing.yml \
     --query properties.fqdn
   

   Your HTTP route configuration's fully qualified domain name (FQDN) looks like this example: my-route-config.ambitiouspebble-11ba6155.eastus.azurecontainerapps.io

1. Ensure both container apps already exist.

2. Create the following Bicep file and save it as routing.bicep.

   resource containerAppsEnvironment 'Microsoft.App/managedEnvironments@2024-10-02-preview' = {
     name: 'my-container-apps-env'
     location: 'eastus'
     tags: {}
     properties: {
       workloadProfiles: [
           {
               workloadProfileType: 'Consumption'
               name: 'Consumption'
           }
       ]
     }
   }
   
   resource httpRouteConfig 'Microsoft.App/managedEnvironments/httpRouteConfigs@2024-10-02-preview' = {
     parent: containerAppsEnvironment
     name: 'my-route-config'
     location: 'eastus'
     properties: {
       rules: [
           {
               description: 'App 1 rule'
               routes: [
                   {
                       match: {
                           prefix: '/app1'
                       }
                       action: {
                           prefixRewrite: '/'
                       }
                   }
               ]
               targets: [
                   {
                       containerApp: 'my-container-app-1'
                   }
               ]
           }
           {
               description: 'App 2 rule'
               routes: [
                   {
                       match: {
                           path: '/app2'
                       }
                       action: {
                           prefixRewrite: '/'
                       }
                   }
                   {
                       match: {
                           path: '/'
                       }
                   }
               ]
               targets: [
                   {
                       containerApp: 'my-container-app-2'
                   }
               ]
           }
       ]
     }
   }
   
   output fqdn string = httpRouteConfig.properties.fqdn
   

3. Deploy the Bicep file with the following command:

   az deployment group create `
     --name $ROUTE_CONFIG_NAME `
     --resource-group $RESOURCE_GROUP `
     --template-file routing.bicep
   

4. In the output, find outputs, which contains your HTTP route configuration's fully qualified domain name (FQDN). For example:

       "outputs": {
         "fqdn": {
           "type": "String",
           "value": "my-route-config.ambitiouspebble-11ba6155.eastus.azurecontainerapps.io"
         }
       },
   

Verify HTTP route configuration

1. Browse to your HTTP route configuration FQDN with the path /app1.

   For example: my-route-config.ambitiouspebble-11ba6155.eastus.azurecontainerapps.io/app1.

   You see the Container Apps quickstart image.

2. Browse to your HTTP route configuration FQDN with the path /app2.

   For example: my-route-config.ambitiouspebble-11ba6155.eastus.azurecontainerapps.io/app2.

   You see the ASP.NET quickstart image.

Clean up resources

If you're not going to continue to use this application, run the following command to delete the resource group along with all the resources created in this quickstart.

Caution

The following command deletes the specified resource group and all resources contained within it. If resources outside the scope of this quickstart exist in the specified resource group, they'll also be deleted.

az group delete --name my-container-apps

Related content

• Azure CLI reference
• Bicep reference
• ARM template reference