banshee/cloud-collection/cloud/azure/https/vms

Azure virtual machines, by Azure Resource Manager

Returns, for each virtual machine of an Azure subscription, its power state and its availability as Azure Resource Health judges it, read through Azure Resource Manager with a service principal that may only read. Three watches are offered, each one set on the probe.

Versions

Generic: Azure Resource Manager is one service, the same for every subscription. The collector asks for the API versions 2024-07-01 of Microsoft.Compute and 2025-05-01 of Microsoft.ResourceHealth, both listed by the Azure REST API reference among the supported versions.

How it works

POST https://login.microsoftonline.com/<azure:tenant>/oauth2/v2.0/token, the form grant_type=client_credentials&client_id=…&client_secret=…&scope=https://management.azure.com/.default: an access token, kept thirty minutes in the probe's cache, encrypted on the poller. A token Azure no longer takes answers 401, and the collector logs in again, once.
GET https://management.azure.com/subscriptions/<azure:subscription>/providers/Microsoft.Compute/virtualMachines?api-version=2024-07-01&statusOnly=true, the token as Authorization: Bearer: every machine of the subscription with its run-time statuses, page after page by nextLink.

{"value": [{"id": "/subscriptions/…/resourceGroups/RG-WEB/providers/Microsoft.Compute/virtualMachines/web-1", "name": "web-1", "properties": {"instanceView": {"statuses": [{"code": "ProvisioningState/succeeded"}, {"code": "PowerState/running", "displayStatus": "VM running"}]}}}], "nextLink": "…"}

GET https://management.azure.com/subscriptions/<azure:subscription>/providers/Microsoft.ResourceHealth/availabilityStatuses?api-version=2025-05-01: the current availability of every resource of the subscription, each under the id of its resource followed by /providers/Microsoft.ResourceHealth/availabilityStatuses/current, page after page.

{"value": [{"id": "/subscriptions/…/virtualMachines/web-1/providers/Microsoft.ResourceHealth/availabilityStatuses/current", "properties": {"availabilityState": "Available", "summary": "…"}}], "nextLink": "…"}

A machine is named <resource group>/<name>, the group in lower case: two machines of one name may live in two groups.
power is the part of the status PowerState/… after the slash, in lower case: running, starting, stopping, stopped (powered off but still allocated, and billed), deallocating, deallocated. A machine without such a status, which Azure says can happen in rare cases, reads unknown.
health is the availabilityState of the machine in lower case: available, degraded, unavailable, unknown; a machine Resource Health does not list reads unknown. The ids are compared in lower case.
A next page is only followed on https://management.azure.com/, where the token may go; any other address stops the collector unreachable.
A code 400 or 401 on the login stops the collector misconfigured (the tenant, the client or its secret refused); a code 403 on a list (the role missing), 400 or 404 (the subscription unknown) too; any other code but 200 stops it unreachable.

The client secret comes from protocol:http:password, a secret variable: it goes in the body of the login only, to https:// only. The token is a secret too, kept in the cache and sent in a header. The lists are not secret.

Prerequisites

A service principal: an app registration in Microsoft Entra ID with a client secret. Its application (client) ID goes in protocol:http:user, its secret in protocol:http:password, its tenant in the variable azure:tenant.
The role Reader given to it on the subscription (Access control (IAM), Add role assignment): */read and nothing else, which lists the machines and reads Resource Health. With Azure CLI: az role assignment create --assignee <client id> --role Reader --scope /subscriptions/<subscription id>.
The poller reaches login.microsoftonline.com and management.azure.com in HTTPS. Their certificates are issued by public authorities: the profile "Standard" trusts them.

Variables

Name	Label	Says	Default
`azure:tenant`	Tenant	the directory (tenant) ID of the service principal, or one of its domains	—
`azure:subscription`	Subscription	the ID of the subscription	—

Outputs

Name	Label	Unit	Per instance
`power`	Power state	—	yes, per virtual machine
`health`	Resource Health	—	yes, per virtual machine

Watches

Name	Title	Kind	Defaults	Checked by default
`not-running`	Virtual machine not running	expected value, on `power`	critical when not `running` for 2 runs: a start or a stop in progress does not raise	yes
`unavailable`	Virtual machine unavailable	state to avoid, on `health`	warning on `degraded`, critical on `unavailable`	yes
`missing`	Virtual machine missing	expected instances, on `power`	no name given: it raises nothing until names are set on the probe	no

A machine stopped on purpose (a test machine, a machine started on demand) is left out by the selection of the probe (Virtual machines: All except rg-test/*).

Limits

Resource Health lists every resource of the subscription, not only the machines: a subscription of many thousands of resources reads as many statuses, page after page.
Not checked against an Azure subscription: the routes, parameters and fields are those of the Azure REST API reference (learn.microsoft.com: "Virtual Machines - List All" in 2024-07-01, which documents statusOnly; the states of "States and billing status", "Availability Statuses - List By Subscription Id" in 2025-05-01) and of the Microsoft identity platform ("OAuth 2.0 client credentials flow"). The reference gives no sample of an answer with statusOnly=true: that the statuses come under properties.instanceView.statuses is read from the definition of a machine, not from a sample.