add custom domain how-to

Author: craigshoemaker

articles/container-apps/TOC.yml

@@ -376,8 +376,12 @@
           href: waf-app-gateway.md
         - name: Enable User Defined Routes (UDR)
           href: user-defined-routes.md
-        - name: Use rule-based routing
-          href: rule-based-routing.md
+        - name: Rule based routing
+          items:
+          - name: Use rule-based routing
+            href: rule-based-routing.md
+          - name: Configure a custom domain
+            href: rule-based-routing-custom-domain.md
         - name: Securing a custom VNET with an NSG
           href: firewall-integration.md
         - name: Use a private endpoint

articles/container-apps/rule-based-routing-custom-domain.md

@@ -0,0 +1,153 @@
+---
+title: Use a custom domain with rule-based routing in Azure Container Apps (preview)
+description: Learn how to configure a custom domain with rule-based routing in Azure Container Apps.
+services: container-apps
+author: craigshoemaker
+ms.service: azure-container-apps
+ms.custom: devx-track-azurecli, devx-track-bicep
+ms.topic: how-to
+ms.date: 04/15/2025
+ms.author: cshoe
+zone_pivot_groups: azure-cli-bicep
+---
+
+# Use a custom domain with rule-based routing in Azure Container Apps (preview)
+
+HTTP route configurations support custom domains, allowing you to route traffic from your own domain names to your container apps.
+
+## Prerequisites
+
+- An existing Azure Container Apps environment
+- A custom domain that you own
+- SSL certificate for your domain (unless using automatic certificates)
+- Container apps deployed to your environment
+
+> [!NOTE]
+> To set up your own custom domain and certificate, see [Custom domain names and free managed certificates](./custom-domains-managed-certificates.md).
+>
+> If you set `bindingType: "Auto"`, you don't need a `certificateId`. Container Apps creates the certificate for you based on the domain.
+
+## Configuration
+
+Update your Container Apps YAML file to include a `customDomains` section. The following example demonstrates how to set up this configuration.
+
+```yml
+customDomains:
+  - name: "<CUSTOM_DOMAIN_ENDPOINT>" 
+    certificateId: "<CERTIFICATE_ID>"
+    bindingType: "SniEnabled" # Can also be "Disabled", "Auto"
+rules:
+  - description: "Routing to App1"
+    routes:
+      - match:
+          prefix: "/1"
+        action:
+          prefixRewrite: "/"
+    targets:
+      - containerApp: "<CONTAINER_APP_NAME>"
+  - description: "Routing to App2"
+    routes:
+      - match:
+          prefix: "/2"
+        action:
+          prefixRewrite: "/"
+    targets:
+      - containerApp: "<CONTAINER_APP_NAME>"
+```
+
+This YAML configuration defines two routing rules for HTTP traffic.
+
+| Property | Description |
+|---|---|
+| `customDomains.name` | The domain name you want to use (example: "app.contoso.com") |
+| `customDomains.certificateId` | Resource ID of your certificate (not needed with `bindingType: "Auto"`) |
+| `customDomains.bindingType` | How SSL is handled: "SniEnabled" (Server Name Indication), "Disabled" (HTTP only), or "Auto" (automatic certificate) |
+| `description` | Human-readable label for the rule |
+| `routes.match.prefix` | URL path prefix to match (example: "/api") |
+| `routes.action.prefixRewrite` | What to replace the matched prefix with before forwarding |
+| `targets.containerApp` | The name of the container app to route matching requests to |
+
+These rules allow different paths on your custom domain to route to different container apps while also modifying the request path before it reaches the destination app.
+
+## Work with your custom domain
+
+Use the following commands to configure and use your custom domain mapping.
+
+Before running the following commands, make sure to replace placeholders surrounded by `<>` with your own values.
+
+### List route configurations
+
+Use `az containerapp env http-route-config list` to list all the defined route configurations.
+
+```azurecli
+az containerapp env http-route-config list \
+    --resource-group <RESOURCE_GROUP_NAME> \
+    --name <ENVIRONMENT_NAME>
+```
+
+### Create a new route configuration
+
+Use `az containerapp env http-route-config create` to create a new route configuration.
+
+```azurecli
+az containerapp env http-route-config create \
+    --resource-group <RESOURCE_GROUP_NAME> \
+    --name <ENVIRONMENT_NAME> \
+    --http-route-config-name <CONFIGURATION_NAME> \
+    --yaml <CONTAINER_APPS_CONFIG_FILE>
+```
+
+### Update a route configuration
+
+Use `az containerapp env http-route-config update` to update an existing route configuration.
+
+```azurecli
+az containerapp env http-route-config update \
+  --resource-group <RESOURCE_GROUP_NAME> \
+  --name <ENVIRONMENT_NAME> \
+  --http-route-config-name <CONFIGURATION_NAME> \
+  --yaml <CONTAINER_APPS_CONFIG_FILE>
+```
+
+### Show a specific route configuration
+
+Use `az containerapp env http-route-config show` to view details of a route configuration.
+
+```azurecli
+az containerapp env http-route-config show \
+    --resource-group <RESOURCE_GROUP_NAME> \
+    --name <ENVIRONMENT_NAME> \
+    --http-route-config-name <CONFIGURATION_NAME>
+```
+
+### Delete a route configuration
+
+Use `az containerapp env http-route-config delete` to remove a route configuration.
+
+```azurecli
+az containerapp env http-route-config delete \
+    --resource-group <RESOURCE_GROUP_NAME> \
+    --name <ENVIRONMENT_NAME> \
+    --http-route-config-name <CONFIGURATION_NAME>
+```
+
+## Verify HTTP routing
+
+After configuring your custom domain with rule-based routing:
+
+1. Navigate to your custom domain in a browser. For example, `https://app.contoso.com/1`.
+
+1. Verify that the request is routed to the first container app.
+
+1. Change the path to `/2`. For example, `https://app.contoso.com/2`.
+
+1. Verify that the request is now routed to the second container app.
+
+## Related content
+
+- [Rule-based routing in Azure Container Apps](./rule-based-routing.md)
+- [Custom domain names and free managed certificates](./custom-domains-managed-certificates.md)
+- [Azure CLI reference for HTTP route configuration](/cli/azure/containerapp/env/http-route-config)
+
+> [!TIP]
+> Having issues? Let us know on GitHub by opening an issue in the [Azure Container Apps repo](https://github.com/microsoft/azure-container-apps).

articles/container-apps/rule-based-routing.md

@@ -5,8 +5,8 @@ services: container-apps
 author: craigshoemaker
 ms.service: azure-container-apps
 ms.custom: devx-track-azurecli, devx-track-bicep
-ms.topic: how-to
-ms.date: 04/03/2025
+ms.topic: tutorial
+ms.date: 04/15/2025
 ms.author: cshoe
 zone_pivot_groups: azure-cli-bicep
 ---
@@ -44,7 +44,7 @@ az upgrade
 
 Ignore any warnings about modules currently in use.
 
-Next, install or update the Azure Container Apps extension for the CLI.
+Install or update the Azure Container Apps extension for the CLI.
 
 If you receive errors about missing parameters when you run `az containerapp` commands in Azure CLI or cmdlets from the `Az.App` module in PowerShell, be sure you have the latest version of the Azure Container Apps extension installed.
 
@@ -54,6 +54,7 @@ az extension add --name containerapp --upgrade
 
 > [!NOTE]
 > Starting in May 2024, Azure CLI extensions no longer enable preview features by default. To access Container Apps [preview features](whats-new.md), install the Container Apps extension with `--allow-preview true`.
+>
 > ```azurecli
 > az extension add --name containerapp --upgrade --allow-preview true
 > ```
@@ -235,7 +236,7 @@ $ROUTE_CONFIG_NAME="my-route-config"
 
 1. In the output, find `outputs`, which contains your HTTP route configuration's fully qualified domain name (FQDN). For example:
 
-    ```
+    ```json
         "outputs": {
           "fqdn": {
             "type": "String",
@@ -246,26 +247,31 @@ $ROUTE_CONFIG_NAME="my-route-config"
 
 ::: zone-end
 
-## Test HTTP route configuration
+## 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`.
 
-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.
+    You see the Container Apps quickstart image.
 
-1. 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.
+1. 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 will also be deleted.
+> 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.
 
 ```azurecli
 az group delete --name my-container-apps
 ```
 
-> [!TIP]
-> Having issues? Let us know on GitHub by opening an issue in the [Azure Container Apps repo](https://github.com/microsoft/azure-container-apps).
-
 ## Related content
 
 - [Azure CLI reference](/cli/azure/containerapp/env/http-route-config)