Merge pull request #293212 from craigshoemaker/aca/troubleshooting

[Container Apps] Add troubleshooting guides

Author: v-shils

articles/container-apps/TOC.yml

@@ -143,7 +143,23 @@
         - name: With a job
           href: tutorial-event-driven-jobs.md
     - name: Troubleshooting
-      href: troubleshooting.md
+      items:
+        - name: Overview
+          href: troubleshooting.md
+        - name: Errors and failures
+          items:
+          - name: Container create
+            href: troubleshoot-container-create-failures.md
+          - name: Open Container Initiative (OCI)
+            href: troubleshoot-open-container-initiative-errors.md
+          - name: Health probe
+            href: troubleshoot-health-probe-failures.md
+          - name: Image pull
+            href: troubleshoot-image-pull-failures.md
+          - name: Storage mount
+            href: troubleshoot-storage-mount-failures.md
+          - name: Target port
+            href: troubleshoot-target-port-settings.md
     - name: Reliability in Azure Container Apps
       href: ../reliability/reliability-azure-container-apps.md?toc=/azure/container-apps/toc.json&bc=/azure/container-apps/breadcrumb/toc.json
 - name: Observability

articles/container-apps/media/troubleshooting/port-mismatch.png

@@ -0,0 +1,47 @@
+---
+title: Troubleshoot container create failures in Azure Container Apps
+description: Learn to troubleshoot container create failures in Azure Container Apps
+services: container-apps
+author: craigshoemaker
+ms.service: azure-container-apps
+ms.topic: how-to
+ms.date: 01/24/2025
+ms.author: cshoe
+ms.custom:
+---
+
+# Troubleshoot container create failures in Azure Container Apps
+
+Container exit events indicate that a container is stopped or exited. These exit events can significantly impact the availability, stability, and performance of your container app. The underlying issues that trigger these events can potentially lead to downtime or degraded service. Each event is recorded to provide insights into the container's lifecycle, helping you diagnose issues related to the container's execution.
+
+When a container exits, it could exit with a nonzero exit code (indicating failure) or a zero exit code (indicating a normal exit). Azure logs each exit event to give you visibility into what happened during the container's run.
+
+## Causes
+
+The following list details different reasons your application can experience container exit events:
+
+- **Application crash or exception**: If the application inside the container encounters an error or exception that it can't recover from, the error can cause the container to exit. Application errors are among the most common reasons for container exit events.
+
+- **Out of memory (OOM) errors**: If the container consumes more memory than the allocated limit, the system might kill the container due to out-of-memory (OOM) errors.
+
+- **Incorrect exit code or misconfiguration in the container**: The container might exit intentionally (but improperly) if the application inside the container exits with a nonzero exit code, indicating an abnormal termination. Additionally, misconfigurations in the container can lead to immediate container shutdown. Misconfigurations that affect the app include missing environment variables, incorrect startup command, or invalid container entry point.  
+
+- **Application termination (normal exit)**: A container might exit normally as the application inside completes its task, for example a batch job or a one-off process. This exit condition is expected behavior when the container is configured for short-lived tasks or single-use jobs.
+
+## Diagnostics
+
+The Container Apps diagnostics features an intelligent and interactive experience that helps you troubleshoot your app with no configuration required. Use the following steps to access Azure Container Apps diagnostics.
+
+1. Go to your container app in the Azure portal.
+
+1. Select **Diagnose and solve problems**.
+
+1. Under the troubleshooting categories, select the **Availability and Performance** category tile.
+
+1. Select **Container Exit Events** to diagnose and troubleshoot the issue.
+
+    This report provides details on the issue, possible causes, and recommended resolutions.
+
+    To view the container exit events per revision in the last 24 hours, select the required revision from the dropdown. You can also look at the exit code the container app reported as it terminated.  
+
+    To see the number of container exit events per revision, select **Click to show**.  

articles/container-apps/troubleshoot-container-create-failures.md

