Run on Azure

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

You enter credentials in a form in the local dashboard, never in chat. Monk keeps them in your OS keychain (or an encrypted file where there is no keychain) on your computer and pushes them to your cluster when a deployment needs them. The coding agent never sees the values. See Security.

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? Deploy your app

Start here

Install

Connect a cloud

Help

What you need

Create credentials

Required permissions

How credentials are stored

Troubleshooting

Deploy your first app

​What you need

​Create credentials

​Required permissions

​How credentials are stored

​Troubleshooting

Deploy your first app

What you need

Create credentials

Required permissions

How credentials are stored

Troubleshooting