so i will be using this repository to test my new idea of ARM templates / bicep deployments ; and i will be shifting my medical chatbot project to azure ;
📄 Azure Deployment Architecture & Troubleshooting Guide Overview This project utilizes a fully automated CI/CD pipeline via GitHub Actions to deploy a Dockerized Flask application. The infrastructure is defined as code using Azure Bicep, deploying to Azure Container Registry (ACR) and Azure Container Apps (ACA).
Authentication Security We use OpenID Connect (OIDC) via Azure Managed Identities (Service Principals) for GitHub Actions. There are no static passwords or secrets stored in GitHub, ensuring zero-trust security. The pipeline generates short-lived tokens on the fly.
🏗️ The Deployment Flow (The "Split Responsibility" Pattern) Azure Container Apps has a known race condition when provisioning an app, assigning it a Managed Identity, and linking it to a private ACR simultaneously. To prevent the deployment from hanging ("Operation Expired"), we split the deployment into two distinct phases:
Phase 1: Infrastructure Provisioning (Bicep)
Bicep provisions the ACR and the ACA Environment.
Bicep provisions the Container App using a public placeholder image (mcr.microsoft.com/azuredocs/containerapps-helloworld:latest) mapped to Port 80. Note: We deliberately omit the registries configuration here to avoid validation timeouts.
Bicep enables a SystemAssigned Managed Identity for the Container App.
Bicep grants the new Managed Identity the AcrPull role, scoped to the ACR.
Phase 2: Code Deployment & Configuration (GitHub Actions CLI)
The pipeline logs into the newly created ACR and pushes the fresh Flask Docker image.
The pipeline uses Azure CLI to bind the ACR to the Container App using the Managed Identity (az containerapp registry set).
The pipeline updates the Container App to pull the new Flask image.
The pipeline updates the ingress target port from 80 to 5000 so the Flask app registers as healthy.
The "Chicken and Egg" Bicep Hang: Never add the registries block directly into the initial Bicep containerApp resource. Azure will try to validate the ACR credentials before the IAM role assignment propagates, resulting in a 20+ minute deployment timeout.
The Port Health-Check Timeout: When Bicep provisions the initial placeholder image, the port must be 80. If it is set to 5000 initially, Azure's health checks will fail on the placeholder, and the provisioning state will hang indefinitely. The switch to port 5000 must happen via the CLI in the final pipeline step.
Student Account Region Locks (RequestDisallowedByAzure): Azure heavily restricts which regions Student Accounts can deploy to based on current server capacity. If a deployment fails due to policy restrictions, check the "Allowed Locations" policy in the Azure Portal to find an unlocked region (e.g., centralindia, eastus) and recreate the Resource Group there.
Duplicate Resource Definitions: You cannot define the same Microsoft.App/containerApps resource twice in a Bicep file to try and patch it. Bicep will fail with a duplicate resource error. Always use the Azure CLI in the pipeline for post-provisioning patches.