DEV Community: Kamil Mrzygłód

Topaz vs Azurite: what actually works locally and what doesn't

Kamil Mrzygłód — Tue, 05 May 2026 11:59:04 +0000

If you have ever written a line of Azure code on a laptop, you have used Azurite. It is the official local emulator for Azure Storage, ships in every Visual Studio install, and runs unchanged in tens of thousands of CI pipelines. For Storage-only workloads it is an excellent tool — Microsoft maintains it, Azure SDKs target it, and the parity with the real Azure Storage REST API is strong.

The problem is that real applications stop at Azure Storage roughly never. The moment you reach for a secret in Key Vault, publish a message to Service Bus, push an image to a Container Registry, or want a DefaultAzureCredential chain that does not silently fall back to interactive browser auth, Azurite has nothing to offer. You are left bolting together a Service Bus emulator from a community Docker image, mocking the Key Vault SDK in tests, and hoping that the way your CI fakes Entra tokens does not drift away from how production behaves.

Topaz is a single .NET 8 (and when 1.3 version is released - .NET 10) binary that emulates Azure Storage, Key Vault, Service Bus, Event Hubs, Container Registry, Managed Identity, RBAC, ARM, and a working Entra ID layer in one process. This post is an honest comparison between the two, focused on what developers who already know Azurite actually run into.

Run the Azure SDK, Azure CLI, Terraform, and docker push against a local emulator — no Azure subscription, no service principal, no cloud charges.
brew tap thecloudtheory/topaz && brew install topaz && topaz-host   # macOS
curl -fsSL https://raw.githubusercontent.com/TheCloudTheory/Topaz/main/install/get-topaz.sh | bash   # Linux
Getting started →

Where Topaz and Azurite agree

It is worth being clear about this up front: for Azure Storage, Azurite is good. Anyone telling you otherwise is selling something. Topaz does not exist because Azurite is bad at Storage — it exists because Azurite is only Storage, and most real Azure applications are not.

For Blob, Queue, and Table data plane operations, the two emulators are at full parity on the cases that matter for day-to-day development:

Storage feature	Topaz	Azurite
Blob basic operations (put, get, delete, head, list)	Yes	Yes
Blob metadata, container metadata	Yes	Yes
Block blobs (`Put Block`, `Put Block List`, `Get Block List`)	Yes	Yes
Page blobs (`Put Page`, `Get Page Ranges`)	Yes	Yes
Container ACLs and stored access policies	Yes	Yes
Container and blob leases (acquire / renew / change / release / break)	Yes	Yes
Blob copy and snapshots	Yes	Yes
Table create / delete / query / entity CRUD	Yes (stable)	Yes (preview)
Table ACL (stored access policies)	Yes	Yes
Queue messages (enqueue, dequeue, peek, update, delete, clear)	Yes	Yes
Queue ACL	Yes	Yes
RA-GRS secondary endpoints	Partial (roadmap)	Yes

The two practical Storage gaps in Topaz today are Account / Service SAS token validation on the data plane (the ARM endpoints that generate SAS strings exist; the data plane providers do not yet recognise the ?sv=...&sig=... parameters in incoming requests) and full RA-GRS secondary endpoint emulation. Both are scheduled — SAS validation is on the v1.4-beta milestone, RA-GRS is on v1.4-beta as well. More on that further down.

The Storage feature that Azurite still does not have is multiple named storage accounts as a first-class concept. Azurite's default account is devstoreaccount1. Adding more requires editing your hosts file, exporting AZURITE_ACCOUNTS with name:key1:key2;name:key1:key2, and restarting the emulator. Topaz has a real ARM control plane: az storage account create --name sa-orders --resource-group rg-local works the same way it works against Azure, registers a DNS entry automatically, and gives you a real connection string you can paste into Azure Storage Explorer or hand to Terraform.

Where Azurite stops: Key Vault

This is the largest single delta between the two emulators, and it is the reason most developers eventually try to replace Azurite.

Azurite has no Key Vault. Not a partial one, not a stubbed one — none. The standard workarounds are:

Mock the SecretClient in tests (loses any coverage of the actual auth layer).
Read secrets from appsettings.Development.json instead (creates a code-path divergence between local and production).
Spin up a real Key Vault per developer (works, but now CI needs Azure credentials and the developer onboarding doc has a "before you can run tests, ask the platform team for..." section).

Topaz has the most complete Key Vault emulation of any service it ships. The control plane covers the full vault lifecycle — create, update, soft-delete, list deleted, recover, purge, name availability, access policy management — and the data plane runs on its own port (8898) reachable at https://<vault-name>.vault.topaz.local.dev:8898/, which is the URL pattern the Azure SDK already constructs.

What works today on the data plane:

