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

# Azure

The [Azure](https://azure.microsoft.com/) plugin provides access to the following
resources from Microsoft Azure:

<AccordionGroup>
  <Accordion title="Knowledge Graph nodes" icon="diagram-project">
    * VM Instances
    * VM Scale Sets and Instances
    * SQL Databases
    * PostgreSQL Databases
    * MySQL Databases
    * Cosmos DB Accounts
    * Load Balancers
    * Application Gateways
    * Storage Accounts
    * Managed Disks
    * Virtual Networks and Subnets
    * Network Security Groups
    * Network Interfaces
    * Public IP Addresses
    * AKS Clusters
  </Accordion>

  <Accordion title="Metrics" icon="chart-line">
    **VM Instances:**

    * Percentage CPU
    * Network In/Out
    * Disk Read/Write Bytes
    * Disk Read/Write Operations/Sec
    * Available Memory Bytes
    * CPU Credits Remaining/Consumed

    **VM Scale Sets:**

    * Percentage CPU
    * Network In/Out Total
    * Disk Read/Write Bytes
    * Disk Read/Write Operations/Sec
    * CPU Credits Remaining/Consumed

    **SQL Databases:**

    * CPU Percent
    * Physical Data Read Percent
    * Log Write Percent
    * DTU Consumption Percent
    * Storage Percent
    * Connection Successful/Failed
    * Blocked by Firewall
    * Deadlocks
    * Workers/Sessions Percent

    **PostgreSQL Databases:**

    * CPU Percent
    * Memory Percent
    * IO Consumption Percent
    * Storage Percent/Used/Limit
    * Active Connections
    * Connections Failed
    * Network Bytes Ingress/Egress
    * Max Lag Across Replicas
    * Backup Storage Used

    **MySQL Databases:**

    * CPU Percent
    * Memory Percent
    * IO Consumption Percent
    * Storage Percent/Used/Limit
    * Active Connections
    * Connections Failed
    * Seconds Behind Master (replicas)
    * Network Bytes Ingress/Egress
    * Backup Storage Used

    **Cosmos DB Accounts:**

    * Total Request Units
    * Total Requests
    * Autoscale Max Throughput
    * Provisioned Throughput
    * Available Storage
    * Data/Index Usage
    * Document Count/Quota
    * Replication Latency
    * Service Availability

    **Load Balancers:**

    * VIP/DIP Availability
    * Byte Count
    * Packet Count
    * SYN Count
    * SNAT Connection Count
    * Allocated/Used SNAT Ports

    **Application Gateways:**

    * Throughput
    * Healthy/Unhealthy Host Count
    * Response Status (2xx/3xx/4xx/5xx)
    * Backend Response Status
    * Backend Connect/Request/Response Time
    * Current Connections
    * Failed Requests
    * Total Requests
    * Current Capacity Units

    **Storage Accounts:**

    * Used Capacity
    * Transactions
    * Ingress/Egress
    * Success Server/E2E Latency
    * Availability
    * Blob Capacity/Count
    * File Capacity/Count/Share Count

    **AKS Clusters:**

    * Node CPU Usage Percentage
    * Node Memory Working Set Percentage
    * Node Disk Usage Percentage
    * Node Network In/Out Bytes
    * Kube Pod Status Ready/Phase
    * Cluster Autoscaler Metrics
    * Unneeded Nodes Count
    * Unschedulable Pods Count
  </Accordion>

  <Accordion title="MCP Tools" icon="wrench">
    * **get\_realtime\_vm\_status**: Get real-time status information for an Azure VM instance
    * **get\_sql\_database\_status**: Get status information for an Azure SQL database
  </Accordion>
</AccordionGroup>

## Prerequisites

You should have Azure credentials configured through one of the following methods:

* **Azure CLI**: Use `az login` to authenticate with the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli)
* **Service Principal**: Set environment variables `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, and `AZURE_TENANT_ID`
* **Managed Identity**: If running on Azure infrastructure (VMs, App Service, etc.)
* **Visual Studio Code**: If you have the Azure Account extension installed and authenticated
* **Azure PowerShell**: If you have authenticated using Azure PowerShell

The plugin follows the [standard Azure credential provider chain](https://docs.microsoft.com/en-us/python/api/azure-identity/azure.identity.defaultazurecredential).

### Required Permissions

The Azure plugin requires read-only access to various Azure resources. Below is the recommended Azure RBAC (Role-Based Access Control) configuration.

#### Option 1: Use Built-in Reader Role (Recommended for Getting Started)

The simplest approach is to assign the built-in **Reader** role at the subscription level:

```bash theme={null}
# Get your subscription ID
SUBSCRIPTION_ID=$(az account show --query id -o tsv)

# Assign Reader role to your service principal or managed identity
az role assignment create \
  --assignee <your-service-principal-id-or-user> \
  --role "Reader" \
  --scope "/subscriptions/$SUBSCRIPTION_ID"