@@ -0,0 +1,49 @@
+---
+title: Troubleshoot health probe failures in Azure Container Apps
+description: Learn to troubleshoot health probe failures in Azure Container Apps
+services: container-apps
+author: craigshoemaker
+ms.service: azure-container-apps
+ms.topic: how-to
+ms.date: 01/24/2025
+ms.author: cshoe
+ms.custom:
+---
+
+# Troubleshoot health probe failures in Azure Container Apps
+
+Health probe failures for in Azure Container Apps indicates that the container app doesn't pass the required health checks and could be considered unhealthy or unready.
+
+Health Probes are a great way to determine application health. Specifically, health probes help work around performance issues related to timeouts during container startup, deadlocks when running the container, and serving traffic when the container is not ready to accept traffic.
+
+## Causes
+
+Factors related to the container configuration and environments that can lead to a health probe failures include::
+
+- **Incorrect health probe configuration**: Configuration errors surrounding protocols, endpoint addresses, paths, ports, and response codes result in probe failures and mark the container as unhealthy.
+
+- **Application not ready or not responding**: The application inside the container might not be ready to serve traffic when the health probe attempts its check. Delays could be due to slow initialization, long startup times, or missing dependencies. In this case, the readiness probe fails, and the container might be marked as not ready to handle traffic.
+
+- **Unreachable health check endpoint**: If the health check endpoint (such as `/health` or `/readiness`) isn't correctly exposed, or the application isn't listening on the correct port, the health probe can't access the endpoint. In this case, the probe fails because it can't reach the endpoint.
+
+## Diagnostics
+
+The Container Apps diagnostics features an intelligent and interactive experience that helps you troubleshoot your app with no configuration required. Use the following steps to access Azure Container Apps diagnostics.
+
+1. Go to your container app in the Azure portal.
+
+1. Select **Diagnose and solve problems**.
+
+1. Under the troubleshooting categories, select the **Availability and Performance** category tile.
+
+1. In the left navigation of the *Availability and Performance* section, select **Health Probe Failures**.
+
+    This report provides details on the issue, possible causes, and recommended resolutions.
+
+    You can review health probe failure events by revision by selecting the required revision of your container app.  
+
+    From this page you can view health probe failure events per revision by health probe type, inside a time frame, and by failure type.
+
+    You can also review the health probe configuration per revision for your container app by selecting the required revision from the dropdown.
+
+    To view the number of storage mount failures per revision, select **Click to show**.

articles/container-apps/troubleshoot-health-probe-failures.md

@@ -0,0 +1,47 @@
+---
+title: Troubleshoot image pull failures in Azure Container Apps
+description: Learn to troubleshoot image pull failures in Azure Container Apps
+services: container-apps
+author: craigshoemaker
+ms.service: azure-container-apps
+ms.topic: how-to
+ms.date: 01/24/2025
+ms.author: cshoe
+ms.custom:
+---
+
+# Troubleshoot image pull failures in Azure Container Apps
+
+If Azure can't pull the container image from the specified registry, the container can't be created or executed, leading to a failure in launching the application. An image pull failure is when the Azure platform is unable to download (described as a "pull") the container image required by the application.
+
+## Causes
+
+The following list details possible causes for image pull failures:
+
+- **Incorrect image name or tag**: This error occurs when the image name or tag specified in the configuration is incorrect or misspelled. These errors could include incorrect image repository names, the image tags, or the image version.
+
+- **Authentication issues (private registry)**: If the image is stored in a private registry like Azure Container Registry or a private Docker Hub registry, you need to make sure you provide proper authentication credentials to pull the image. If these credentials are missing, incorrect, or expired, the pull operation fails.
+
+- **Registry unavailability or network issues**: If the container registry is down or unreachable (due to network issues or misconfiguration), then the pull request doesn't complete successfully. This failure could also stem from DNS issues, firewalls, or connectivity problems between Azure Container Apps and the registry. When there are network issues, the image can't pull from the registry, causing the container creation to fail.
+
+- **Rate limits or quota exceeded**: Many container registries, including Docker Hub, enforce rate limits on how frequently images can be pulled. If the rate limit or quota is exceeded (for example, too many image pulls in a short period), the image pull is temporarily blocked. When the pull is blocked, the container doesn't start because Azure Container Apps can't retrieve the image which blocks the deployment.
+
+- **Image not found**: This failure could happen if the image doesn't exist, or if the wrong tag or repository is specified.
+
+## Diagnostics
+
+The Container Apps diagnostics features an intelligent and interactive experience that helps you troubleshoot your app with no configuration required. Use the following steps to access Azure Container Apps diagnostics.
+
+1. Go to your container app in the Azure portal.
+
+1. Select **Diagnose and solve problems**.
+
+1. Under the troubleshooting categories, select the **Availability and Performance** category tile.
+
+1. In the left navigation, select **Image Pull Failures** to diagnose and troubleshoot the issue.
+
+    This report provides details on the issue, possible causes, and recommended resolutions.
+
+    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**.  

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