Surface	Operations
Secrets	Set, Get (by name and version), List, Update, Delete, Get Versions, Backup, Restore, full soft-delete surface (Get Deleted, List Deleted, Recover, Purge)
Keys	Create, Import (RSA + EC), Get, List, Update, Delete, Backup, Restore, Rotate, Get/Update Rotation Policy, full soft-delete surface, `encrypt`, `decrypt`, `sign`, `verify`, `wrapKey`, `unwrapKey`, `release`, `Get Random Bytes`, `Get Key Attestation`
Certificates	Not yet — full surface scheduled for v1.3-beta

The soft-delete and recovery surface deserves a specific call-out because it is what most teams accidentally depend on. If your application catches KeyVaultErrorException on a soft-deleted secret, recovers it, and continues — that code path is unreachable in any other local emulator. Topaz exercises it end-to-end. Tokens are real signed JWTs. The vault URL works with DefaultAzureCredential exactly as in production.

What is not there yet is the certificates data plane (CRUD, soft-delete surface, issuers, contacts, merge — all scheduled for v1.3-beta). If your application reads certificates from Key Vault — for example, an ASP.NET Core app loading its TLS cert via the Key Vault provider — that path is not yet covered. For secrets and keys, including the cryptographic operations, it is.

Where Azurite stops: Service Bus

Service Bus is the second most common reason teams outgrow Azurite. The community workarounds — RabbitMQ, ActiveMQ, in-memory test doubles — all break the same invariant: the AMQP wire format is not the same, so any code that reaches into broker-specific behaviour (dead-letter queues, peek-lock vs receive-and-delete, deferred messages, session state) drifts away from Service Bus reality.

Topaz runs a real AMQP 1.0 broker on ports 8889 (plain) and 5671 (AMQP/TLS), implemented natively in the host process. The Azure Service Bus SDK connects to it without modification. MassTransit, NServiceBus, and any other library that speaks AMQP work because they are speaking AMQP, not because Topaz pretends to be Service Bus through a thin shim.

Surface	What works
Namespaces (control plane)	Create / Update / Delete / Get / List By Resource Group
Queues (control plane)	Create / Update / Delete / Get / List By Namespace
Topics (control plane)	Create / Update / Delete / Get / List By Namespace
Subscriptions	Create / Update / Delete / Get (via AMQP management node)
Messaging (data plane, AMQP)	Send / Receive on queues and topics, Complete / Abandon / Dead-letter
AMQP entity management	Create / Get / Delete queues, topics, subscriptions — used by MassTransit

Specifically not implemented yet: subscription rule management (filters / actions), namespace authorization rules, list-keys / regenerate-keys, disaster recovery configs, migration configs, private endpoints. For most application development workflows this is a non-issue; if you are building tooling that programmatically rotates Service Bus SAS keys or manages DR pairing, real Azure is still the right target for those tests.

Where Azurite stops: Container Registry

docker push myregistry.azurecr.io/myapp:latest against a local emulator is the kind of thing that historically required either a real ACR (and therefore Azure credentials in CI) or running a generic Docker registry and pretending it is ACR (works for pull, breaks the moment anything touches the ARM control plane or the ACR-specific OAuth2 exchange).

Topaz emulates both layers:

Control plane (ARM): create, update, delete, list registries; manage admin credentials; toggle adminUserEnabled.
Data plane (OCI Distribution Spec, port 8892): manifest CRUD, blob upload (POST / PATCH / PUT chunked uploads), blob download and existence checks, repository catalog, tag listing, and the ACR-specific /oauth2/exchange endpoint that makes az acr login work.

The full authentication flow — GET /v2/ returning a Www-Authenticate challenge, POST /oauth2/exchange swapping the Entra token for an ACR refresh token, and the bearer token round-trip — is implemented end-to-end. There is a separate post on how this works that goes into the design tradeoffs.

What this unlocks: you can run docker push, helm push, and any OCI-compliant client against Topaz without modifying anything in your build pipeline. The registry hostname follows real Azure conventions (myregistry.cr.topaz.local.dev:8892). Image promotion workflows, CI builds that publish images, and Terraform configurations that create ACRs all work locally. docker pull and end-to-end image pull-through is on the roadmap.

Where Azurite stops: Entra ID and Managed Identity

This is the silent one. Azurite does not need an identity layer because it accepts SharedKey for authentication and falls back to "no auth" when nothing is provided. The moment your application uses DefaultAzureCredential — which is the Microsoft-recommended pattern for everything except Storage — Azurite cannot help. Your local code either talks to a real Entra tenant (forcing every developer onto a corporate identity) or you replace DefaultAzureCredential with a custom test double (creating a code-path divergence with production).

Topaz ships a working Entra ID emulation layer. A local tenant (topaz.local.dev, tenant ID 50717675-3E5E-4A1E-8CB5-C62D8BE8CA48) is provisioned at startup with a built-in superadmin account. Every token is a real, signed JWT — same format Azure issues, same claims layout, signed with HMAC-SHA256, one-hour lifetime. The OIDC discovery endpoint (/.well-known/openid-configuration) is fully functional, both /organizations/ and /{tenantId}/ variants are served, and four grant types are supported: client_credentials, password, authorization_code, and refresh_token.

