For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /docs/infrastructure/providers/azure/account-setup.md.

Azure Account Setup

Setting up Azure for tsdevstack deployments. Each environment requires its own subscription for isolation.

Warning

Check App Service quota before the first deploy. Some new subscriptions have zero quota for Basic-tier VMs, and infra:deploy then fails with Current Limit (Basic VMs): 0. See App Service Quota below.

Prerequisites

  • Azure account with portal access
  • One Azure subscription per environment (dev, staging, prod)
  • App Service plan quota in your target region (Basic/B-series)

Register Resource Providers

Azure subscriptions do not have all resource providers enabled by default. You must register every provider the framework uses before running cloud:init. This is a one-time operation per subscription.

How to Register

  1. Go to the Azure Portal
  2. Search for "Subscriptions" and click on your subscription. If you have more than one, check the Subscription ID: it must be the one in your credentials file, otherwise the providers get registered in the wrong place
  3. In the left sidebar under Settings, click Resource providers
  4. For each provider listed below:
    • Type the provider name in the search box
    • Select it from the list
    • Click Register at the top
    • The status progress message may disappear from the list. Click the bell icon (notifications) in the top-right navbar to track progress and verify registration succeeded.
    • Wait until the status shows Registered (usually under a minute)

Required Providers

Register all 12 providers:

ProviderUsed For
Microsoft.AppContainer Apps (backend services)
Microsoft.CacheAzure Cache for Redis
Microsoft.CdnAzure Front Door (CDN / load balancer)
Microsoft.ContainerRegistryContainer Registry (Docker images)
Microsoft.DBforPostgreSQLPostgreSQL Flexible Server
microsoft.insightsDiagnostic settings, Application Insights, the traces data collection rule, the dashboard workbook
Microsoft.KeyVaultKey Vault (secrets management)
Microsoft.ManagedIdentityManaged Identities for containers
Microsoft.NetworkVirtual Networks, subnets, NSGs
Microsoft.OperationalInsightsLog Analytics workspace
Microsoft.StorageStorage Accounts (Terraform state, SPA hosting)
Microsoft.WebApp Service Plans (Kong, Next.js)
Warning

The Microsoft.Web provider must be registered before you can request App Service quota (next section). The quota page will be empty without it.

App Service Quota

The framework deploys Kong on a dedicated App Service Plan. If your project includes Next.js apps, they share a second App Service Plan. App Service quota counts instances (VMs), so you need quota for every instance the plans can run. With the defaults that is 1 for Kong, plus 1 with Next.js. On a Standard or Premium plan that autoscales, count its maxInstances. See Azure App Service plans.

The default SKU is B1. If you override it to an S-series SKU in infrastructure.json, you need quota for that family instead (or both, if you mix SKUs).

Check Your Quota

  1. Go to the Azure Portal
  2. Search for "Quotas" > click My quotas
  3. Filter: Service: App Service, Location: your deployment region

What you see depends on the subscription:

  • One "Total Regional VMs" row (App Service, shown as a preview): if its limit covers your instance count, you're set. The portal says "Quota need not be requested for this SKU", and no request is needed.
  • One row per VM family (for example "B1 VMs"): if the family you need shows a limit of 0, request an increase as below.

Request an Increase

  1. In My quotas, keep the App Service filter for your region
  2. Request quota for each VM family you need:
SKU in infrastructure.jsonQuota to Request
B1, B2, B3 (default)B1/B2/B3 VMs
S1, S2, S3S1/S2/S3 VMs
P1v3, P2v3, P3v3P1v3/P2v3/P3v3 VMs
  1. Select the row (e.g., "B1 VMs", showing "0 of 0") > click Request increase
  2. Set the new limit to your instance count: Kong's instances plus the Next.js plan's (all Next.js apps share one plan). For a plan that autoscales, count its maxInstances
  3. Submit and wait for approval (usually 1-4 hours, often minutes)

If the self-service option is not available, create a support request: Help + support > + Create a support request > Issue type: "Service and subscription limits (quotas)" > Quota type: "App Service"

Azure Managed Redis Access

The framework runs Redis on Azure Managed Redis (default size Balanced_B0, set with redis.tier in infrastructure.json). Azure doesn't let every subscription create it. New pay-as-you-go subscriptions in particular can be blocked in a region until you ask, whatever size you pick. The deploy then fails with:

Creation of Azure Managed Redis with the SKU Balanced_B0 is not supported for your subscription in East US 2.
Please choose a different SKU or region. If you need access to this SKU, please contact support.

There is no API to check this ahead of time, so on a new subscription request access before your first deploy:

  1. Help + support > + Create a support request
  2. Issue type: "Service and subscription limits (quotas)"
  3. Pick the Redis quota type the form offers (Azure Managed Redis or Azure Cache for Redis)
  4. Ask for Azure Managed Redis with the size you'll use (Balanced_B0 by default) in your deployment region. If a deploy already failed, add the CorrelationID from the error.

Everything else in a deploy is created before it stops at Redis, so once access is granted, run infra:deploy again and it continues where it left off.

PostgreSQL Region Access

