Reference Data Overrides

Reference Data Overrides

Some of the data Locally serves isn't a resource you create - it's reference data: the curated catalogues Azure exposes but that you only ever read. Locally ships a sensible built-in set of each, and lets you override or extend any of them with your own data, so a VM image, VM size or runtime stack that Locally doesn't ship out of the box can still be recognised locally.

The locally refresh-reference-data command fills those override files with real Azure data. It runs the Azure CLI for you against real Azure, using your existing az login, checks the output and writes it to the file Locally reads at launch. You need the Azure CLI installed and signed in.

The datasets

Five datasets can be refreshed. Three of them are per-region, so Locally runs the az command once for each region you pick and merges the results:

These commands go to real Azure, not Locally, so nothing here is prefixed with locally run. The region names are Azure's, such as westeurope, because that's where the data comes from.

Refreshing every dataset

Run the command with no arguments to refresh all five:

$ locally refresh-reference-data

In a terminal, it lists the Azure regions and lets you pick one or more. For each dataset it then shows how many entries it found and where it will write them, and asks before writing. Answer anything other than y to skip that dataset.

Refreshing one dataset

Name a dataset to refresh just that one, and pass the regions with --location:

$ locally refresh-reference-data images -l westeurope,eastus --yes $ locally refresh-reference-data vmSkus --location westeurope --yes

The stack datasets aren't per-region, so they don't need --location. Fetching images can take a few minutes per region.

Locally checks each response has the shape it expects before writing. If it doesn't, the command stops with an error and writes nothing for that dataset.

Running in a script

When stdin isn't a terminal there's no region picker and no confirmation prompt, so pass --yes, plus --location if a per-region dataset is included. Without them the command exits with an error and writes nothing.

Where the files are written

The command writes to the same directory Locally reads reference-data overrides from, resolved in this order (first one set wins):

Within that directory each dataset is a file at <provider>/<dataset>.json - for example microsoft.compute/images.json or microsoft.web/webAppStacks.json. Locally reads these at launch, so after a refresh you'll need to restart Locally for the new data to take effect.

How overrides are applied

An override adds to what Locally already serves - it never replaces the built-in catalogue wholesale. Your entries are merged over the curated defaults, and where an entry collides with a built-in one (by its identity - publisher/offer/sku for an image, name for a SKU or stack, and so on) yours wins. Anything you don't override keeps working exactly as before.

Because of this, a missing or malformed override file can only ever fall back to the built-in data - it can't break serving. If a file isn't present, Locally serves its defaults silently; if a file exists but can't be read or parsed, Locally logs a warning naming the dataset and still serves its defaults.

Flags