Tied to that:

Microsoft Graph API for users, applications, service principals, and groups — enough to script a full identity setup.
Managed Identity — user-assigned and system-assigned, including federated identity credentials. The same DefaultAzureCredential chain that works in production works locally, no special credential type required.
RBAC — role assignments and role definitions at any ARM scope, with the standard built-in roles (Owner, Contributor, Reader, plus the service-specific data-plane roles like Storage Blob Data Contributor) pre-loaded.

This is the difference between "I can read a blob locally" and "I can run my entire authn/authz path locally". The latter catches a class of bug — token audience mismatches, role assignment drift, scope errors — that mocks never catch.

There is a dedicated post on the Entra emulation layer if you want the design details.

Where Azurite stops: ARM, Terraform, and the Azure CLI

Azurite has no ARM control plane, which means there is no az group create, no azurerm_resource_group, no Bicep deployment, no way to express the resources your application needs in the same infrastructure-as-code language you use in production. Local development and production end up using two different definitions of "what infrastructure exists".

Topaz has a working ARM emulation. The Resource Manager port (8899) accepts az and azurerm provider traffic, exposes a metadata document at the discovery endpoint that points every Azure API URL at the local emulator, and accepts ARM template / Bicep deployments end-to-end. The same terraform apply that creates resources in Azure can create them in Topaz with one provider setting:

provider "azurerm" {
  features {}
  metadata_host                   = "topaz.local.dev:8899"
  resource_provider_registrations = "none"
}

That is the entire integration. metadata_host redirects endpoint discovery; the AzureRM provider then constructs every subsequent URL — Storage, Key Vault, Service Bus, Container Registry — from Topaz's metadata document. Detail in the Terraform integration post.

The Azure CLI works the same way: register Topaz as a cloud environment with az cloud register, switch to it, and az login issues a token from the local Entra layer. From there, az keyvault secret set, az servicebus queue create, az acr login, az group deployment create all work as they do against Azure. Azurite supports az storage and only az storage.

What Azurite still does better

A genuinely honest post needs this section. Azurite is not strictly worse — it is narrower, more mature in its narrow scope, and the right call for some workloads.

Microsoft maintenance. Azurite is shipped and supported by Microsoft. Topaz is open source and maintained by an independent team. If your organisation requires vendor-supported software for local development tooling, that distinction matters.
RA-GRS secondary endpoints. Azurite emulates the read-access geo-redundant secondary URL pattern today. Topaz has partial support; full secondary endpoint semantics — secondary DNS hostnames, GeoReplicationStats payloads, and read-only enforcement — are scheduled for v1.4-beta.
The UseDevelopmentStorage=true shortcut. Azurite is hardcoded to the Azure SDK's UseDevelopmentStorage=true connection string. Topaz uses real connection strings — the same format Azure issues — which is more flexible but loses the one-line shortcut.
Visual Studio integration. Azurite ships with Visual Studio and Storage Explorer has a built-in "Local Emulator" entry. Topaz works with Storage Explorer, but you connect via a connection string rather than the dedicated emulator option.
Maturity. Azurite has been in production CI pipelines for years. Topaz is in beta as of v1.0 and is moving fast — that is also the reason this post needs to list which surfaces are not yet covered.

If your application uses only Storage, a single account is enough, and you do not need ARM or Terraform integration locally, Azurite is genuinely the simpler choice and there is no reason to switch.

What is coming for Storage in Topaz

The Storage roadmap is publicly tracked in BACKLOG.md and mirrored on the website roadmap. The near-term Storage work in flight:

v1.4-beta — SAS token validation on the data plane.
The control plane already generates SAS tokens via ListAccountSas and ListServiceSas. The data-plane security providers (Blob, Queue, Table) currently only recognise the Authorization: header — incoming requests with ?sv=...&sig=... query strings hit the missing-header path and return 401. The work in progress adds:

Account SAS validation: detects sv, ss, srt, sp, se, st, spr, sip, sig, builds the canonical Account SAS string-to-sign, HMAC-SHA256 against the account key, validates expiry / service / resource type / HTTP method.
Service SAS validation: per-service string-to-sign, including the canonicalized resource and the response-header overrides (rscc, rscd, etc.), with stored access policy lookup when si=<policyId> is present.
Stored access policy enforcement: the Container ACL / Queue ACL / Table ACL endpoints already round-trip <SignedIdentifiers> XML to disk; v1.4 wires them into the SAS validation path so revoking a named policy actually revokes the tokens that reference it.

