Azure Setup

Clouder supports Azure as a cloud provider for managing virtual machines, Kubernetes clusters, and other resources. This guide explains how to create the Azure credentials needed to connect from the Clouder CLI.

Prerequisites

• An Azure account — sign up at https://azure.microsoft.com/free
• Azure CLI installed — Install the Azure CLI

Authentication Methods

Clouder supports two authentication methods:

Method 1: Azure CLI Login (Recommended for Development)

The simplest way to get started. Log in with the Azure CLI and Clouder will use those credentials automatically.

# Log in to Azure
az login

# Verify your account
az account show

# Configure Clouder to use your Azure subscription
clouder azure configure

When you run clouder azure configure, it will detect your az login session, list available subscriptions, and let you select one interactively.

Method 2: Service Principal (Recommended for Production / CI/CD)

A Service Principal is an identity created for applications, services, and automation tools to access Azure resources with specific permissions.

Step 1: Create an App Registration

1. Go to the Azure Portal
2. Navigate to Microsoft Entra ID → App registrations → New registration
3. Enter a name (e.g., clouder-cli)
4. Set Supported account types to "Accounts in this organizational directory only"
5. Click Register
6. Note the Application (client) ID and Directory (tenant) ID from the Overview page

Step 2: Create a Client Secret

1. In your App registration, go to Certificates & secrets → Client secrets → New client secret
2. Add a description (e.g., clouder-cli-secret) and set an expiration
3. Click Add
4. Copy the secret Value immediately — it won't be shown again

Step 3: Assign Permissions

The Service Principal needs a role assignment on your subscription:

# Get your subscription ID
az account show --query id -o tsv

# Assign the Contributor role (allows creating/managing resources)
az role assignment create \
    --assignee <CLIENT_ID> \
    --role "Contributor" \
    --scope "/subscriptions/<SUBSCRIPTION_ID>"

For more restrictive access, you can use specific roles:

• Reader: List and view resources only
• Virtual Machine Contributor: Manage VMs
• Kubernetes Service Contributor: Manage AKS clusters

Step 4: Configure Clouder

Option A: Interactive configuration

clouder azure configure

This will prompt you for:

• Subscription ID
• Tenant ID
• Client (Application) ID
• Client Secret

Option B: Command-line flags

clouder azure configure \
    --subscription-id <SUBSCRIPTION_ID> \
    --tenant-id <TENANT_ID> \
    --client-id <CLIENT_ID> \
    --client-secret <CLIENT_SECRET> \
    --no-interactive

Option C: Using the Azure CLI shortcut

# Create a service principal and configure Clouder in one step
az ad sp create-for-rbac \
    --name "clouder-cli" \
    --role Contributor \
    --scopes "/subscriptions/<SUBSCRIPTION_ID>" \
    --query "{subscription_id: '<SUBSCRIPTION_ID>', tenant_id: tenant, client_id: appId, client_secret: password}" \
    -o json

Then pass the output values to clouder azure configure.

Configuration File

Clouder stores Azure credentials in ~/.clouder/azure/azure.yaml with restricted permissions (600). The file looks like:

subscription_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
tenant_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
client_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
client_secret: your-secret-value

Security note: Never commit this file to version control. The file permissions are automatically set to owner-read-write only.

Verifying the Setup

# Check Azure configuration
clouder azure

# List your subscriptions
clouder azure subscriptions

# List available regions
clouder azure regions

# List resources in your subscription
clouder azure resources

# List resource groups
clouder azure resource-groups

Virtual Machine Management

Listing VMs

# List all VMs in the subscription
clouder azure vm-ls

# List VMs in a specific resource group
clouder azure vm-ls --resource-group my-rg

Creating a VM

Clouder supports both interactive and non-interactive VM creation:

Interactive mode (prompts for all values):

clouder azure vm-create

The interactive flow will:

1. Ask for a VM name
2. Ask for a resource group (defaults to <name>-rg)
3. Show popular regions and let you pick one
4. Show common VM sizes (from free-tier to GPU instances)
5. Detect your SSH key (~/.ssh/id_rsa.pub) and ask to use it
6. Show a confirmation summary before creating

Non-interactive mode (all options specified):

clouder azure vm-create \
    --name my-vm \
    --resource-group my-rg \
    --region eastus \
    --vm-size Standard_B2s \
    --ssh-key ~/.ssh/id_rsa.pub \
    --image Ubuntu2204

Available images:

Image	Publisher	Description
Ubuntu2204	Canonical	Ubuntu 22.04 LTS (default)
Ubuntu2404	Canonical	Ubuntu 24.04 LTS
Debian12	Debian	Debian 12

When creating a VM, Clouder automatically provisions:

• A virtual network and subnet
• A public IP address (static)
• A network interface
• The VM itself with SSH key authentication

Deleting a VM

# Delete with confirmation prompt
clouder azure vm-delete my-vm --resource-group my-rg

# Delete without confirmation
clouder azure vm-delete my-vm --resource-group my-rg --force

Listing VM Sizes

# List VM sizes in a region (interactive)
clouder azure vm-sizes

# List VM sizes in a specific region
clouder azure vm-sizes --region westeurope

Resource Management

# List all available regions
clouder azure regions

# List resources (interactive region selection if not specified)
clouder azure resources
clouder azure resources --region eastus
clouder azure resources --resource-group my-rg

# List resource groups
clouder azure resource-groups

Interactive Mode

When no region or resource filters are provided, Clouder enters interactive mode:

• Region selection: Shows popular regions and lets you pick one
• VM creation: Prompts for name, resource group, region, VM size, and SSH key
• Resource listing: Asks which region to filter by

Environment Variables

As an alternative to the configuration file, you can set environment variables:

export AZURE_SUBSCRIPTION_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export AZURE_TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export AZURE_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export AZURE_CLIENT_SECRET=your-secret-value

These are automatically picked up by DefaultAzureCredential when no Clouder config file is present.

Troubleshooting

"DefaultAzureCredential failed to retrieve a token"

1. Run az login to refresh your credentials
2. Ensure your account has access to the subscription: az account list

"AuthorizationFailed"

Your Service Principal needs the right role assignment:

az role assignment list --assignee <CLIENT_ID> --output table

"SubscriptionNotFound"

Verify the subscription ID is correct and active:

az account list --output table