> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Run on Azure

> Connect Monk to your Microsoft Azure account

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

<Steps>
  <Step title="Copy your Subscription ID">
    Log into [Azure Portal → Subscriptions](https://portal.azure.com/#blade/Microsoft_Azure_Billing/SubscriptionsBlade) and copy the **Subscription ID** you want Monk to use.
  </Step>

  <Step title="Register an application">
    Go to [Azure Active Directory → App registrations](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps) → **New registration**. Name it something like `monk-deployment` and click **Register**.
  </Step>

  <Step title="Copy IDs">
    On the app overview page, copy the **Application (client) ID** and **Directory (tenant) ID**.
  </Step>

  <Step title="Create a client secret">
    Go to **Certificates & secrets** → **New client secret**. Set an expiry and copy the **Value** immediately — it is shown only once.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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
    ```
  </Step>
</Steps>

## 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).

<Accordion title="Minimum custom role JSON">
  ```json theme={null}
  {
    "$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"
    ]
  }
  ```
</Accordion>

<Accordion title="CLI setup (alternative to portal)">
  ```bash theme={null}
  # 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
  ```
</Accordion>

## 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](/features/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
```

<Card title="Deploy your first app" icon="rocket" href="/getting-started/first-deployment" color="#3B82F6">
  Credentials ready — now deploy
</Card>