v1.4-beta — anonymous / public-access reads for Blob containers.
Real Azure allows containers created with x-ms-blob-public-access: container (list + read) or blob (read only) to permit unauthenticated reads. Topaz currently rejects every request without an Authorization header. The fix is to store the public-access level on the container, look it up in the security provider when no auth is present, and permit the request when the level allows the operation.

v1.4-beta — RA-GRS secondary endpoint semantics.
Secondary DNS hostnames ({accountName}-secondary.*), secondaryEndpoints.blob/.table/.queue/.file in the storage account ARM response, the ?restype=service&comp=stats endpoint returning a realistic GeoReplicationStats payload, and read-only enforcement that returns 403 WriteOperationNotSupportedOnSecondary on mutating requests against a secondary endpoint.

v1.5-beta — User Delegation SAS for Blob.
The Entra-derived SAS variant. Two coordinated pieces: an ARM endpoint that mints a user delegation key bounded by (start, expiry, oid, tid), and Blob data-plane validation that recomputes the key from the stored fields and validates the signed token. This is the only SAS variant that needs the local Entra layer to be coherent with the storage layer — which is part of why Topaz is built as one process rather than five.

v1.6-beta — unified data-plane port.
Real Azure exposes Blob / Table / Queue / File on port 443 with subdomain-based routing ({account}.blob.core.windows.net, etc.). Topaz currently uses separate ports per sub-service (8891 / 8890 / 8893 / 8894) for routing simplicity. Some Azure CLI / SDK code paths construct storage URLs via get_account_url(), which builds a single https:// URL from the cloud-suffix storage_endpoint — encoding only one port. Consolidating onto a single port behind subdomain routing fixes that and makes the local URL pattern identical to production.

These are all in the public backlog with milestone labels — there is no roadmap kept in someone's head.

Developer experience: where the differences compound

The feature comparison above is the headline. The day-to-day experience matters more.

Single binary, single process, single working directory

Azurite is one process for Storage. Replicating Topaz's surface with separate emulators means orchestrating Azurite + a Service Bus emulator + a registry + a mock identity server, all writing to different directories, all logging in different formats, all started from different scripts. Every team that goes down this path eventually writes a Docker Compose file that nobody is happy with.

Topaz is one binary or one Docker image. State lives in .topaz/ next to your project. Stop the host, the state is preserved. Start it again, the state comes back. Delete the directory, the slate is clean. There is one log stream and one health check (GET /health).

MCP server for AI tooling

Topaz ships an MCP server (Topaz.MCP) that exposes the host as a set of tools any MCP-compatible client can call. The intended use case is GitHub Copilot in VS Code — drop a .vscode/mcp.json in your workspace, point it at the MCP binary, and Copilot can run RunTopazAsContainer, CreateSubscription, CreateResourceGroup, CreateKeyVault, CreateStorageAccount, CreateServiceBusNamespace, CreateContainerRegistry, and a GetConnectionStrings tool that returns ready-to-paste connection strings for everything it just provisioned.

In practice this means you can describe a local environment in natural language:

Start Topaz. Create a subscription, a resource group rg-dev in westeurope, then provision a Storage account, a Service Bus namespace with a queue named orders, and a Key Vault with a secret db-password. Output the connection strings.

…and the assistant runs the whole sequence. There is also a GetTopazStatus diagnostics tool for the case where a setup fails partway through and you want to know which ports are bound. Full details in the MCP server documentation.

Azurite has no equivalent. There is no MCP integration, no programmatic way for an AI assistant to provision a Storage account, no notion of provisioning at all — the tool exists at the data plane and stops there.

Editor and IDE integration

GitHub Copilot in VS Code works through the MCP server. The Topaz CLI (topaz) is a thin client over the host process — every command is topaz <verb> with consistent JSON output, which means it scripts cleanly from a terminal, a shell hook, a Makefile, or a CI step. A native VS Code extension is on the roadmap; for the moment, the MCP path covers the AI-assisted workflows and the CLI covers everything else.

Scaling out: CI and Docker

Topaz publishes a Docker image (topaz/host) that runs as a sidecar in any CI environment. The pattern in GitHub Actions is:

services:
  topaz:
    image: topaz/host:latest
    ports:
      - 8899:8899
      - 8898:8898
      - 8891:8891
      - 8889:8889
      - 8892:8892
    options: --health-cmd="curl -f http://localhost:8899/health || exit 1"

Then terraform apply against metadata_host = "topaz:8899" from any step. No Azure credentials in the pipeline secrets, no rate-limited subscription, no per-run cost. The same image runs as a Testcontainer inside .NET integration tests via the Topaz Testcontainers helper. The CI/CD integration guide covers GitHub Actions and Azure DevOps.

Azurite has a Docker image too. The difference is what the image emulates — Topaz's image covers the same surface this post described (Storage + Key Vault + Service Bus + Event Hubs + ACR + Entra + ARM); Azurite's covers Storage. If your CI only needs Storage, that is fine. If it needs more, Azurite forces you back to the multi-emulator orchestration problem.