@@ -0,0 +1,53 @@
+---
+title: Troubleshooting Open Container Initiative (OCI) errors in Azure Container Apps
+description: Learn to troubleshoot aOpen Container Initiative (OCI) errors in Azure Container Apps
+services: container-apps
+author: craigshoemaker
+ms.service: azure-container-apps
+ms.topic: how-to
+ms.date: 01/24/2025
+ms.author: cshoe
+ms.custom:
+---
+
+# Troubleshoot Open Container Initiative (OCI) errors in Azure Container Apps
+
+An Open Container Initiative (OCI) runtime error is a failure in the container runtime during the execution or creation of a container. Failures can occur at any point in the container lifecycle, such as pulling the image, creating the container, or starting the container.
+
+A container create failure happens when the container fails to initialize, pull the image, or run properly. An OCI runtime error directly contributes to this failure as it often occurs during the container creation phase.
+
+For example:
+
+- The container runtime might fail to instantiate the container due to an issue with the image or environment.
+
+- The container might fail to execute required steps required during startup (such as mounting volumes or accessing network interfaces).
+
+## Causes
+
+Possible causes of OCI runtime errors include:
+
+- **Corrupt or invalid image**: If the container image is corrupt, incomplete, or incompatible with the host environment, the runtime might fail to start the container.
+
+- **Incompatible image architecture**: If the image is built for a different architecture (for example, ARM vs. x86), the runtime might be unable to create the container.
+
+- **Incorrect or missing configuration files**: If there are incorrect Dockerfile settings, missing environment variables or missing required configuration files, the container might cause the runtime to fail during startup.
+
+- **Incorrect volume mounts**: The container might fail to mount volumes if the path or permission settings are incorrect, causing a runtime failure.
+
+- **Network configuration errors**: Incorrect networking settings (such as invalid bridge networks) might result in an error.
+
+## Diagnostics
+
+The Container Apps diagnostics features an intelligent and interactive experience that helps you troubleshoot your app with no configuration required. Use the following steps to access Azure Container Apps diagnostics.
+
+1. Go to your container app in the Azure portal.
+
+1. Select **Diagnose and solve problems**.
+
+1. Under the troubleshooting categories, select the **Availability and Performance** category tile.  
+
+1. In the left navigation of the *Availability and Performance* category, select **Container Create Failures**. The information returned provides details on the error along with recommended actions to resolve the issue and more troubleshooting information.  
+
+    By selecting the required revision from the dropdown, you can inspect any container create failure events per revision in the last 24 hours.
+
+    You can also look at the number of containers create failures per revision for your container app, by selecting **Click to show**.

articles/container-apps/troubleshoot-open-container-initiative-errors.md

