Skip to main content
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

1

Copy your Subscription ID

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

Register an application

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

Copy IDs

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

Create a client secret

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

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.
6

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:
ask Monk to 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). 
{
  "$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"
  ]
}

# 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 in your IDE’s secret storage 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: 
ask Monk why my Azure credentials are not working

Deploy your first app

Credentials ready — now deploy