Azure Web Apps

Azure Web Apps

Overview

Azure App Service is the Platform-as-a-Service (PaaS) offering for hosting web applications, REST APIs, and mobile backends on Azure. It provides managed compute, built-in load balancing, automatic patching, and integrated CI/CD. App Service supports multiple runtime stacks (.NET, Node.js, Python, Java, PHP, Ruby) and containerized workloads.

Key benefits: zero-downtime deployments via deployment slots, horizontal auto-scaling, managed SSL certificates, VNet integration for private networking, and managed identity for passwordless authentication to Azure resources.

ARM REST API Endpoints

Base URL: https://management.azure.com API Version: 2023-12-01

All endpoints require the header Authorization: Bearer <token> with scope https://management.azure.com/.default.

App Service Plans

Create App Service Plan body:

{
  "location": "eastus",
  "sku": {
    "name": "S1",
    "tier": "Standard",
    "capacity": 1
  },
  "kind": "linux",
  "properties": {
    "reserved": true
  }
}

Set kind: "linux" and reserved: true for Linux plans. Omit both for Windows plans.

Web Apps

Create Web App body:

{
  "location": "eastus",
  "properties": {
    "serverFarmId": "/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Web/serverfarms/{planName}",
    "siteConfig": {
      "linuxFxVersion": "NODE|20-lts",
      "appSettings": [
        { "name": "WEBSITE_NODE_DEFAULT_VERSION", "value": "~20" }
      ],
      "alwaysOn": true,
      "http20Enabled": true,
      "minTlsVersion": "1.2"
    },
    "httpsOnly": true
  },
  "identity": {
    "type": "SystemAssigned"
  }
}

Windows runtime versions: DOTNET|v8.0, NODE|20, PYTHON|3.12, JAVA|17-java17. Linux runtime versions: DOTNETCORE|8.0, NODE|20-lts, PYTHON|3.12, JAVA|17-java17.

Deployment Slots

Swap slots body:

{
  "targetSlot": "production",
  "preserveVnet": true
}

App Settings

Update app settings body:

{
  "properties": {
    "DB_CONNECTION": "@Microsoft.KeyVault(VaultName=myvault;SecretName=db-conn)",
    "APPINSIGHTS_INSTRUMENTATIONKEY": "xxx-xxx",
    "WEBSITE_RUN_FROM_PACKAGE": "1"
  }
}

Custom Domains

Bind custom domain body:

{
  "properties": {
    "hostNameType": "Verified",
    "sslState": "SniEnabled",
    "thumbprint": "<certificate-thumbprint>"
  }
}

TLS Certificates

Deployment Methods

GitHub Actions (OIDC Federated Credential)

The recommended CI/CD approach uses OIDC federated credentials — no secrets stored in GitHub.

1. Create an Azure AD app registration with federated credential for GitHub Actions.
2. Assign the app the Website Contributor role on the App Service.
3. Configure GitHub secrets: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID.
4. Use azure/login@v2 with client-id, tenant-id, subscription-id.
5. Use azure/webapps-deploy@v3 to deploy.

ZIP Deploy

az webapp deploy --resource-group <rg> --name <app-name> --src-path ./app.zip --type zip

Or via REST API:

POST https://<app-name>.scm.azurewebsites.net/api/zipdeploy
Content-Type: application/zip
Authorization: Basic <deployment-credentials>
Body: <zip-file-binary>

Docker Container

{
  "properties": {
    "siteConfig": {
      "linuxFxVersion": "DOCKER|myregistry.azurecr.io/myimage:latest",
      "acrUseManagedIdentityCreds": true
    }
  }
}

Local Git

Enable local Git deployment and push to the App Service Git remote:

az webapp deployment source config-local-git --name <app-name> --resource-group <rg>
git remote add azure <git-url-from-output>
git push azure main

Managed Identity & Key Vault

System-Assigned Managed Identity

Enable via ARM: "identity": { "type": "SystemAssigned" }. The response includes principalId and tenantId.

Key Vault References in App Settings

Instead of storing secrets directly in app settings, reference Azure Key Vault:

@Microsoft.KeyVault(VaultName=myvault;SecretName=db-connection-string)
@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/db-connection-string/abc123)

Prerequisites:

1. Enable managed identity on the App Service.
2. Grant the identity Key Vault Secrets User role on the Key Vault.
3. Use the @Microsoft.KeyVault(...) syntax in app settings.

Application Insights

