Merge pull request #314020 from craigshoemaker/aca/commit-driven-updates-batch1

[Container Apps] Update 9 docs from recent k4apps commits (P1-P3 batch)

Author: JamesJBarnett

articles/container-apps/compose-agent.md

@@ -2,15 +2,15 @@
 title: Deploy Docker Compose for agents to Azure Container Apps Preview
 description: Learn how to use Docker Compose for Agents on Azure Container Apps Preview.
 ms.topic: how-to
-ms.date: 11/18/2025
+ms.date: 03/31/2026
 ms.service: azure-container-apps
 ms.author: cshoe
 author: craigshoemaker
 ---
 
 # Deploy Docker Compose for agents to Azure Container Apps Preview
 
-This article shows you how to deploy applications to Azure Container Apps by using Docker’s Compose for Agents. This feature keeps the compose file you already use locally and allows you to deploy it onto Container Apps. The `az-cli` container app extension then translates the compose file into Azure Container App applications and manages identities, scaling, and model lifecycle for you.
+This article shows you how to deploy applications to Azure Container Apps by using Docker's Compose for Agents. This feature keeps the compose file you already use locally and allows you to deploy it onto Container Apps. The `az-cli` container app extension then translates the compose file into Azure Container App applications and manages identities, scaling, and model lifecycle for you.
 
 In this article, you learn to:
 
@@ -37,7 +37,7 @@ When you run `az containerapp compose create`, the CLI translates agent-focused
 
 ### Model context protocol (MCP) tooling
 