ASP.NET Core integration

AddTopaz() is an extension method on IServiceCollection that provisions local Azure infrastructure at application startup — declaratively, in the same Program.cs where you wire up DI. Spin up a resource group, a Service Bus namespace, a Key Vault with seed secrets, a Storage account, all in code, all conditional on environment so the same Program.cs runs unchanged in production. Detail in the ASP.NET Core integration guide.

When to keep Azurite

Your application uses only Azure Storage and a single account is sufficient.
You need RA-GRS secondary endpoint emulation today.
You need a Microsoft-supported emulator with vendor backing.
Your toolchain is built around Azurite and migration is not worth the effort.

When to switch to Topaz

Your application uses any service beyond Storage — Key Vault, Service Bus, Event Hubs, Container Registry, Managed Identity, RBAC.
You need multiple named storage accounts in local or CI environments without manual hosts file edits.
You want a single process to replace multiple emulators and the Docker Compose file that holds them together.
You use Terraform with the azurerm provider and want a local target for terraform apply.
You want the full Azure CLI (az keyvault, az servicebus, az acr, az deployment) to work locally, not just az storage.
You want ARM-level resource management (resource groups, subscriptions, ARM templates, Bicep) in CI without a real subscription.
You want DefaultAzureCredential to work end-to-end locally without code-path divergence from production.
You want AI-assisted environment provisioning through MCP.

Migrating

For Storage specifically, Topaz implements the same data-plane APIs Azurite does. Point your existing Azure SDK clients at Topaz's endpoints and they connect without code changes — only the endpoint hostname, port, and credentials change. The one item to check during migration is authentication: Topaz always enforces SharedKey signatures on Table and Queue requests, so any request that Azurite silently accepted with a missing or invalid signature will be rejected. This is intentional — it is the same behaviour real Azure has, and catching the divergence locally is the whole point.

Beyond Storage, the API coverage docs list which operations are implemented per service. If you hit something that is not yet supported, open an issue — the backlog is publicly tracked and feedback shapes priorities.

Summary

Azurite is a good Storage emulator. Topaz is a Storage emulator that also covers Key Vault, Service Bus, Event Hubs, Container Registry, Managed Identity, RBAC, ARM, and Entra ID — in one binary, with one log stream, one working directory, and one Docker image. The Storage parity is essentially complete; the gaps that remain (SAS validation, RA-GRS, public-access reads) are scheduled and tracked in the open backlog.

If your application is Storage-only, stay on Azurite. If it is anything else — and most real Azure applications are — Topaz exists to remove the orchestration tax of running five different local emulators that were never designed to work together.

Two days chasing a SharedKey signature mismatch: fixing azurerm_storage_table_entity in Topaz

Kamil Mrzygłód — Thu, 30 Apr 2026 10:42:05 +0000

Some bugs announce themselves loudly. A null pointer in a hot path, a missing route that returns 404 to every request — the kind of thing that fails immediately and points straight at the cause. Others are quieter. They let most of the stack work correctly and only reveal themselves at the intersection of two independently correct but mutually incompatible assumptions. The azurerm_storage_table_entity failure was the second kind.

This post is an account of a two-day investigation into a persistent 401 Unauthorized response on Terraform table entity operations, the four separate bugs we found along the way, and how pairing with GitHub Copilot shaped the investigation. The fix touched authentication, HTTP routing, upsert semantics, and stream lifecycle — each uncovered only after the previous one was resolved.

You can read more about Topaz here: https://topaz.thecloudtheory.com/

The starting point

Topaz already had table storage support: accounts, tables, entity insert and query. The azurerm_storage_table Terraform resource worked. What did not work was azurerm_storage_table_entity. Any Terraform run that tried to create a table entity failed immediately:

Error: creating Entity (Partition Key "pk1" / Row Key "rk1" / ...):
  executing request: unexpected status 401 (401 Unauthorized) with EOF

The 401 was puzzling because the same storage account, created by the same Terraform run, authenticated correctly for every ARM-level operation. Listing keys worked. Creating the table worked. Only the data-plane entity operation failed.

The investigation begins: is the key the problem?

The first hypothesis was key mismatch. Terraform calls listKeys to get a storage account key and then uses it to sign data-plane requests with HMAC-SHA256. If Topaz returned a different key than it used to verify the signature, every request would fail.

To confirm or rule this out, we added diagnostic logging across the authentication path. The TableStorageSecurityProvider was modified to emit the full stored keys (as base64 and as raw bytes in hex), the received signature, the computed signature for both keys, the full Authorization header, every request header with its raw bytes, and the exact string-to-sign in hex. ListStorageAccountKeysEndpoint was modified to log a prefix of both keys on every call, so we could correlate what Terraform received with what Topaz verified against.

