Merge pull request #310136 from craigshoemaker/aca/enable-labels

[Container Apps] Update: Deployment labels -> clarify enabling deployment labels

Author: prmerger-automator[bot]

articles/container-apps/deployment-labels.md

@@ -6,37 +6,40 @@ author: craigshoemaker
 ms.author: cshoe
 ms.service: azure-container-apps
 ms.topic: tutorial
-ms.date: 10/27/2025
+ms.date: 01/05/2026
 zone_pivot_groups: azure-cli-or-portal
 ---
 
 # Deployment labels in Azure Container Apps
 
-Deployment labels allow you to assign meaningful names (such as dev, staging, prod) to specific container revisions. Applying these names gives you a streamlined process for handling complex deployment scenarios and environment management.
+Deployment labels help you assign meaningful names, such as dev, staging, or prod, to specific container revisions. When you apply these names, you streamline handling complex deployment scenarios and environment management.
 
-With deployment labels, you can:
+By using deployment labels, you can:
 
-- Assign clear, descriptive labels to revisions
-- Have new revisions automatically assigned to labels for routing and traffic management
-- Route traffic based on labels instead of changing revision names
-- Promote or demote revisions by reassigning labels
-- Roll back to previous revisions using label history
+- Assign clear, descriptive labels to revisions.
+- Automatically assign new revisions to labels for routing and traffic management.
+- Route traffic based on labels instead of changing revision names.
+- Promote or demote revisions by reassigning labels.
+- Roll back to previous revisions by using label history.
+
+> [!IMPORTANT]
+> Before you can use deployment labels, you need to follow the steps to first [enable deployment](?pivots=azure-portal#use-deployment-labels) labels in the portal for your container app.
 
 ## Key features
 
-Deployment labels enable you to create sophisticated deployment strategies while maintaining control over your application lifecycle with the following features:
+Deployment labels enable you to create sophisticated deployment strategies while maintaining control over your application lifecycle by using the following features:
 
 - **Label assignment**: Create and assign meaningful labels to container revisions, making it easier to manage environments like dev, staging, and prod.
 
 - **Traffic splitting & A/B testing**: Support for traffic splitting, blind rollback, and A/B testing enables gradual rollouts and testing of new features.
 
-- **Staging releases & auto swap**: Automatic revision activation allows you to seamlessly create new revisions and have them assigned to new or existing labels and receive traffic. Any revisions no longer referenced by a label will be shut down automatically.
+- **Staging releases & auto swap**: Automatic revision activation allows you to seamlessly create new revisions and assign them to new or existing labels to receive traffic. Any revisions no longer referenced by a label are shut down automatically.
 
 ::: zone pivot="azure-portal"
 
 ## Use deployment labels
 
-To enable deployment labels, follow these steps in the Azure portal:
+By default deployment labels aren't available to your container app. To enable, deployment labels, follow these steps in the Azure portal:
 
 1. Open your container app in the Azure portal.
 
@@ -48,9 +51,9 @@ To enable deployment labels, follow these steps in the Azure portal:
 
 1. Select **Apply**.
 
-### Create a new label 
+### Create a new label
 
-New labels are based on existing labels when created in the portal. By default Container Apps creates your first label for you named *label-1*. When labels are created via CLI or Bicep, you can associate them with any existing revision or a new revision. 
+Create new labels in the portal based on existing labels. By default, Container Apps creates your first label named *label-1*. When you create labels through the CLI or Bicep, you can associate them with any existing revision or a new revision.
 
 1. Open your container app in the Azure portal.
 
@@ -66,13 +69,13 @@ New labels are based on existing labels when created in the portal. By default C
 
 ### Label history and rollbacks
 
-You can view the full history of a label using the following steps:
+You can view the full history of a label by using the following steps:
 
 1. Open your container app in the Azure portal.
 
 1. From the menu, under *Application*, select **Labels**.
 
-1. Select **Show history** associated with the label you're interested in.
+1. Select **Show history** for the label you're interested in.
 
 Use the *Show history* option for any label to:
 
@@ -116,6 +119,7 @@ To enable deployment labels, follow these steps in the Azure CLI:
    ```
 
 1. To create a new revision with a new or existing label, use the following command:
+
    ```bash
    az containerapp update \
    --name $CONTAINER_APP_NAME \
@@ -125,6 +129,7 @@ To enable deployment labels, follow these steps in the Azure CLI:
    ```
 
 1. To show label history, use the following command:
+
    ```bash
    az containerapp label-history show \
    --name $CONTAINER_APP_NAME \
@@ -133,13 +138,15 @@ To enable deployment labels, follow these steps in the Azure CLI:
    ```
 
 1. To show label app traffic, use the following command:
+
    ```bash
    az containerapp ingress traffic show \
    --name $CONTAINER_APP_NAME \
    --resource-group $RESOURCE_GROUP \
    ```
 
 1. To add a label to a revision, use the following commands:
+
    ```bash
    az containerapp revision label add \
    --name $CONTAINER_APP_NAME \
@@ -177,11 +184,11 @@ Here's a typical workflow using deployment labels:
 
 1. **Update a label**: Select a label (for example, "stage") to update it with new containers, scaling, or volume settings.
 
-1. **Test the changes**: With the new revision deployed, you can route a portion of traffic to the updated label.
+1. **Test the changes**: With the new revision deployed, route a portion of traffic to the updated label.
 
-1. **Promote changes**: Once you feel confident in the production revision, you can update the production label to point to the same revision
+1. **Promote changes**: When you're confident in the production revision, update the production label to point to the same revision.
 
-1. **Monitor and rollback if needed**: If issues arise, use the label history to roll back to a previous version.
+1. **Monitor and rollback if needed**: If problems arise, use the label history to roll back to a previous version.
 
 ## Related content