@@ -0,0 +1,45 @@
+---
+title: Troubleshoot storage mount failures in Azure Container Apps
+description: Learn to troubleshoot storage mount failures in Azure Container Apps
+services: container-apps
+author: craigshoemaker
+ms.service: azure-container-apps
+ms.topic: how-to
+ms.date: 01/24/2025
+ms.author: cshoe
+ms.custom:
+---
+
+# Troubleshoot storage mount failures in Azure Container Apps
+
+Azure Container Apps allow containers to interact with external storage systems, such as Azure Files, Azure Blob Storage, or Azure Managed Disks, for persisting data. These storage resources are mounted to the container's file system during container startup.
+
+Storage mount failures occur when your app's container is unable to successfully mount or access required storage resources, such as volumes or file systems.
+
+## Causes
+
+- **Incorrect configuration of storage mounts**: This error occurs when the configuration settings for mounting a storage resource (such as a volume, Azure Files share, or blob) are incorrect.
+
+- **Invalid or expired credentials**: This error occurs when the authentication credentials are invalid, expired, or misconfigured.
+
+- **Misconfigured storage class or mount type**: If a container app is configured to use a storage class or mount type incompatible with the storage system or configuration, the mount fails.
+
+- **Storage resource deletion or modification**: This error occurs when the storage resource (for example, an Azure Files share or disk) is deleted or modified while the container app is running.
+
+## Diagnostics
+
+The Container Apps diagnostics features an intelligent and interactive experience that helps you troubleshoot your app with no configuration required. Use the following steps to access Azure Container Apps diagnostics.
+
+1. Go to your container app in the Azure portal.
+
+1. Select **Diagnose and solve problems**.
+
+1. Under the troubleshooting categories, select the **Availability and Performance** category tile.
+
+1. From the left navigation, select **Storage Mount Failures** to diagnose and troubleshoot the issue.
+
+    This report provides details on the issue, possible causes, and recommended resolutions.
+
+    By selecting the required revision from the dropdown, you can view storage mount failure events in the last 24 hours, and the storage mount configuration per revision for your container app.
+
+    Additionally, you can find the number of storage mount failures per revision for your container app, by selecting **Click to show**.

articles/container-apps/troubleshoot-storage-mount-failures.md

@@ -0,0 +1,47 @@
+---
+title: Troubleshoot target port settings in Azure Container Apps
+description: Learn to troubleshoot target port settings in Azure Container Apps
+services: container-apps
+author: craigshoemaker
+ms.service: azure-container-apps
+ms.topic: how-to
+ms.date: 01/24/2025
+ms.author: cshoe
+ms.custom:
+---
+
+# Troubleshoot target port settings in Azure Container Apps
+
+Incorrect target port settings in a container app prevent incoming requests from reaching the correct port where the container listens for traffic. This port mismatch stops the container app from routing external traffic to the right application inside the container. Such misconfiguration can cause app downtime or delays in serving requests, reducing service availability. Additionally, if the app scales and the target port is misconfigured, new instances might not function correctly, negatively impacting overall performance and scalability.
+
+## Causes
+
+- **Port not exposed in dockerfile or app configuration**: This error comes when there's a mismatch between the container configuration and the port where the application is listening. For instance, if:
+
+  - The container configurations don't expose the required port using the `EXPOSE` directive.
+
+  - The containerized application inside the app isn't configured to listen on the container app's expected routing or networking port.
+
+    Then the ports are mismatched. For example, the container might be configured to listen on port `8080`, but the container app is expecting it to be on port `80`.
+
+- **Multiple containers and service ports conflicts**: In a scenario where multiple containers are running in the same app, there could be conflicts between different services trying to use the same port. Ensuring that each service listens to a unique port or that the routing is configured correctly is essential.
+
+## Diagnostics
+
+The Container Apps diagnostics features an intelligent and interactive experience that helps you troubleshoot your app with no configuration required. Use the following steps to access Azure Container Apps diagnostics.
+
+1. Go to your container app in the Azure portal.
+
+1. Select **Diagnose and solve problems**.
+
+1. Under the troubleshooting categories, select the **Availability and Performance** category tile.
+
+1. In the left navigation, select **Container Apps Ingress Port settings check** to diagnose and troubleshoot the issue.
+
+    Select the required revision of your container app from the dropdown. The latest revision would be populated by default.
+
+    :::image type="content" source="media/troubleshooting/port-mismatch.png" alt-text="Screenshot of port mismatch report.":::
+
+    This report provides details on the issue, possible causes, and recommended resolutions.
+
+    These errors are only raised when the container app is trying to start or scale. Therefore, if the tool doesn't find any issues during a given period, try running the detector during a time when you know the container app is expected to start or scale. In the case when the app isn't receiving any traffic, try to browse the issue or trigger it.