Azure can also block a subscription from creating a PostgreSQL Flexible Server in a region, whatever size you pick. New pay-as-you-go subscriptions are the usual case. The size list (az postgres flexible-server list-skus) and the quota page still show every size as available, so only a create shows the block. The deploy fails with:

Status: "SkuNotAvailable"
Message: "Specified SKU is not supported in this region. Please choose a different SKU."

Request access for your deployment region:

  1. Help + support > Create a support request. In the panel, describe the issue (for example "postgresql region access"), pick Service and subscription limits (quotas), then Create a support request
  2. Quota type: "Azure Database for PostgreSQL flexible server"
  3. Under Add additional details, pick Region access and your region

Access is granted per series. Name the series of every size you may use: the B-series for B_ sizes, Dsv3 or Ddsv5 for GP_ sizes, Esv3 or Edsv5 for MO_ sizes. Microsoft may enable a different series than the one you asked for, so check the reply: if your size still fails, try the same size from the other generation (for example GP_Standard_D2ds_v5 instead of GP_Standard_D2s_v3).

Microsoft answers quota requests within 24 to 48 hours. Everything created before the database stays in place: once access is granted, run infra:deploy again and it continues. The other way out is a region that isn't blocked, which needs a resource group there (Step 4).

Capacity Is Not Quota

Quota is a limit on your subscription, and you can ask for more. Capacity is whether Azure has a free machine of that size in the region right now. A size can be offered in a region, with plenty of quota left, and still fail:

Status: "RegionalAllocationFailed"
Message: "We do not have sufficient capacity for the requested compute size in this region."

A quota request doesn't help here, and no API shows capacity ahead of time. Shortages usually pass within minutes, so infra:deploy waits 5 minutes and tries again, up to 3 times. Everything created before the failure stays in place. If capacity still isn't back:

  • Run infra:deploy again later. It continues where it stopped.
  • Pick another size for the resource that failed, for example database.tier in infrastructure.json. Capacity differs between sizes.
  • Ask Azure support for capacity in your region: Help + support > + Create a support request.

App Service Plans

App Service plans (Kong, Next.js) can be short of machines too:

No available instances to satisfy this request. App Service is attempting to increase capacity. Please retry your request later

infra:deploy doesn't retry this one. Every App Service plan create that fails counts toward an Azure limit: after too many creates or failed creates in a short time, Azure refuses plan creates for the subscription in that region:

App Service Plan Create operation is throttled for subscription ... Please contact support if issue persists.

(extended code 51025). Azure documents no duration; its support answers mention up to 48 hours. So when a plan is short of machines:

  • Pick another size: appService.kongSku or appService.nextjsSku in infrastructure.json (for example B2), then run infra:deploy again.
  • Don't run it again and again with the same size.

When the limit has hit, don't run infra:deploy again until it lifts: every attempt counts. Ask Azure support to lift it (Help + support > + Create a support request, with the subscription, the region, code 51025 and the time), or wait. Everything created so far stays in place, and the next deploy continues where it stopped. A different subscription isn't affected.

Step 1: Create App Registration

  1. Go to Azure Portal > search "Microsoft Entra ID"
  2. Under Manage, click App registrations > + New registration
  3. Name: {projectName}-{env} (e.g., myapp-dev)
  4. Supported account types: "Single tenant" (Accounts in this organizational directory only)
  5. Redirect URI: Leave blank
  6. Click Register

From the Overview page, copy:

  • Application (client) ID > this is clientId
  • Directory (tenant) ID > this is tenantId

Step 2: Create Client Secret

  1. Click on your App Registration from the list to open it
  2. In the left sidebar under Manage, click Certificates & secrets
  3. Click + New client secret
  4. Description: {projectName}-{env}-key (e.g., myapp-dev-key)
  5. Expires: 24 months
  6. Click Add
  7. Two fields appear side by side: Secret ID and Value. Copy the Value field (the long string) — this is your clientSecret. It is only shown once; if you navigate away, you cannot retrieve it.

Step 3: Get Subscription ID

  1. Search for "Subscriptions" in the portal
  2. Click your subscription
  3. Copy the Subscription ID

Step 4: Create Resource Group

Naming is required

The resource group must be named exactly {projectName}-{env}-rg. The framework derives this name from your project name and environment — there is no way to override it. If the name doesn't match, all commands will fail.

  1. Search for "Resource groups" > + Create
  2. Subscription: Select from Step 3
  3. Resource group: {projectName}-{env}-rg (e.g., tsdevstack-dev-rg)
  4. Region: Choose your region (e.g., East US 2). Avoid East US — PostgreSQL Flexible Server is often restricted there. Some regions also refuse tenants that have no resources there yet: infra:init then fails with "The selected region is currently not accepting new customers". Microsoft's location ineligible page lists those regions. The deploy creates its resources in the resource group's region, so moving means deleting the group, creating it again in another region (with the roles in Step 5), and setting location in the credentials (Step 6) to that region.
  5. Click Review + create > Create

Step 5: Grant Permissions

The Service Principal needs three roles on the resource group.

