Fixing Azure 503 When WEBSITE_RUN_FROM_PACKAGE Requires Cross‑Subscription Stora

by 
# 503 Service Unavailable Azure App Service

## Summary
**Azure App Service** returned a **503 Service Unavailable** error during deployment to a new subscription after migration. The application appeared functional locally and passed YAML validation, but failed with **"Could not download zip"**, suggesting a deployment pipeline or subscription linkage issue.

## Root Cause
- **Environment variable**: `WEBSITE_RUN_FROM_PACKAGE=1` required the deployment package to be **pre-uploaded** to Azure Storage, bypassing direct zip extraction from the CI/CD pipeline.
- **Subscription mismatch**: CI/CD job used the **new subscription** but lacked permissions to access **storage containers** tied to the **old subscription**.
- **Deployment method**: `deploymentMethod: 'auto'` assumed automation could resolve dependencies, but **cross-subscription resource access** required manual orchestration.

## Why This Happens in Real Systems
- **Legacy workflows**: CI/CD pipelines often assume storage access is scoped to the deployment subscription by default.
- **Azure Storage secrets**: Storage account keys or SAS tokens for existing packages are **not inherited** across subscriptions during migration.
- **Environment variable interactions**: `WEBSITE_RUN_FROM_PACKAGE` assumes the package exists in connected storage, which requires **separate upload steps** before deployment.

## Real-World Impact
- **Deployment failures**: Jobs returned **404 Not Found** for the zip package, triggering a **503** server error.
- **Downtime**: Zero users in staging initially, but risked **production outages** if triggered prematurely.
- **Misdiagnosis**: Teams wasted hours debugging YAML/YAML changes instead of verifying **subscription permissions** and **storage access**.

## How Senior Engineers Fix It

### ✅ Solution 1: Upload Package to Storage First
```bash
# Upload the zip to the old subscription's storage manually
az storage blob upload --container-name $(STORAGE_CONTAINER) --file $(SYSTEM_DEFAULT_WORKING_DIR)/*.zip --name $(ZIP_NAME) --subscription $(OLD_SUB_ID) --auth-mode login

✅ Solution 2: Inject Storage Key into Deploy Step

- task: AzureWebApp@1
  inputs:
    azureSubscription: 'NEW_SUB_ID'
    appType: 'webApp'
    appName: 'NewServiceApp-Prod'
    package: '$(StorageUriFromOldSub)' # Pre-configured URI from old subscription
    deploymentMethod: 'directDeployment'

✅ Solution 3: Migrate Storage Access First

  • Step 1: Re-upload the existing zip to the new subscription’s storage.
  • Step 2: Update WEBSITE_RUN_FROM_PACKAGE to reference the new subscription’s storage URI.
  • Step 3: Remove references to the old subscription in deployment jobs.

Why Juniors Miss It

  • “YAML says valid!”: Over-reliance on automated validation tools that don’t simulate Azure’s subscription isolation.
  • Environment variable magic: Unaware that WEBSITE_RUN_FROM_PACKAGE depends on existing storage metadata, not just local files.
  • Lack of cross-subscription checks: Never audited whether storage containers or secrets persisted post-migration.

Leave a Comment