Kamil Mrzygłód

Until recently, topaz start was the only way to run the emulator. That single command lived inside the CLI, started the Host, and stayed running in your terminal. Useful for getting going quickly. Less useful once you want to script around it, automate it in CI, or distribute the two halves independently.

This post walks through why the split was done, how the boundary between Host and CLI works in practice, and what the health-check endpoint makes possible from any language.

I wanted to run Terraform locally against infrastructure emulated on my laptop, without an Azure subscription and without worrying about credentials leaking into my CI pipeline. At first it seemed cumbersome. As it turns out, the setup is straightforward, and it exposed something interesting about how the AzureRM provider actually discovers its endpoints.

Every Terraform workflow targeting Azure needs 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 credentials 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 locally, with no subscription, no credentials to rotate, and no cloud charges. Here is how the integration works and how to set it up.

Running the full test suite on every commit is simple to set up and expensive to live with. Topaz spans twelve services, each with its own E2E tests and Azure CLI tests. On a change to a single endpoint in the Container Registry service, waiting for Key Vault, Service Bus, and Event Hubs tests to finish is pure overhead. The Topaz CI pipeline solves this with a three-stage decision that maps changed files to a focused test filter — running everything only when it has to.

The previous post on ACR authentication covered everything up to the point where docker login succeeds and Docker has a valid Bearer token. That is the precondition. The question this post answers is what happens next: how docker push transfers a real image into Topaz and why the protocol is more structured than a simple file upload.

Container Registry is different from every other Azure service Topaz emulates. You do not call it through the Azure SDK with a credential — you call it through the Docker CLI, docker pull, docker push, helm push, or any OCI-compliant client. Before any of that works, the client has to authenticate. And that authentication flow is entirely its own protocol, separate from anything in the Azure REST API.

This post walks through how Topaz emulates the ACR data plane authentication layer and what design decisions made it possible without writing a custom token server.

After months of alpha development, Topaz is moving to beta. The core emulation layer is stable, the service catalogue has grown considerably, and the rough edges that made early adopters cautious are largely gone. This post walks through what changed and what is currently available.

Authentication is the first thing every Azure SDK touches. Before your application can read a secret from Key Vault, publish a message to Service Bus, or query a storage account, it needs a valid token. That token comes from Microsoft Entra ID. Without a working Entra emulation layer, every other Azure service emulator is incomplete — your code would still call out to login.microsoftonline.com even in a fully local setup.

Topaz solves this by shipping a full Entra ID emulation layer out of the box.

Emulation of a service isn't complete if the authorization layer isn't emulated as well. This is why Topaz will introduce authorization mechanism for various services, starting with Table Storage.

After giving it some initial dry runs and validating the overall concept, Topaz has been publicly announced.