Go to the Resource Group > Access control (IAM) > assign each role:

Role 1: Contributor

  • + Add > Add role assignment
  • Tab: Privileged administrator roles > select Contributor
  • Select members > search for tsdevstack-dev > assign

Role 2: Key Vault Secrets Officer

  • + Add > Add role assignment
  • Tab: Job function roles > search Key Vault Secrets Officer
  • Select members > search for tsdevstack-dev > assign

Role 3: User Access Administrator (constrained)

  • + Add > Add role assignment
  • Tab: Privileged administrator roles > select User Access Administrator
  • Select members > search for tsdevstack-dev
  • On the Conditions step: click Select roles and principals
  • Select Constrain roles template
  • Click + Select roles > search and add each:
    • Key Vault Secrets Officer
    • Key Vault Secrets User
    • AcrPull
    • Storage Blob Data Contributor
    • Monitoring Metrics Publisher
  • Save and assign
RolePurpose
ContributorCreate and manage resources (Key Vault, Container Apps, databases, etc.)
Key Vault Secrets OfficerRead, write, and delete secrets in Key Vault
User Access Administrator (constrained)Assign only the Key Vault, AcrPull, Storage and Monitoring Metrics Publisher roles to the apps' managed identities. Put and lift the database's delete lock (the condition limits role assignments only, not locks)

All roles above are scoped to the resource group. Provider registration (done earlier) is a separate subscription-level operation.

Monitoring Metrics Publisher lets the services, Kong and the Next.js apps send their traces to Azure Monitor. A service principal set up before it was on this list can't grant it, and infra:deploy stops with an authorization error. Add it: Resource Group > Access control (IAM) > Role assignments > the User Access Administrator row > View/Edit in the Condition column, then add Monitoring Metrics Publisher to the roles and save.

Step 6: Save Credentials

Create .tsdevstack/.credentials.azure.json:

{
  "dev": {
    "clientId": "<Application (client) ID from Step 1>",
    "clientSecret": "<Secret Value from Step 2>",
    "tenantId": "<Directory (tenant) ID from Step 1>",
    "subscriptionId": "<Subscription ID from Step 3>",
    "location": "eastus2"
  }
}

Add more environments as needed. Each environment must use a different subscriptionId (enforced by framework).

Step 7: Initialize

npx tsdevstack cloud:init --azure

This will:

  1. Validate each environment has a unique subscription
  2. Check all 12 resource providers: registers the missing ones when the service principal may (Contributor on the subscription), otherwise names the ones still to register in the portal
  3. Create the shared Key Vault with RBAC authorization enabled. If a vault with that name was deleted in the last 90 days, it's recovered
  4. Check that the service principal can read the vault's secrets. This needs the Key Vault Secrets Officer role from Step 5. cloud:init doesn't assign roles.
  5. Update .tsdevstack/config.json with cloud.provider: "azure"

Safe to run multiple times — all operations are idempotent.

Secret Naming

Azure Key Vault only allows alphanumeric characters and hyphens. The framework auto-transforms underscores:

  • DATABASE_URL > stored as DATABASE-URL
  • JWT_PRIVATE_KEY_CURRENT > stored as JWT-PRIVATE-KEY-CURRENT

Your code always uses underscores — the transformation is transparent.

Environment Isolation

Each environment must use a separate subscription (unique subscriptionId). The framework validates this during cloud:init.

Troubleshooting

"Forbidden" or "Access Denied"

  1. Check the SP has all three roles on the resource group (Step 5)
  2. Verify credentials match the App Registration
  3. Verify subscriptionId matches the subscription containing the resource group

"Caller is not authorized to perform action on resource" (Key Vault)

The service principal has no Key Vault role that allows the action named on the error's Action: line. Give it Key Vault Secrets Officer on the resource group (Step 5, Role 2). Key Vault Secrets User has a similar name but can only read, so pushing secrets fails on setSecret. A new role assignment can take up to 10 minutes to apply.

"does not have authorization to perform action ... register/action"

Resource providers are not registered on the subscription. Go to Subscriptions > your subscription > Resource providers and register all providers listed in Register Resource Providers.

"Key Vault not found"

Run npx tsdevstack cloud:init --azure to create it.

"Credentials file not found"

Ensure the file exists at .tsdevstack/.credentials.azure.json.

"ServerNameAlreadyExists" on the PostgreSQL server

PostgreSQL Flexible Server names are global DNS names, and the default name is already taken somewhere in Azure. With the subscription's suffix ({project}-{env}-postgres-{suffix}) that's rare; environments set up with v0.12.0 or earlier use {project}-{env}-postgres, which another project with the same name, or a server left in a subscription you deleted, can hold. Set a different name for that environment with database.serverName in .tsdevstack/infrastructure.json, then deploy again. See Custom server name (Azure).

"Creation of Azure Managed Redis with the SKU ... is not supported for your subscription"

Your subscription isn't allowed to create Azure Managed Redis in that region yet. Request access through a support request, see Azure Managed Redis Access. Choosing a bigger size doesn't help: the block usually applies to the product, not to one size.