Auto-Instrumentation

For supported runtimes (.NET, Node.js, Java, Python), enable auto-instrumentation via app settings:

{
  "APPLICATIONINSIGHTS_CONNECTION_STRING": "InstrumentationKey=xxx;IngestionEndpoint=https://xxx.applicationinsights.azure.com/",
  "ApplicationInsightsAgent_EXTENSION_VERSION": "~3"
}

Availability Tests

Configure URL ping tests to monitor uptime from multiple Azure regions.

Networking

VNet Integration

Connect the App Service to an Azure Virtual Network for access to private resources:

{
  "properties": {
    "virtualNetworkSubnetId": "/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Network/virtualNetworks/{vnet}/subnets/{subnet}"
  }
}

Requires a dedicated subnet with at least /26 address space.

Private Endpoints

Make the app accessible only via private IP within a VNet:

{
  "properties": {
    "privateLinkResourceId": "/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Web/sites/{appName}",
    "groupIds": ["sites"]
  }
}

Access Restrictions

Allow traffic only from specific IPs or VNet subnets:

{
  "properties": {
    "ipSecurityRestrictions": [
      {
        "ipAddress": "203.0.113.0/24",
        "action": "Allow",
        "priority": 100,
        "name": "Office IP"
      }
    ]
  }
}

App Service Plan Tiers

Permissions / Scopes

Error Handling

ARM error response structure:

{
  "error": {
    "code": "ResourceNotFound",
    "message": "The Resource 'Microsoft.Web/sites/myapp' under resource group 'myrg' was not found."
  }
}

Deployment-Specific Errors

Common Patterns

Blue-Green Deployment with Slots

Zero-downtime deployment using staging slot:

1. Create a staging slot: PUT .../sites/{app}/slots/staging.
2. Deploy new version to staging: ZIP deploy or GitHub Actions targeting the staging slot.
3. Run smoke tests against https://{app}-staging.azurewebsites.net.
4. Swap staging → production: POST .../sites/{app}/slotsswap with targetSlot: "production".
5. If issues detected, swap again to rollback instantly.
6. Mark slot-specific settings (e.g., SLOT_NAME) as sticky so they don't swap.

Containerized Web App with ACR

Deploy a Docker container from Azure Container Registry:

1. Create an ACR: az acr create --name myregistry --resource-group myrg --sku Basic.
2. Build and push image: az acr build --registry myregistry --image myapp:v1 ..
3. Create web app with container: set linuxFxVersion: "DOCKER|myregistry.azurecr.io/myapp:v1".
4. Enable managed identity and grant AcrPull role on the registry.
5. Set acrUseManagedIdentityCreds: true in site config (no admin credentials needed).
6. Enable continuous deployment: ACR webhook triggers redeployment on image push.

Managed Identity + Key Vault + SQL

Secure database access without passwords:

1. Enable system-assigned managed identity on the App Service.
2. Create a Key Vault and store the SQL connection string as a secret.
3. Grant the App Service identity Key Vault Secrets User on the vault.
4. Set app setting: DB_CONNECTION=@Microsoft.KeyVault(VaultName=myvault;SecretName=sql-conn).
5. Alternatively, use Azure AD authentication for SQL: grant the managed identity db_datareader and db_datawriter roles directly in SQL Database.

GitHub Actions CI/CD with OIDC

Passwordless deployment from GitHub:

1. Create an Azure AD app registration.
2. Add a federated credential: issuer https://token.actions.githubusercontent.com, subject repo:org/repo:ref:refs/heads/main.
3. Assign Website Contributor role on the App Service.
4. In GitHub, set secrets: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID.
5. Use the azure/login@v2 action with client-id, tenant-id, subscription-id (no secret needed).
6. Deploy with azure/webapps-deploy@v3.

Best Practices

• Always enable HTTPS: Set httpsOnly: true on every web app.
• Use deployment slots for production: Never deploy directly to the production slot.
• Key Vault for secrets: Use @Microsoft.KeyVault(...) references instead of storing secrets in app settings.
• Managed identity: Use system-assigned identity for single-resource scenarios, user-assigned for shared identity across resources.
• Health check: Configure /health endpoint and set it in App Service health check settings for automatic instance replacement.
• Application Insights: Always enable for production workloads — the telemetry is invaluable for debugging.
• Auto-scale: Configure auto-scale rules on Standard tier or above for production workloads.

Reference Files

Example Files

Progressive Disclosure — Reference Files