Azure Account Setup
Setting up Azure for tsdevstack deployments. Each environment requires its own subscription for isolation.
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
- Go to the Azure Portal
- 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
- In the left sidebar under Settings, click Resource providers
- 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:
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
- Go to the Azure Portal
- Search for "Quotas" > click My quotas
- 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
- In My quotas, keep the App Service filter for your region
- Request quota for each VM family you need:
- Select the row (e.g., "B1 VMs", showing "0 of 0") > click Request increase
- 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 - 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:
There is no API to check this ahead of time, so on a new subscription request access before your first deploy:
- Help + support > + Create a support request
- Issue type: "Service and subscription limits (quotas)"
- Pick the Redis quota type the form offers (Azure Managed Redis or Azure Cache for Redis)
- Ask for Azure Managed Redis with the size you'll use (
Balanced_B0by 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:
Request access for your deployment region:
- 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
- Quota type: "Azure Database for PostgreSQL flexible server"
- 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:
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:deployagain later. It continues where it stopped. - Pick another size for the resource that failed, for example
database.tierininfrastructure.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:
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:
(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.kongSkuorappService.nextjsSkuininfrastructure.json(for exampleB2), then runinfra:deployagain. - 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
- Go to Azure Portal > search "Microsoft Entra ID"
- Under Manage, click App registrations > + New registration
- Name:
{projectName}-{env}(e.g.,myapp-dev) - Supported account types: "Single tenant" (Accounts in this organizational directory only)
- Redirect URI: Leave blank
- Click Register
From the Overview page, copy:
- Application (client) ID > this is
clientId - Directory (tenant) ID > this is
tenantId
Step 2: Create Client Secret
- Click on your App Registration from the list to open it
- In the left sidebar under Manage, click Certificates & secrets
- Click + New client secret
- Description:
{projectName}-{env}-key(e.g.,myapp-dev-key) - Expires: 24 months
- Click Add
- 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
- Search for "Subscriptions" in the portal
- Click your subscription
- Copy the Subscription ID
Step 4: Create Resource Group
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.
- Search for "Resource groups" > + Create
- Subscription: Select from Step 3
- Resource group:
{projectName}-{env}-rg(e.g.,tsdevstack-dev-rg) - Region: Choose your region (e.g.,
East US 2). AvoidEast US— PostgreSQL Flexible Server is often restricted there. Some regions also refuse tenants that have no resources there yet:infra:initthen 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 settinglocationin the credentials (Step 6) to that region. - 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
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:
Add more environments as needed. Each environment must use a different subscriptionId (enforced by framework).
Step 7: Initialize
This will:
- Validate each environment has a unique subscription
- 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
- 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
- Check that the service principal can read the vault's secrets. This needs the Key Vault Secrets Officer role from Step 5.
cloud:initdoesn't assign roles. - Update
.tsdevstack/config.jsonwithcloud.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 asDATABASE-URLJWT_PRIVATE_KEY_CURRENT> stored asJWT-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"
- Check the SP has all three roles on the resource group (Step 5)
- Verify credentials match the App Registration
- Verify
subscriptionIdmatches 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.