Azure Subscription ☁️

Komodor's Azure integration discovers your AKS clusters and pulls read-only metadata so you can view workload health, costs, and right-sizing recommendations without granting write access.

How it works

You create an Azure App Registration (service principal) with the built-in Reader role on your subscription, then hand the credentials to Komodor. Komodor stores the client secret encrypted and uses it only to list and describe your AKS resources.

Prerequisites

- Azure CLI installed — `az --version`

- Owner or User Access Administrator on the target subscription

- Active `az` login — `az login`

- A Komodor API key (find it under Settings → API Keys)

Setup

Option 1 — Automated setup script

Download and run the script. It creates the app registration, assigns the Reader role, and registers the integration in one step.

bash
bash setup-azure-integration.sh \
--subscription-id <your-subscription-id> \
--komodor-api-key <your-api-key>

For multiple subscriptions, need to run it separately for each subscription.

Optional flags:

Flag	Description	Default
--subscription-id	Azure subscription ID	required
--komodor-api-key	Komodor API key	required
--account-name	Display name in Komodor	Subscription display name
--tenant-id	Azure tenant ID	Current `az login` tenant

Option 2 — Azure CLI (step by step)

Set your subscription

bash
az account set --subscription <your-subscription-id>

Create the app registration

bash
APP_ID=$(az ad app create --display-name "komodor" --query appId -o tsv)
echo "App ID: $APP_ID"

Create a service principal

bash
az ad sp create --id "$APP_ID"

Create a client secret

bash
az ad app credential reset --id "$APP_ID" --years 2

This outputs three values — save them all:

Output field	Komodor field
appId	clientId
password	clientSecret (shown once only)
tenant	tenantId

Assign the Reader role on the subscription

bash
az role assignment create \
--assignee "$APP_ID" \
--role "Reader" \
--scope "/subscriptions/<your-subscription-id>"

Register the integration

bash
curl -X POST https://api.komodor.com/api/v2/integrations/azure \
-H "X-API-KEY: <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"accountName": "<display-name>",
"tenantId": "<tenant-id>",
"clientId": "<app-id>",
"clientSecret": "<client-secret>",
"subscriptionId": "<your-subscription-id>"
}'

Option 3 — Azure Portal

1. Go to Azure Active Directory → App registrations → New registration

- Name: `komodor`

- Supported account types: Accounts in this organizational directory only

- Click Register

2. On the app's overview page, note the Application (client) ID and Directory (tenant) ID

3. Go to Certificates & secrets → New client secret

- Description: `komodor`

- Expiry: 24 months

- Click Add — copy the Value immediately (it won't be shown again)

4. Go to Subscriptions → [your subscription] → Access control (IAM) → Add role assignment**

- Role: `Reader`

- Assign access to: User, group, or service principal

- Search for and select your `komodor` app registration

- Click Review + assign

5. Register the integration via the API (same `curl` command as Option 2, step 6)

Verify the connection

A successful `POST` returns `HTTP 201` with an integration ID and initial status:

{
"id": "...",
"status": "connected",
"verificationStatus": "pending"
}

`verificationStatus` transitions to `verified` within 2–3 minutes. Poll with:

bash
curl https://api.komodor.com/api/v2/integrations/azure/<integration-id> \
-H "X-API-KEY: <your-api-key>" \
| python3 -m json.tool

Required permissions

The built-in Reader role covers everything Komodor needs. If your security policy requires a custom role, the minimum permissions are:

Permission	Purpose
Microsoft.ContainerService/managedClusters/read	Discover and read AKS clusters
Microsoft.ContainerService/managedClusters/agentPools/read	Read node pool details
Microsoft.Resources/subscriptions/resourceGroups/read	Enumerate resource groups
Microsoft.Authorization/roleAssignments/read	Validate role assignments

Troubleshooting

`verificationStatus` stays `pending` after 5 minutes

Role assignments can take a few minutes to propagate. If it stays `pending` past 10 minutes, confirm the Reader role is assigned at the subscription scope (not a resource group or individual resource).

`HTTP 401 Unauthorized`

The `X-API-KEY` header is missing or the key is invalid. Verify your API key under **Settings → API Keys**.

`HTTP 422 All checks failed`

The credentials are invalid, or the Reader role hasn't propagated yet. Double-check `tenantId`, `clientId`, `clientSecret`, and `subscriptionId`, then wait 2 minutes and retry.

`HTTP 409 Conflict`

An integration for this subscription already exists. Remove the existing one first via `DELETE /api/v2/integrations/azure/<id>`, then retry.