Run on Azure - Monk Docs

Monk needs a service principal to provision and manage infrastructure in your Azure subscription. This page walks you through creating one with the right permissions.

What You Need

Client ID (Application ID)
Client Secret
Tenant ID
Subscription ID
Resource Group name

Create Credentials

Copy your Subscription ID

Log into Azure Portal → Subscriptions and copy the Subscription ID you want Monk to use.

Go to Azure Active Directory → App registrations → New registration. Name it something like monk-deployment and click Register.

Copy IDs

On the app overview page, copy the Application (client) ID and Directory (tenant) ID.

Create a client secret

Go to Certificates & secrets → New client secret. Set an expiry and copy the Value immediately — it is shown only once.

Assign a role

Go to your subscription → Access control (IAM) → Add role assignment. Assign the Contributor role (or the custom role below) to the application you just registered.

Provide to Monk

When you deploy to Azure, Monk requests credentials through a secure form. You can provide them as individual fields or as an SDK auth JSON file. You can also tell your agent:

/monk update my Azure credentials

Required Permissions

The built-in Contributor role works for a quick start. For production, use the minimum custom role below. Scope summary: Compute (VMs, disks, snapshots, availability sets). Networking (VNet/subnets, NICs, public IPs, NSGs). Load balancing (load balancers and application gateways). Resource groups and subscription metadata. Marketplace agreements (for some images).

Minimum custom role JSON

{
  "$schema": "https://schema.management.azure.com/schemas/2018-01-01/roleDefinition.json",
  "Name": "Monk Cluster Role",
  "IsCustom": true,
  "Description": "Custom role for Monk container orchestration platform",
  "Actions": [
    "Microsoft.Network/publicIPAddresses/read",
    "Microsoft.Network/publicIPAddresses/write",
    "Microsoft.Network/publicIPAddresses/delete",
    "Microsoft.Network/publicIPAddresses/join/action",
    "Microsoft.Compute/disks/read",
    "Microsoft.Compute/disks/write",
    "Microsoft.Compute/disks/delete",
    "Microsoft.Compute/snapshots/read",
    "Microsoft.Compute/snapshots/write",
    "Microsoft.Compute/snapshots/delete",
    "Microsoft.Network/networkWatchers/read",
    "Microsoft.Network/networkWatchers/delete",
    "Microsoft.Network/virtualNetworks/read",
    "Microsoft.Network/virtualNetworks/write",
    "Microsoft.Network/virtualNetworks/delete",
    "Microsoft.Network/virtualNetworks/subnets/read",
    "Microsoft.Network/virtualNetworks/subnets/write",
    "Microsoft.Network/virtualNetworks/subnets/delete",
    "Microsoft.Network/virtualNetworks/subnets/join/action",
    "Microsoft.Compute/virtualMachines/read",
    "Microsoft.Compute/virtualMachines/write",
    "Microsoft.Compute/virtualMachines/delete",
    "Microsoft.Compute/virtualMachines/restart/action",
    "Microsoft.Compute/virtualMachines/start/action",
    "Microsoft.Compute/virtualMachines/powerOff/action",
    "Microsoft.Network/networkInterfaces/read",
    "Microsoft.Network/networkInterfaces/write",
    "Microsoft.Network/networkInterfaces/join/action",
    "Microsoft.Network/networkInterfaces/delete",
    "Microsoft.Resources/subscriptions/resourceGroups/read",
    "Microsoft.Resources/subscriptions/resourceGroups/write",
    "Microsoft.Resources/subscriptions/resourceGroups/delete",
    "Microsoft.Network/networkSecurityGroups/read",
    "Microsoft.Network/networkSecurityGroups/write",
    "Microsoft.Network/networkSecurityGroups/delete",
    "Microsoft.Network/networkSecurityGroups/join/action",
    "Microsoft.Network/loadBalancers/read",
    "Microsoft.Network/loadBalancers/write",
    "Microsoft.Network/loadBalancers/delete",
    "Microsoft.Network/loadBalancers/backendAddressPools/join/action",
    "Microsoft.Compute/availabilitySets/read",
    "Microsoft.Compute/availabilitySets/write",
    "Microsoft.Compute/availabilitySets/delete",
    "Microsoft.Network/applicationGateways/read",
    "Microsoft.Network/applicationGateways/write",
    "Microsoft.Network/applicationGateways/delete",
    "Microsoft.Compute/skus/read",
    "Microsoft.Compute/locations/usages/read",
    "Microsoft.Resources/subscriptions/locations/read",
    "Microsoft.Authorization/permissions/read",
    "Microsoft.MarketplaceOrdering/offertypes/publishers/offers/plans/agreements/read",
    "Microsoft.MarketplaceOrdering/offertypes/publishers/offers/plans/agreements/write"
  ],
  "NotActions": [],
  "DataActions": [],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/YOUR_SUBSCRIPTION_ID"
  ]
}

CLI setup (alternative to portal)

# Replace YOUR_SUBSCRIPTION_ID in monk-role.json first
az role definition create --role-definition monk-role.json

# Create service principal with the custom role
az ad sp create-for-rbac \
  --name "monk-cluster-sp" \
  --role "Monk Cluster Role" \
  --scopes "/subscriptions/YOUR_SUBSCRIPTION_ID" \
  --sdk-auth > azurekey.json

# Provide the SDK auth file to Monk
monk cluster provider add -p azure -f /absolute/path/to/azurekey.json

How Credentials Are Stored

Credentials are encrypted at rest on your machine and on your Monk cluster using your cloud provider’s KMS — so your infrastructure can manage itself autonomously. They are never sent to Monk servers and never exposed to the LLM. See Security for full details.

Troubleshooting

Client secret expired — create a new secret in App registrations → Certificates & secrets, then update credentials in Monk. Wrong tenant ID — double-check the Directory (tenant) ID on the app overview page. Missing Contributor role — verify the role assignment in your subscription’s Access control (IAM). Ask your agent for help:

/monk why my Azure credentials are not working

Deploy your first app

Credentials ready — now deploy

​What You Need

​Create Credentials

​Required Permissions

​How Credentials Are Stored

​Troubleshooting