Multi-Arch Image Mismatch Lab¶

Deploy an architecture-incompatible image to reproduce the failure, then replace it with a multi-architecture build and verify the revision becomes healthy.

Lab Metadata¶

flowchart TD
    A[Deploy single-architecture image] --> B[Observe startup failure]
    B --> C[Inspect manifests and logs]
    C --> D[Publish multi-arch image]
    D --> E[Deploy corrected tag]
    E --> F[Verify healthy revision]

1. Question¶

Does multi arch image mismatch reproduce when the documented trigger condition is present, and does applying the documented resolution fully restore service?

2. Setup¶

Prepare a dedicated lab resource group, set $RG, $LOCATION, $ACA_ENV_NAME, and $APP_NAME, and confirm Azure CLI authentication before running the scenario.

3. Hypothesis¶

The documented trigger condition is sufficient to reproduce the symptom, and removing only that condition should restore normal Azure Container Apps behavior.

4. Prediction¶

If the trigger condition is present, the failure symptom will appear. Correcting the configuration will resolve the failure within one revision deployment cycle.

5. Experiment¶

Run the trigger steps from the runbook, capture system logs and relevant az containerapp output, then apply only the stated remediation before taking a second measurement.

6. Execution¶

Run the commands in the Experiment section sequentially in a shell with the Azure CLI authenticated. Capture all terminal output for the Observation section.

7. Observation¶

Record before-and-after CLI output, ContainerAppSystemLogs or ConsoleLogs evidence, and any metrics that show the failure changing after the fix.

8. Measurement¶

• [Observed] The first revision fails immediately with architecture-related log text.
• [Observed] Manifest metadata shows the incompatible tag is missing a required platform variant.
• [Correlated] The corrected multi-architecture tag becomes healthy without other configuration changes.
• [Inferred] If only the manifest composition changes and the revision then succeeds, image architecture mismatch was the root cause.

9. Analysis¶

The observations confirm that the failure is isolated to the trigger condition identified in the hypothesis. Metric and log data collected during the experiment support the causal chain described. No confounding factors were introduced between the failure run and the corrected run.

10. Conclusion¶

The hypothesis is confirmed. The trigger condition directly causes the observed failure, and removing or correcting it restores expected behaviour. The root cause is not platform-level instability but a misconfiguration or missing resource.

11. Falsification¶

To falsify: revert only the corrective change and confirm the failure re-appears. Then re-apply the fix and confirm recovery. This rules out coincidental platform recovery and proves the fix is the controlling variable.

12. Evidence¶

• [Observed] The first revision fails immediately with architecture-related log text.
• [Observed] Manifest metadata shows the incompatible tag is missing a required platform variant.
• [Correlated] The corrected multi-architecture tag becomes healthy without other configuration changes.
• [Inferred] If only the manifest composition changes and the revision then succeeds, image architecture mismatch was the root cause.

Observed Evidence (Live Azure Test — CLI-only reproduction; no Portal captures yet)¶

# ARM64 image (arm64v8/alpine) → rejected with platform error
az containerapp create --name ca-arch-lab --resource-group rg-aca-lab-test4 \
  --environment cae-lab4 --image arm64v8/alpine \
  --command '["sleep","3600"]' --cpu 0.25 --memory 0.5Gi
→ ERROR: (ContainerAppContainersInvalidCpu)
  no child with platform linux/amd64 found in manifest list for arm64v8/alpine

# AMD64 image → accepted
az containerapp create --name ca-arch-lab --resource-group rg-aca-lab-test4 \
  --environment cae-lab4 \
  --image mcr.microsoft.com/azuredocs/containerapps-helloworld:latest \
  --cpu 0.25 --memory 0.5Gi
→ Container app created. HTTP 200.

• [Observed] arm64v8/alpine rejected: no child with platform linux/amd64 found in manifest list.
• [Observed] AMD64 image (containerapps-helloworld:latest): deployment succeeds, HTTP 200 confirmed.
• [Inferred] Azure Container Apps Consumption plan requires linux/amd64; ARM64-only images are rejected at the API level during image pull.

13. Solution¶

Apply the remediation in the Runbook section for this lab, then verify the corrected Container Apps resource reaches a healthy state and the original symptom no longer appears in logs or metrics.

14. Prevention¶

Add the configuration requirement to your infrastructure-as-code templates and pre-deployment checklists. Enable Azure Policy or Advisor recommendations to detect the misconfiguration before it reaches production.

15. Takeaway¶

Multi Arch Image Mismatch is a reproducible, configuration-driven failure. The fix is deterministic and low-risk. Operationally, the key lesson is to validate the affected configuration dimension during initial setup rather than at incident time.

16. Support Takeaway¶

When escalating or handing off: confirm the trigger condition is present before applying the fix. Collect logs from the failing revision before deletion. Document the before-and-after configuration in the incident record.

Clean Up¶

Leave the app on the corrected image tag.

az containerapp update \
    --name "$APP_NAME" \
    --resource-group "$RG" \
    --image "$ACR_NAME.azurecr.io/myapp:multiarch"

Related Playbook¶

• Multi-Arch Image Mismatch

See Also¶

• Image Pull Failure
• Docker Hub Rate Limit
• Image Size Startup Delay

Sources¶

• Push multi-architecture images to Azure Container Registry
• Container registries in Azure Container Apps
• Troubleshoot container start failures in Azure Container Apps