```

This provides read access to all resources in the subscription, which is sufficient for the plugin to build the knowledge graph and retrieve metrics.

#### Option 2: Custom Role with Minimal Permissions (Recommended for Production)

For production environments, create a custom role with only the permissions needed by Unpage:

```json theme={null}
{
  "Name": "Unpage Reader",
  "Description": "Minimal read-only permissions for Unpage infrastructure knowledge graph",
  "Actions": [
    "Microsoft.Compute/virtualMachines/read",
    "Microsoft.Compute/virtualMachines/instanceView/read",
    "Microsoft.Compute/virtualMachineScaleSets/read",
    "Microsoft.Compute/virtualMachineScaleSets/virtualMachines/read",
    "Microsoft.Compute/virtualMachineScaleSets/virtualMachines/instanceView/read",
    "Microsoft.Compute/disks/read",
    "Microsoft.Sql/servers/read",
    "Microsoft.Sql/servers/databases/read",
    "Microsoft.DBforPostgreSQL/servers/read",
    "Microsoft.DBforPostgreSQL/servers/databases/read",
    "Microsoft.DBforMySQL/servers/read",
    "Microsoft.DBforMySQL/servers/databases/read",
    "Microsoft.DocumentDB/databaseAccounts/read",
    "Microsoft.Network/loadBalancers/read",
    "Microsoft.Network/applicationGateways/read",
    "Microsoft.Network/virtualNetworks/read",
    "Microsoft.Network/virtualNetworks/subnets/read",
    "Microsoft.Network/networkSecurityGroups/read",
    "Microsoft.Network/networkInterfaces/read",
    "Microsoft.Network/publicIPAddresses/read",
    "Microsoft.Storage/storageAccounts/read",
    "Microsoft.ContainerService/managedClusters/read",
    "Microsoft.Insights/metrics/read",
    "Microsoft.Resources/subscriptions/resourceGroups/read"
  ],
  "NotActions": [],
  "AssignableScopes": [
    "/subscriptions/<your-subscription-id>"
  ]
}
```

To create and assign this custom role:

```bash theme={null}
# Save the JSON above to a file named unpage-reader-role.json
# Update <your-subscription-id> with your actual subscription ID

# Create the custom role
az role definition create --role-definition unpage-reader-role.json

# Assign the custom role
az role assignment create \
  --assignee <your-service-principal-id-or-user> \
  --role "Unpage Reader" \
  --scope "/subscriptions/$SUBSCRIPTION_ID"
```

#### Permissions Breakdown

The custom role includes permissions for:

* **Compute**: Read access to VMs, VM Scale Sets, and managed disks
* **Databases**: Read access to SQL, PostgreSQL, MySQL, and Cosmos DB resources
* **Networking**: Read access to load balancers, application gateways, virtual networks, subnets, NSGs, network interfaces, and public IPs
* **Storage**: Read access to storage accounts
* **AKS**: Read access to managed Kubernetes clusters
* **Monitoring**: Read access to Azure Monitor metrics for all resources
* **Resource Groups**: List and read resource groups in the subscription

These permissions are read-only and follow the principle of least privilege.

## Configuration

Configure the Azure plugin by running `uv run unpage configure` or by editing
the `~/.unpage/profiles/<profile_name>/config.yaml` file:

```yaml theme={null}
plugins:
  # ...
  azure:
    enabled: true
    # Optional: specify subscription details
    settings:
      subscriptions:
        default:
          subscription_id: "your-subscription-id"
          tenant_id: "your-tenant-id"  # Optional
```

If no subscription is specified, the plugin will use the default subscription from your Azure credentials.

## Tools

The Azure plugin provides the following tools to Agents and MCP Clients:

<Card title="get_realtime_vm_status">
  Get real-time status information for an Azure VM instance directly from Azure API.

  **Arguments**

  <ParamField path="vm_name" type="string" required>
    The Azure VM name.
  </ParamField>

  <ParamField path="resource_group" type="string" required>
    The Azure resource group name containing the VM.
  </ParamField>

  **Returns** `dict | string`: A dictionary containing VM status information or an error message if the VM couldn't be found.

  Example response:

  ```json theme={null}
  {
    "name": "my-vm",
    "power_state": "VM running",
    "provisioning_state": "Succeeded",
    "statuses": [
      {
        "code": "PowerState/running",
        "display_status": "VM running",
        "time": "2024-01-15T10:30:00Z"
      }
    ]
  }
  ```
</Card>

<br />

<Card title="get_sql_database_status">
  Get status information for an Azure SQL database.

  **Arguments**

  <ParamField path="database_name" type="string" required>
    The Azure SQL database name.
  </ParamField>

  <ParamField path="server_name" type="string" required>
    The Azure SQL server name hosting the database.
  </ParamField>

  <ParamField path="resource_group" type="string" required>
    The Azure resource group name containing the SQL server.
  </ParamField>

  **Returns** `dict | string`: A dictionary containing database status and configuration details or an error message if the database couldn't be found.

  Example response:

  ```json theme={null}
  {
    "name": "my-database",
    "status": "Online",
    "edition": "Standard",
    "service_objective": "S1",
    "max_size_bytes": 268435456000,
    "collation": "SQL_Latin1_General_CP1_CI_AS",
    "creation_date": "2024-01-10T08:00:00Z"
  }
  ```
</Card>