Connect an Azure subscription#

The Community Edition connects one cloud account, on AWS, Azure or GCP (editions.md). The Azure ingestor is off until you ask for it:

helm upgrade hyvop ./hyvop -n hyvop --reuse-values --set ingestors.azure.enabled=true

An administrator then connects the subscription under Integrations, Azure.

Hyvop reads only. It signs in as an app registration (a service principal) and reads resources and metrics; it reads cost from a storage account. The role it needs is a read-only custom role, not the built-in Reader: Reader lets a principal read every resource of every provider in the subscription, and Hyvop calls a short list of them.

What to create in Azure#

1. An app registration. Microsoft Entra ID, App registrations, New registration; the screen suggests the name hyvop-reader. Note its Application (client) ID and the Directory (tenant) ID.

2. A client secret. Under Certificates & secrets, create one and copy its Value (not its ID).

3. The custom role, assigned to the app registration at the subscription scope. The definition (20 actions, all reads; NotActions, DataActions and NotDataActions are empty):

   jsonCopy

   {
     "Name": "Hyvop reader",
     "IsCustom": true,
     "Description": "Lets Hyvop list resources and read their metrics in this subscription. It cannot change a resource, list a key or read a secret.",
     "Actions": [
       "Microsoft.Compute/disks/read",
       "Microsoft.Compute/locations/vmSizes/read",
       "Microsoft.Compute/snapshots/read",
       "Microsoft.Compute/virtualMachines/read",
       "Microsoft.DocumentDB/databaseAccounts/read",
       "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/read",
       "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/throughputSettings/read",
       "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/read",
       "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/throughputSettings/read",
       "Microsoft.Insights/Metrics/Read",
       "Microsoft.Network/loadBalancers/read",
       "Microsoft.Network/publicIPAddresses/read",
       "Microsoft.Resources/subscriptions/locations/read",
       "Microsoft.Resources/subscriptions/read",
       "Microsoft.Sql/servers/databases/read",
       "Microsoft.Sql/servers/read",
       "Microsoft.Storage/storageAccounts/blobServices/containers/read",
       "Microsoft.Storage/storageAccounts/managementPolicies/read",
       "Microsoft.Storage/storageAccounts/read",
       "Microsoft.Web/sites/read"
     ],
     "NotActions": [],
     "DataActions": [],
     "NotDataActions": [],
     "AssignableScopes": ["/subscriptions/<SUBSCRIPTION_ID>"]
   }

   With the Azure CLI, save that JSON as hyvop-reader.json (with your subscription ID in AssignableScopes), then:

   shCopy

   SUB=<SUBSCRIPTION_ID>
   az ad app create --display-name hyvop-reader
   az ad sp create --id <APP_ID>
   az role definition create --role-definition @hyvop-reader.json
   az role assignment create --assignee <APP_ID> --role "Hyvop reader" --scope /subscriptions/$SUB
   az ad app credential reset --id <APP_ID> --append

   The connection screen shows the same definition for the services you choose, and an administrator can read it from GET /api/integrations/AZURE/role-setup (with services to leave out the ones you do not want collected).

4. A cost export (optional, but without it resources carry no billed cost): a Cost Management export, daily, actual cost, CSV, written to a storage account and a container. Note the storage account name, the container (with its folder if it has one, for example exports/daily) and one of the storage account's access keys.

None of these actions writes, lists a key or reads a secret, and the role has no data actions. Cost is read differently: the ingestor lists and reads the export's CSV files in the storage account with the account's access key. Prices come from Microsoft's public Retail Prices API, which needs no sign-in.

If you connected with Reader and Cost Management Reader before: they keep working. To move to the custom role, assign it, then remove the two built-in assignments and run a collection.

What to enter in Hyvop#

Test the connection, then save. The subscription is collected at once and then on the same schedules as an AWS account (inventory every 4 hours, metrics every 2 hours, billing nightly).

Cost: when it is collected#

Core asks the Azure ingestor for billing only when the subscription has a cost export configured. A subscription connected without one is scanned and is not asked for billing every night only to fail. Add the export later by editing the connection.

The ingestor needs to reach Azure's APIs and the Retail Prices API on port 443 (networkPolicy.egress.ingestors.internet, true by default).

How much history the first collection reads#

The first collection of a newly connected account reads 30 days of metrics, so that the rules that need history can report once it is there. The ingestor setting AZURE_METRICS_BACKFILL_DAYS (30 by default) sets it: ingestors.azure.env.AZURE_METRICS_BACKFILL_DAYS=14. A longer one is limited by what the cloud keeps (Azure Monitor keeps metrics 93 days).

Demo mode#

ingestors.azure.env.AZURE_DATA_SOURCE=dummy serves fixture data instead of reading Azure. The default is live.