The first finding was that the keys were stable. Terraform's listKeys calls (there were four of them per apply — the provider is aggressive about refreshing credentials) consistently received the same key1 prefix. The key logged at verification time matched. The key mismatch hypothesis was eliminated.

Ruling out Topaz restarts

One suspicious pattern appeared in the logs: at a certain point during a test run, ARM requests started returning no route to host on port 8899. This looked like the Topaz container crashing and restarting mid-test — which would regenerate the storage keys and make Terraform's cached key stale.

We checked the Docker container lifecycle carefully. The logs showed two AMQP listener errors at startup (a known benign issue with port reuse in the Docker test environment) but no crash or restart. The no route to host was a red herring — it appeared after Terraform had already failed and was in its cleanup phase, not before. Cross-referencing the listKeys timestamps with the entity request timestamps confirmed: the key prefix was identical across all four calls in the same test run. No restart, no key regeneration.

Narrowing the scope: the isolated test

At this point we were spending time waiting for the full storage batch test to complete — roughly thirty minutes per run because Terraform retries failing requests with exponential backoff before giving up. To eliminate noise from other resources in the same test, we created a minimal isolated scenario: a single resource group, a single storage account, a single table, and a single entity. Nothing else.

resource "azurerm_storage_table_entity" "entity" {
  storage_table_id = azurerm_storage_table.tbl.id
  partition_key    = "pk1"
  row_key          = "rk1"
  entity = {
    name = "isolated-entity"
  }
}

This reduced the iteration cycle and made the logs dramatically easier to read.

The actual bug: URL encoding

With a clean log, the problem became visible. Here is what Topaz logged as the string-to-sign it computed:

GET\n\n\nThu, 30 Apr 2026 06:43:27 GMT\n/tfisoentityacct/isoentities(PartitionKey='pk1',%20RowKey='rk1')

And the TF debug log showed the URL Terraform actually sent the request to:

GET https://tfisoentityacct.table.storage.topaz.local.dev:8890/isoentities%28PartitionKey=%27pk1%27,%20RowKey=%27rk1%27%29

