Skip to main content

Azure Virtual Machines Integration for AlmaForge

On an Azure Virtual Machine, almad reads the VM's resource tags from the Azure Instance Metadata Service (IMDS) and attaches them as labels to every resource the agent registers: SSH nodes, applications, databases, and Kubernetes clusters. Each tag key is prefixed with azure/ to distinguish it from ordinary static labels.

There is no config knob to turn on and no Azure-side setting to enable. When almad starts on an Azure VM, it probes IMDS, negotiates an API version, and starts the importer. Azure VM resource tags are available through IMDS, so unlike AWS EC2 there is no "enable instance metadata tags" toggle to flip. If the VM has no tags, the importer runs idle and the agent uses only its static labels.

TL;DR​

  1. Set resource tags on the VM in the Azure portal, with az vm update, or in your IaC tool (Step 1).
  2. Start or restart almad. Resource tags appear as azure/<key> labels on the agent's resources (Step 2).

Prerequisites​

Before you start, make sure you have:

  • One almad agent running on an Azure VM and joined to a AlmaForge cluster. See SSH server enrollment to install and join an agent.
  • Permission to set resource tags on the VM, either in the Azure portal (Contributor or Tag Contributor role on the VM resource) or via an IaC pipeline that writes to ARM.
  • A working alma CLI pointed at the cluster so you can list resources after applying tags.
  • Outbound reachability from the VM to http://169.254.169.254/metadata. Azure IMDS is link-local and accessed from inside the VM. Ensure the agent can reach it directly, bypassing HTTP proxies.

Step 1. Apply tags to the VM​

Resource tags live on the VM itself as part of its ARM resource definition. Set them anywhere you already manage Azure resources. Three equivalent paths:

Option A: Azure portal​

  1. Open the VM in the Azure portal.
  2. In the left pane, open Tags.
  3. Add the key/value pairs you want to project into AlmaForge labels.
  4. Save.

Option B: Azure CLI​

Terminal
az vm update \    --resource-group my-rg \    --name my-vm \    --set tags.Team=platform tags.CostCenter=rd-42 tags.env=prod

az vm update is additive by default: existing tags you do not mention on the command line are left alone.

Option C: Terraform / Bicep​

Set the tags field on the azurerm_virtual_machine or azurerm_linux_virtual_machine resource in Terraform, or on the Microsoft.Compute/virtualMachines resource in Bicep. ARM applies them the next time the resource is reconciled.

Step 2. Verify labels on the agent​

almad fetches all tags once on startup and then on a one-hour schedule. After you change a tag in Azure, expect it to propagate to the VM's IMDS within a few minutes on Azure's side, and then to the agent on the next refresh. If you want to request a fresh fetch before the next interval, restart the agent.

List the node. Each Azure VM tag appears as an azure/<key> label. The table view truncates long label lists, so pass -o yaml to see every label at once:

Terminal
alma get node -o yamlapiVersion: almaforge.com/v1kind: Servermetadata:  labels:    env: prod    azure/Team: platform    azure/CostCenter: rd-42    azure/Owner: sre  name: 5c1f...spec:  useTunnel: true  hostname: app-01.example.com

Tag values pass through unchanged. Tag keys that are not valid AlmaForge label keys are skipped with a debug-level log on the agent and do not appear in the output.

The same labels flow to any other resource the agent registers. If the host runs the application service, the database service, or the Kubernetes service as well as SSH, each resource they register receives the same azure/... label set.

Troubleshooting​

azure/ labels never appear​

From the VM itself, confirm IMDS responds and returns a tag list:

Terminal
curl -sH "Metadata: true" \    "http://169.254.169.254/metadata/instance/compute/tagsList?api-version=2021-02-01"[{"name":"Team","value":"platform"},{"name":"CostCenter","value":"rd-42"}]

The Metadata: true header is required. Azure IMDS rejects requests without it. If this command returns the expected tags but they do not show up on the node, restart almad to force a fresh fetch. The first action the importer takes after startup is a full fetch.

If the curl command fails with a 400, 401, or 403, IMDS is up but the request shape is wrong. Verify you passed the Metadata: true header and an api-version query parameter. Any recent API version (2021-02-01, 2023-07-01, etc.) is fine for a manual check.

almad also logs the unreachable-metadata case once per process lifetime at warning level: Could not fetch Azure instance's tags.

Labels are stale​

The agent refreshes on a fixed one-hour schedule. There is no way to shorten that interval. To force a refresh, restart almad on the VM.

Azure propagation has its own delay as well: after you change a tag in the portal or via ARM, it takes up to a few minutes for the new value to be visible through IMDS. If the agent's view is still stale after a restart, check that the new value is visible in the curl command above before looking at AlmaForge.

Operations​

Blast radius of a bad tag​

Tags enter the agent as static labels, so any role or access rule that matches on azure/... picks up whatever value IMDS returns. Access rules that grant access when a label matches a specific value use the imported label after the agent refreshes and publishes it. A tag edit does not revoke access immediately. Use a lock for an urgent cutoff. Treat write permission on Azure VM resource tags as equivalent to write permission on the labels those tags drive. Scope the Microsoft.Resources/tags/write permission and the VM Contributor / Tag Contributor role assignments on production VMs accordingly.

Non-Azure hosts​

On a host that is not an Azure VM, the importer still attempts the Azure IMDS probe at agent startup, because Azure detection does not use DMI and cannot be short-circuited the way EC2 and Hetzner are. The probe times out within a total 500 millisecond window across all cloud providers, and the agent proceeds normally with only its static labels. You will not see a warning on non-cloud hosts unless you enable debug logging.

Refresh cadence​

The one-hour refresh interval is fixed in the agent and not configurable. A tag change reaches AlmaForge after Azure exposes it through IMDS and the agent's next successful fetch. Restarting the agent requests a fresh fetch without waiting for the interval and reuses existing certificates. A restart can interrupt sessions on that host.

Interaction with static labels​

Static labels set in the agent's configuration and azure/* labels coexist. Static labels take precedence if the same key is configured in both places. Reserve azure/ keys for the importer so a manual value does not mask the Azure tag. See RBAC label matching to use imported labels in roles.

References​