-Azure Container Apps runs a variant of [Docker’s MCP gateway](https://github.com/docker/mcp-gateway) as its own container app. It uses system-assigned managed identity to add or remove MCP tool containers within the environment dynamically. This setup appears as separate containers under the mcp-gateway application. Gateway to MCP tooling communication is limited to the network. Stdio MCP servers are wrapped to run as SSE based MCP servers on Azure Container Apps. Docker for Agents on Azure Container Apps currently supports the following Stdio MCP servers: AppSignal, BigQuery, Confluence, DuckDuckGo, Fetch, Filesystem, Git, Google Drive, Jira, MongoDB, MySQL, Notion, Playwright, PostgreSQL, SequentialThinking, Slack, SQLite, Supabase, Time, Twist.
+Azure Container Apps runs a variant of [Docker's MCP gateway](https://github.com/docker/mcp-gateway) as its own container app. It uses system-assigned managed identity to add or remove MCP tool containers within the environment dynamically. This setup appears as separate containers under the mcp-gateway application. Gateway to MCP tooling communication is limited to the network. Stdio MCP servers are wrapped to run as SSE based MCP servers on Azure Container Apps. Docker for Agents on Azure Container Apps currently supports the following Stdio MCP servers: AppSignal, BigQuery, Confluence, DuckDuckGo, Fetch, Filesystem, Git, Google Drive, Jira, MongoDB, MySQL, Notion, Playwright, PostgreSQL, SequentialThinking, Slack, SQLite, Supabase, Time, Twist.
 
 ### Models
 
@@ -138,6 +138,15 @@ az containerapp compose create \
 			--environment $ENV_NAME
 ```
 
+### Agent settings defaults
+
+Applications created without explicit agent settings receive the following defaults:
+
+* `DiscoveryMode` = `Auto`, which automatically detects agent capabilities and dependencies.
+* `IsAgent` = `false`, indicating that the app doesn't act as an agent unless explicitly configured.
+
+These defaults ensure consistent behavior for all container apps in your environment.
+
 ### Uninstalling and switching back
 
 To switch back to the stable release of the container app extension:

articles/container-apps/environment-variables.md

@@ -6,7 +6,7 @@ author: fred-cardoso
 ms.service: azure-container-apps
 ms.custom: devx-track-azurecli, devx-track-azurepowershell
 ms.topic: how-to
-ms.date: 02/03/2025
+ms.date: 03/31/2026
 ms.author: fredcardoso
 ---
 
@@ -167,6 +167,7 @@ The following variables are available to container apps:
 | `CONTAINER_APP_ENV_DNS_SUFFIX` | The DNS suffix for the Container Apps environment. To obtain the fully qualified domain name (FQDN) of the app, append the app name to the DNS suffix in the format `$CONTAINER_APP_NAME.$CONTAINER_APP_ENV_DNS_SUFFIX`. | `<DEFAULT_HOSTNAME>.<REGION>.azurecontainerapps.io` |
 | `CONTAINER_APP_PORT` | The target port of the container app. | `8080` |
 | `CONTAINER_APP_REPLICA_NAME` | The name of the container app replica. | `my-containerapp--20mh1s9-86c8c4b497-zx9bq` |
+| `CONTAINER_NAME` | The name of the replica. Available for managed function apps and logic apps. | `my-containerapp--20mh1s9-86c8c4b497-zx9bq` |
 
 ### Jobs
 

articles/container-apps/functions-overview.md

@@ -5,7 +5,7 @@ services: container-apps
 author: craigshoemaker
 ms.service: azure-container-apps
 ms.topic:  how-to
-ms.date: 04/07/2025
+ms.date: 03/31/2026
 ms.author: cshoe
 ---
 
@@ -152,14 +152,21 @@ Azure Functions on Container Apps integrate seamlessly with Azure’s observabil
 - **Custom logging:** Supports standard frameworks like ILogger and console logging for structured output.  
 - **Centralized monitoring:** Container Apps environment offers unified dashboards and alerts across all apps.
 
+
+## Environment variables
+
+Azure Functions running on Container Apps have access to system-provided environment variables. The `CONTAINER_NAME` environment variable is automatically set to the replica name for your function app. Use this variable for logging, correlation, and debugging in multi-replica scenarios.
+
+For a full list of system-provided environment variables, see [Environment variables in Azure Container Apps](environment-variables.md).
+
 ## Considerations
 
 Keep these other considerations in mind when using Azure Functions on Azure Container Apps:
 
 - **Ingress Requirement for Auto-Scaling**: To enable automatic scaling based on events, [ingress must be enabled](../container-apps/ingress-how-to.md)—either publicly or within the Container Apps internal environment.
 - **Mandatory Storage Account**: Every Functions app deployed on Container Apps must be linked to a storage account. This is required for managing triggers, logs, and state. Review the [storage account guidance](../azure-functions/storage-considerations.md) for best practices.
 - **Multi-revision storage**: When deploying with multiple active revisions, assign a dedicated storage account to each revision. Using a dedicated storage account helps prevent conflicts and ensures proper isolation. Alternatively, if you do not require concurrent revisions, consider using the default single revision mode for simplified management.
-- **Multi-revision triggers**: If you are using multi-revision mode with a pull-based trigger, use a different event source for each revision to avoid conflicts related to competing consumers. Functions that use Azure Queue Storage, Azure Event Hub, Azure Service Bus, or Durable Functions triggers are examples of pull-based triggers.
+- **Multi-revision triggers**: If you are using multi-revision mode with a pull-based trigger, use a different event source for each revision to avoid conflicts related to competing consumers. Functions that use Azure Queue Storage, Azure Event Hubs, Azure Service Bus, or Durable Functions triggers are examples of pull-based triggers.
 - **Cold start latency**: When your container app scales in to zero during idle periods, the first request after inactivity experiences a cold start. Learn more about [reducing cold start times](../container-apps/cold-start.md).
 - **Application insights integration**: For robust monitoring and diagnostics, link your Functions app to Application Insights. For more information, see [App Insights integration with Functions](../azure-functions/configure-monitoring.md?tabs=v2#enable-application-insights-integration).
 - **Functions proxies**: Not supported. For API gateway scenarios, integrate with Azure API Management instead.

articles/container-apps/jobs.md

@@ -5,7 +5,7 @@ services: container-apps
 author: craigshoemaker
 ms.service: azure-container-apps
 ms.topic: concept-article
-ms.date: 01/28/2026
+ms.date: 03/31/2026
 ms.author: cshoe
 ms.custom:
   - build-2023
@@ -607,6 +607,13 @@ To configure advanced settings by using the Azure portal, create the job as desc
 
 ---
 
+## Job networking and app-to-app communication
+
+When a job pod starts, sidecar containers (such as the Envoy proxy) are guaranteed to be ready before the main job container begins execution. This ensures that app-to-app calls made by the job at startup succeed without connection failures.
+
+> [!NOTE]
+> If your job makes calls to other container apps at startup, you don't need to add retry logic for initial sidecar readiness. The platform handles this automatically.
+
 ## Jobs restrictions
 
 The following features aren't supported:

articles/container-apps/manage-secrets.md

@@ -5,7 +5,7 @@ services: container-apps
 author: craigshoemaker
 ms.service: azure-container-apps
 ms.topic: how-to
-ms.date: 02/28/2025
+ms.date: 03/31/2026
 ms.author: cshoe
 ms.custom:
   - devx-track-azurecli
@@ -587,6 +587,18 @@ Mounting secrets as a volume isn't supported in PowerShell.
 
 ---
 
+## Troubleshoot Key Vault references
+
+When you reference secrets from Azure Key Vault, you might encounter issues during secret retrieval or synchronization. Here are common errors and resolutions:
+
+| Error | Cause | Resolution |
+|-------|-------|-----------|
+| Managed identity not enabled | The container app doesn't have a managed identity assigned. | Enable system-assigned or user-assigned managed identity on your container app. See [Managed identities](managed-identity.md). |
+| Identity not found | The specified managed identity doesn't exist or isn't assigned to the container app. | Verify the identity is created and assigned to the container app in the **Identity** section. |
+| Secret disabled in Key Vault | The secret is disabled in the Key Vault resource. | Go to your Key Vault in the Azure portal and enable the secret. |
+| Authentication failed | The managed identity lacks the required permissions to read the secret. | Grant the **Key Vault Secrets User** role to the managed identity on your Key Vault. See [Key Vault Secrets User](/azure/role-based-access-control/built-in-roles/security#key-vault-secrets-user). |
+| RBAC permission denied | The managed identity has insufficient permissions to access the Key Vault. | Verify the RBAC role assignment on the Key Vault and ensure it includes read permissions for secrets. |
+
 ## Next steps
 
 > [!div class="nextstepaction"]

articles/container-apps/metrics.md

@@ -5,7 +5,7 @@ services: container-apps
 author: craigshoemaker
 ms.service: azure-container-apps
 ms.topic: how-to
-ms.date: 04/28/2025
+ms.date: 03/31/2026
 ms.author: cshoe
 ---
 
@@ -17,7 +17,7 @@ The metrics explorer in the Azure portal allows you to visualize the data. You c
 
 ## Available metrics
 
-Container Apps provides these basic metrics.
+Container Apps provide these basic metrics.
 
 | Title | Dimensions | Description | Metric ID | Unit |
 |--|--|--|--|--|
@@ -26,7 +26,7 @@ Container Apps provides these basic metrics.
 | Network In Bytes | Replica, Revision | Network received bytes | `RxBytes` | Bytes |
 | Network Out Bytes | Replica, Revision | Network transmitted bytes | `TxBytes` | Bytes |
 | Replica count | Revision | Number of active replicas | `Replicas` | Count |
-| Total Replica Restart Count | Replica, Revision | Total number of restarts since the replica came online | `RestartCount` | Count |
+| Total Replica Restart Count | Replica, Revision | Total number of restarts for app container instances only, excluding platform-managed sidecar containers | `RestartCount` | Count |
 | Requests | Replica, Revision, Status Code, Status Code Category | Requests processed | `Requests` | Count |
 | Reserved Cores | Revision | Number of reserved cores for container app revisions | `CoresQuotaUsed` | Count |
 | Resiliency Connection Timeouts | Revision | Total connection timeouts | `ResiliencyConnectTimeouts` | Count |

articles/container-apps/opentelemetry-agents.md

@@ -4,7 +4,7 @@ description: Learn to record and query data collected using OpenTelemetry in Azu
 services: container-apps
 author: craigshoemaker
 ms.service: azure-container-apps
-ms.date: 03/30/2026
+ms.date: 03/31/2026
 ms.author: cshoe
 ms.topic: how-to
 ms.custom:
@@ -747,7 +747,7 @@ For more information, see [Microsoft.App/managedEnvironments](/azure/templates/m
 
 ## Data resilience
 
-In the event of a messaging inturruptions to an endpoint, the OpenTelemetry agent uses the following procedure to support data resilience: 
+In the event of a messaging interruption to an endpoint, the OpenTelemetry agent uses the following procedure to support data resilience: 
 
 - **In-memory buffering and retries**: The agent holds data in memory and keeps retrying (with backoff) for up to five minutes.
 - **Dropping data**: If the buffered queue fills up, or the endpoint is still down after retries, the agent discards the oldest batches to avoid running out of memory.
@@ -824,6 +824,11 @@ These resources are managed by Microsoft and don't appear in your billing or res
 
     Agent status and health metrics aren't currently exposed. This capability is planned for a future release.
 
+
+## Custom DNS configuration
+
+The managed OpenTelemetry collector respects custom DNS configuration in your Container Apps environment. If you've configured custom DNS settings, the collector automatically uses those settings for name resolution when connecting to external endpoints. This ensures that your OpenTelemetry data is routed correctly through your network infrastructure.
+
 ## Next steps
 
 > [!div class="nextstepaction"]

articles/container-apps/troubleshoot-image-pull-failures.md

@@ -5,7 +5,7 @@ services: container-apps
 author: craigshoemaker
 ms.service: azure-container-apps
 ms.topic: how-to
-ms.date: 01/24/2025
+ms.date: 03/31/2026
 ms.author: cshoe
 ms.custom:
 ---
@@ -45,3 +45,50 @@ The Container Apps diagnostics features an intelligent and interactive experienc
     You can also look at the image pull failures per revision in the last 24 hours, by selecting the required revision from the dropdown.  
 
     To view the number of image pull failures per revision for your container app, select **Click to show**.  
+
+## Image pull validation
+
+Image pull validation is only performed when the container image reference changes during an update. When you update your container app with the same image reference, the validation process is skipped and the deployment proceeds without re-validating the image. This optimization reduces deployment time for unchanged images.
+
+If you need to validate an image again, you can modify the image tag or reference and then update your container app to trigger the validation.
+
+## Resolving image pull failures
+
+### Step 1: Verify the image exists
+
+To verify that the image exists in the registry:
+
+1. Use a Docker client to pull the image from the registry manually.
+1. Confirm the exact image name and tag.
+1. Verify that the image tag exists in the registry.
+
+### Step 2: Check authentication credentials
+
+If you're using a private registry:
+
+1. Verify that the registry credentials (username and password) are correct.
+1. Confirm that the credentials haven't expired.
+1. Ensure that the identity pulling the image has permission to access the registry.
+1. For Azure Container Registry, verify that the managed identity has the **AcrPull** role assigned.
+
+### Step 3: Verify network connectivity
+
+To verify network connectivity between Azure Container Apps and the registry:
+
+1. Confirm that your Container Apps environment can reach the registry.
+1. Check DNS resolution for the registry FQDN.
+1. Verify firewall and network security group rules aren't blocking access.
+1. If using a private endpoint, ensure it's properly configured and accessible.
+
+### Step 4: Check rate limits
+
+If you suspect rate limiting:
+
+1. Wait a few minutes before attempting to pull the image again.
+1. For Docker Hub, consider using a paid account or implementing a registry mirror.
+1. If using Azure Container Registry, check the registry's quotas and limits.
+
+## Related content
+
+- [Containers in Azure Container Apps](containers.md)
+- [Managed identities in Azure Container Apps](managed-identity.md)

articles/container-apps/troubleshooting.md

@@ -5,7 +5,7 @@ services: container-apps
 author: craigshoemaker
 ms.service: azure-container-apps
 ms.topic: how-to
-ms.date: 02/03/2025
+ms.date: 03/31/2026
 ms.author: cshoe
 ms.custom:
 ---
@@ -29,6 +29,7 @@ The following table lists issues you might encounter while using Azure Container
 | Responses not as expected | The container app endpoint responds to requests, but the responses aren't as expected. | [Verify traffic is routed to the correct revision](#verify-traffic-is-routed-to-the-correct-revision)<br><br>[Verify you're using unique tags when deploying images to the container registry](/azure/container-registry/container-registry-image-tag-version) |
 | Missing parameters error | You receive error messages about missing parameters when you run `az containerapp` commands in the Azure CLI, or run cmdlets from the `Az.App` module in Azure PowerShell. | [Verify latest version of Azure Container Apps extension is installed](#verify-latest-version-of-azure-container-apps-extension-is-installed) |
 | Preview features not available | [Preview features](./whats-new.md) are not available when you run `az containerapp` commands in the Azure CLI. | [Verify Azure Container Apps extension allows preview features](#verify-azure-container-apps-extension-allows-preview-features) |
+| Key Vault secret sync error | You're unable to retrieve or synchronize secrets from Azure Key Vault. | [Troubleshoot Key Vault references](./manage-secrets.md#troubleshoot-key-vault-references) |
 | Deleting your app or environment doesn't work | This issue is often accompanied by a message such as **provisioningState: ScheduledForDelete**.  | [Manually delete the associated VNet](#manually-delete-the-vnet-being-used-by-the-azure-container-apps-environment) |
 
 ## View logs