The entity key lookup path contains parentheses and single quotes. Terraform's go-azure-sdk encodes those: ( → %28, ' → %27. It signs the request using the raw encoded URL. ASP.NET Core receives the request and makes the decoded path available through HttpRequest.Path. When Topaz called ToString() on that path, it got the decoded form — (PartitionKey='pk1', — which is not what was signed. The HMAC computation was based on a different string than what the client used.

The fix was to read the raw request target before ASP.NET Core's decoding step using IHttpRequestFeature.RawTarget, which preserves the wire-format path exactly as the client sent it:

var rawTarget = context.Features.Get<IHttpRequestFeature>()?.RawTarget
                ?? context.Request.Path.Value
                ?? string.Empty;
var queryIndex = rawTarget.IndexOf('?');
var rawPath = queryIndex >= 0 ? rawTarget[..queryIndex] : rawTarget;

This was a one-line conceptual fix that required updating the IsRequestAuthorized call in all fourteen table endpoint classes. The base class TableDataPlaneEndpointBase was refactored to accept an HttpContext and extract the raw path internally, so all call sites became a single-argument call.

Bug two: the MERGE verb

With auth fixed, the next run reached Terraform's actual entity creation step — and hit a new error:

Request MERGE /isoentities(PartitionKey='pk1',%20RowKey='rk1') has no corresponding endpoint assigned.

The Azure Table Storage REST API uses HTTP MERGE for Insert-or-Merge operations. Topaz's InsertOrMergeTableEntityEndpoint only declared POST in its Endpoints array:

public string[] Endpoints => [@"POST /^.*?\(PartitionKey='.*?',(%20|\s)?RowKey='.*?'\)$"];

Terraform's go-azure-sdk uses MERGE as the verb. The fix was straightforward — add MERGE to the array:

public string[] Endpoints =>
[
    @"POST /^.*?\(PartitionKey='.*?',(%20|\s)?RowKey='.*?'\)$",
    @"MERGE /^.*?\(PartitionKey='.*?',(%20|\s)?RowKey='.*?'\)$",
];

Bug three: Insert-or-Merge semantics

With routing fixed, the next run returned 404 Not Found. The HandleUpdateEntityRequest path calls DataPlane.UpdateEntity, which throws EntityNotFoundException when the entity file does not exist on disk:

if(File.Exists(entityPath) == false)
{
    throw new EntityNotFoundException();
}

For a PUT (Replace) or PATCH (Merge), throwing here is correct — updating a non-existent entity should fail. But MERGE in Table Storage semantics means Insert-or-Merge: create the entity if it does not exist, merge the properties if it does. The existing code had no path for that case.

We added an UpsertEntity method to TableServiceDataPlane that writes a new entity unconditionally, and a upsert parameter to HandleUpdateEntityRequest that catches EntityNotFoundException and falls through to the upsert path:

catch (EntityNotFoundException) when (upsert)
{
    buffered!.Position = 0;
    DataPlane.UpsertEntity(buffered, subscriptionIdentifier, resourceGroupIdentifier,
        tableName, storageAccountName, partitionKey, rowKey);
    response.StatusCode = HttpStatusCode.NoContent;
}

Bug four: the disposed stream

That buffered!.Position = 0 line is significant. The first implementation of the upsert fallback passed the original input stream directly to UpsertEntity. The next test run returned 500 Internal Server Error with Cannot access a disposed object in the Topaz logs.

UpdateEntity reads the body with a StreamReader before throwing EntityNotFoundException. StreamReader disposes its underlying stream by default when it is disposed — which happens when the using var sr block exits after the throw. By the time the catch (EntityNotFoundException) when (upsert) block ran, the stream was already closed.

The fix was to buffer the request body into a MemoryStream before entering the UpdateEntity call when upsert is true, and use leaveOpen: true in UpdateEntity's StreamReader to avoid closing the memory stream on an unexpected throw:

MemoryStream? buffered = null;
if (upsert)
{
    buffered = new MemoryStream();
    input.CopyTo(buffered);
    buffered.Position = 0;
    input = buffered;
}

The test assertion

After all four bugs were fixed, Terraform reported Apply complete! Resources: 4 added, 0 changed, 0 destroyed. The test itself still failed:

System.InvalidOperationException : The node must be of type 'JsonValue'.

The terraform output -json response wraps each output in an envelope: { "partition_key": { "value": "pk1", "type": "string" } }. The initial test assertion called .GetValue<string>() directly on outputs["partition_key"], which is a JsonObject, not a JsonValue. The fix was a one-character change — navigate to ["value"] first, matching every other test in the suite.

The role of Copilot in the investigation

Copilot assisted throughout both days: adding the diagnostic logging, generating the isolated Terraform scenario and test class, and suggesting fixes as each root cause was identified. The investigation benefited from being able to express hypotheses in natural language — "could the key bytes differ even if the base64 strings match?" led immediately to logging the raw bytes in hex — and from having a second reader of the logs who could cross-reference the wire trace in the TF debug log against the canonicalization logic in the Topaz source.

The most valuable contribution was narrowing the investigation down to the URL encoding issue. The logs included a DecodedPathSTS variant that computed the signature using Uri.UnescapeDataString(absolutePath). When that also failed to match, it confirmed the issue was not simply percent-encoded spaces — it was the full encoding of the path characters. Tracing IHttpRequestFeature.RawTarget was the correct escape hatch once the root cause was understood.

What changed

Area	Change
`TableStorageSecurityProvider`	Signs against `IHttpRequestFeature.RawTarget` (raw wire path) instead of `HttpRequest.Path` (decoded)
`InsertOrMergeTableEntityEndpoint`	Added `MERGE` verb alongside `POST`
`TableServiceDataPlane`	Added `UpsertEntity`; `UpdateEntity` uses `leaveOpen: true`
`TableDataPlaneEndpointBase`	`HandleUpdateEntityRequest` accepts `upsert` flag; buffers body into `MemoryStream` for fallback
All 14 table endpoints	Updated to pass `HttpContext` to `IsRequestAuthorized`

The storage API coverage page now marks azurerm_storage_table_entity create, read, and delete as implemented. The full Terraform scenario — resource group, storage account, table, entity — runs end-to-end in roughly two minutes with no manual steps.

Takeaway

Each of the four bugs was independently plausible and independently fixable. But they were invisible until the previous one was resolved. You cannot see that MERGE is unrouted if you never get past the 401. You cannot see the upsert semantics gap if MERGE returns 404 before reaching the data plane. You cannot see the disposed stream if the upsert path is never exercised. The debugging process was necessarily sequential — each fix revealed the next layer.

The URL encoding issue is worth calling out specifically. The Azure Table Storage SharedKey algorithm requires signing the canonicalized resource, which is derived from the request URL. Whether that URL is in its raw percent-encoded form or its decoded form is not a detail the specification makes obvious. ASP.NET Core's routing infrastructure silently decodes the path before most code ever sees it. IHttpRequestFeature.RawTarget is the correct place to read the unmodified wire path, and it is not the first thing you reach for. Getting there required enough diagnostic signal to rule out every other explanation first.

Running Terraform against Azure locally, without a subscription

Kamil Mrzygłód — Tue, 14 Apr 2026 10:16:23 +0000

This posts explains how Terraform is integrated with Topaz - Azure emulator for local development and testing. You can check it here.

Every Terraform workflow that targets Azure needs the same things before it can do anything useful: an Azure subscription, a service principal or user account with the right permissions, and a network path to the Azure APIs. In a team setting you also need to make sure those credentials are available wherever terraform apply runs — local machines, CI agents, staging pipelines. The feedback loop is slow, and the blast radius for a misconfigured apply is real.

Topaz removes all of that. The same terraform apply that would create resources in Azure can instead create them in a local emulator, with no subscription, no credentials to rotate, and no cloud charges. This post explains how the integration works and how to set it up.

Why the standard AzureRM provider works at all

The key insight is that the AzureRM provider does not have Azure's API endpoints hardcoded. When it initialises, it fetches a metadata document from a discovery endpoint that describes where each Azure API lives. In a normal setup, that discovery endpoint is the Azure Resource Manager metadata endpoint at management.azure.com. Once the provider has that document, it constructs every subsequent request URL from it.

The metadata_host setting exists precisely to point that discovery step somewhere else. Set it to Topaz's ARM port, and the provider fetches Topaz's metadata document instead. That document points every API URL — authentication, resource management, Key Vault, Storage — at the local emulator. The provider never knows it is not talking to Azure.

provider "azurerm" {
  features {}
  metadata_host                    = "topaz.local.dev:8899"
  resource_provider_registrations  = "none"
}

Two settings are doing the work here. metadata_host redirects endpoint discovery to Topaz. resource_provider_registrations = "none" tells the provider not to attempt registering resource providers on startup — Topaz does not emulate the full registration flow, and it is not needed for local development anyway.

DNS setup

The hostname topaz.local.dev needs to resolve to 127.0.0.1 on your machine. Topaz ships install scripts that configure this using dnsmasq, which handles the wildcard subdomains that services like Container Registry depend on. The getting started guide covers installation and the one-time DNS and certificate setup.

For containerised environments, the same configuration can be handled at the container network level — the Terraform integration guide covers that path as well.

Authentication

AzureRM needs a credential to authenticate against whatever it thinks Azure is. With Topaz, that means authenticating against Topaz's local Entra ID emulation layer, which responds to the same OAuth2 endpoints the real Azure uses.

The simplest approach for local development is to use the Azure CLI configured for Topaz's local cloud. Once configured, az login issues a token from the local Entra layer, and the AzureRM provider picks it up through DefaultAzureCredential exactly as it would in production. No service principal, no environment variables, no secrets.

A fixed subscription ID avoids drift between runs:

topaz start \
  --default-subscription 00000000-0000-0000-0000-000000000001 \
  --log-level Information

Pair that with:

export ARM_SUBSCRIPTION_ID=00000000-0000-0000-0000-000000000001

And every terraform plan and apply targets the same subscription, the same resource IDs, and the same state — which matters when you want your CI runs to behave identically to your laptop.

A complete example

With Topaz running, this is all it takes to create a resource group and a Key Vault locally:

terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "= 4.67.0"
    }
  }
}

provider "azurerm" {
  features {}
  metadata_host                   = "topaz.local.dev:8899"
  resource_provider_registrations = "none"
}

resource "azurerm_resource_group" "example" {
  name     = "rg-local"
  location = "westeurope"
}

resource "azurerm_key_vault" "example" {
  name                = "kv-local"
  location            = azurerm_resource_group.example.location
  resource_group_name = azurerm_resource_group.example.name
  tenant_id           = "50717675-3e5e-4a1e-8cb5-c62d8be8ca48"
  sku_name            = "standard"
}

terraform init
terraform apply -auto-approve
terraform destroy -auto-approve

The tenant ID above is Topaz's built-in local tenant — the same one az login uses when configured for the local cloud.

AzAPI provider

If your Terraform configuration uses azapi resources alongside azurerm, the setup is straightforward. Keep the azurerm provider configured for Topaz metadata and add the azapi provider declaration:

terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "= 4.67.0"
    }
    azapi = {
      source = "Azure/azapi"
    }
  }
}

provider "azurerm" {
  features {}
  metadata_host                   = "topaz.local.dev:8899"
  resource_provider_registrations = "none"
}

provider "azapi" {}

Because azapi inherits its endpoint configuration from the same environment, and Topaz's metadata document covers the resource management endpoints that azapi targets, no additional configuration is needed.

Using it in CI

The setup above works identically in a CI pipeline. Run Topaz as a service container or a background step, set ARM_SUBSCRIPTION_ID, and run terraform apply as normal. No Azure credentials in the pipeline, no cost per run, no rate limiting from the Azure APIs. The CI/CD integration guide has ready-to-use examples for GitHub Actions and Azure DevOps.

What works today

Topaz currently supports Terraform workflows for Azure Storage, Key Vault, Service Bus, Event Hubs, Container Registry, and Resource Manager operations including resource groups and ARM template deployments. The API coverage docs list which operations are implemented per service.

Not every AzureRM resource type is emulated yet. If you hit a resource that Topaz does not support, the provider will return a 404 or an unsupported operation error. Check the API coverage page for current status, and open an issue if something you need is missing.