Local Azure emulator: how to use Floci with Terraform (what works and what doesn't)

In short: Floci is a local Azure emulator: it runs in Docker and answers as if it were Azure, so Terraform and the CLI talk to your computer instead of the cloud. It's useful for practicing with no account, no credit card and no fear of leaving something running. In this guide I start it with Docker Compose, configure the azurerm provider and try three examples copied from the official Terraform documentation: a PostgreSQL Flexible Server (it's a real Postgres), a virtual machine (it says running, but nothing runs) and an AKS cluster (under the hood, it's k3s). I also cover the errors that came up and how I fixed them.

This article goes with the video above. If you'd rather read, everything is here step by step, with code blocks ready to copy. The full code is in the repository: https://github.com/kevorojas/floci-azure-terraform.

Tested versions: floci-az 0.13.0, azurerm provider 5.8.0 and Terraform 1.14.3, on macOS with Docker. Floci moves fast: with other versions, some details may differ.

What is Floci and what is it for?

Floci is a cloud emulator that runs on your computer. It emulates the AWS, Azure, Google Cloud and Oracle Cloud APIs, each on its own port. Your Terraform, CLI or SDK think they're talking to the cloud, but they're actually talking to a container on your machine.

It started as a free alternative to LocalStack. In this guide I focus on Azure.

What is it for? Learning and practicing Azure without an account. Many people can't put a credit card down to open a subscription, and those who can have the usual fear: forgetting something running and getting the bill. With Floci you can create, break and destroy resources with Terraform as many times as you want, and nothing leaves your computer.

What it isn't: it isn't Azure at home. Some services are real (a PostgreSQL database actually works) and others only exist in the "control plane": the API says they were created, but there's nothing behind them. Each one is covered in detail below.

What you need before starting

• Docker (on Mac, Docker Desktop) with Docker Compose.
• Terraform 1.6 or later. I used 1.14.3.
• The azurerm 5.x provider. Terraform downloads it with terraform init.
• No Azure account. No az login, no subscription, no credit card.
• Optional: pgAdmin or psql for the PostgreSQL example, and kubectl and jq for the AKS one.
• Optional: git, if you're going to build the image AKS needs (explained in its section).

Operating system: I tested everything on macOS. The TLS certificate step is Mac-specific. I didn't test Linux or Windows.

Running the local Azure emulator with Docker Compose

This is the minimal docker-compose.yml to get Azure on your computer:

name: floci-azure

services:
  floci-az:
    image: floci/floci-az:0.13.0
    ports:
      - "127.0.0.1:4577:4577"
    volumes:
      # PostgreSQL, AKS (k3s) and non-mocked VMs are containers Floci creates in your Docker
      - /var/run/docker.sock:/var/run/docker.sock
      # Keeps the TLS certificate so you don't have to trust it again on every start
      - ./data:/app/data
    environment:
      # The Azure provider discovers the cloud over HTTPS: without TLS it won't start
      FLOCI_AZ_TLS_ENABLED: "true"
      # Everything in memory: if the container restarts, everything is lost
      FLOCI_AZ_STORAGE_MODE: memory
      # "true": VMs are control plane only (they say running, but nothing runs)
      FLOCI_AZ_SERVICES_VM_MOCKED: "true"

Start it with one command:

docker compose up -d
docker compose ps

It's up in a couple of seconds.

In the repo (https://github.com/kevorojas/floci-azure-terraform) the compose file also starts the AWS, Google Cloud and Oracle emulators, plus Floci's web UI, which shows your resources like a console. In Settings > Cloud you pick the cloud, and each one has its own console with the available services and the ones still coming. It's not the Azure portal, but it's handy to see what you created.

Two security details about the compose file:

• Ports are bound to 127.0.0.1. The emulators have no authentication, so don't expose them to your network.
• Floci mounts the Docker socket (/var/run/docker.sock) because it creates containers for PostgreSQL and AKS. That gives it full control over your Docker: only use it on your test machine.

Checking that it answers

Floci publishes its cloud "endpoints", just like Azure. If it answers with localhost addresses, you're good:

/usr/bin/curl -s "https://localhost:4577/metadata/endpoints?api-version=2022-09-01"

If this fails because of the certificate, that's expected: the next section fixes it. On Mac I use /usr/bin/curl (the system one) on purpose: a curl installed by another package manager may not read the macOS keychain.

Trusting Floci's TLS certificate (macOS)

Floci serves its API over HTTPS with its own certificate. Terraform doesn't trust it, so terraform init works, but the first terraform plan fails with something like:

Error: retrieving metadata from endpoint "https://localhost:4577": ...
tls: failed to verify certificate: x509: certificate signed by unknown authority

Adding the certificate to the system keychain

On startup, Floci generates its certificate authority (CA) in ./data/tls/. On macOS you add it to the system keychain:

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain ./data/tls/floci-az-selfsigned-ca.crt

After that, terraform plan works.

SSL_CERT_FILE doesn't work on macOS. Floci's documentation suggests that environment variable, but on Mac Terraform uses the system certificate verifier and ignores it. I tried it and the error stayed the same. Only the keychain worked.

Since the compose file mounts ./data, the certificate survives restarts and you don't need to trust it again. If you delete that folder, Floci generates a new CA and you have to repeat the step.

Removing the certificate when you're done

Adding a CA to the system keychain makes your Mac trust everything that CA signs. When you stop using Floci, remove it. First remove the trust, then the certificate (Floci's CA is named floci-az-ca):

sudo security remove-trusted-cert -d ./data/tls/floci-az-selfsigned-ca.crt
sudo security delete-certificate -c floci-az-ca /Library/Keychains/System.keychain

You can also do it from the Keychain Access app: System keychain, search for floci-az-ca and delete it. If you trusted more than one Floci CA (for example, because you deleted ./data), delete-certificate -c complains that there's more than one match; in that case it's easier to delete them from the app.

Terraform against Floci: only the provider changes

This is the core idea: your Terraform resources are the same ones you'd use on real Azure. What changes is the azurerm provider configuration.

First, the terraform block (as usual):

terraform {
  required_version = ">= 1.6"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 5.0"
    }
  }
}

This is a normal provider, against real Azure:

provider "azurerm" {
  features {}

  subscription_id = "<your-subscription-id>"
  # Authentication comes from your `az login` session
  # (or from a service principal or OIDC in a pipeline)
}

And this is the same provider pointing to Floci:

provider "azurerm" {
  features {}

  # 1. Ask Floci, on localhost, for the cloud's addresses
  metadata_host = "localhost:4577"

  # 2. Don't use your `az login` session
  use_cli = false

  # 3. Don't try to register resource providers
  resource_provider_registrations = "none"

  # 4. Fake credentials: Floci doesn't validate them and real Azure would reject them
  subscription_id = "00000000-0000-0000-0000-000000000001"
  tenant_id       = "00000000-0000-0000-0000-000000000002"
  client_id       = "00000000-0000-0000-0000-000000000003"
  client_secret   = "fake-secret"
}

The four differences, one by one

1. metadata_host. The Azure provider starts by asking for the list of cloud addresses (where Resource Manager is, where login is, where storage is). With metadata_host it asks Floci on localhost:4577 instead of the public cloud. Floci's documentation also adds environment = "stack", but the provider ignores it when metadata_host is set, so I left it out.
2. use_cli = false. If you don't give it credentials, the provider falls back to your Azure CLI's by default. I turn that off so there's no way it uses your real session, even if you have an az login open.
3. resource_provider_registrations = "none". Stops the provider from trying to register resource providers in the subscription. In azurerm 5.x it's already the default, so you can omit it; in 4.x you need it.
4. Fake credentials. Floci doesn't validate credentials. And if, by mistake, Terraform ended up talking to real Azure, these credentials would fail. It's a second safety net.

Watch out for Floci's documentation. It currently uses skip_provider_registration = true. That argument no longer exists in azurerm 4 and 5, and if you copy it as is, Terraform answers An argument named "skip_provider_registration" is not expected here. If you're on azurerm 3.x, that one is still the right argument.

One more rule: don't have ARM_* variables from a real subscription exported in the terminal where you work with Floci.

Extra safety belt (optional). If you use a variable instead of hardcoding the host, you can prevent it from pointing anywhere other than your computer:

variable "floci_host" {
  description = "floci-az host:port"
  type        = string
  default     = "localhost:4577"

  validation {
    condition     = can(regex("^(localhost|127\\.0\\.0\\.1):[0-9]+$", var.floci_host))
    error_message = "Only the local emulator (localhost:PORT) is allowed."
  }
}

And in the provider: metadata_host = var.floci_host.

Example 1: PostgreSQL Flexible Server, a real database

The first example comes from the official documentation for the azurerm_postgresql_flexible_server resource in the Terraform registry. The docs build a private server with a VNet, a delegated subnet and private DNS; I simplified it to a server with public access, and removed the provider block the example ships with, because it already lives in providers.tf (if you keep it, Terraform fails with Duplicate provider configuration).

Folder 01-postgresql/main.tf:

resource "azurerm_resource_group" "rg" {
  name     = "rg-floci-demo"
  location = "West Europe"
}

resource "azurerm_postgresql_flexible_server" "psql" {
  name                          = "example-psqlflexibleserver"
  resource_group_name           = azurerm_resource_group.rg.name
  location                      = azurerm_resource_group.rg.location
  version                       = "12"
  public_network_access_enabled = true
  administrator_login           = "psqladmin"
  administrator_password        = "H@Sh1CoR3!"
  zone                          = "1"

  storage_mb   = 32768
  storage_tier = "P4"

  sku_name   = "B_Standard_B1ms"
  depends_on = [azurerm_resource_group.rg]
}

About the password: it's the one from the documentation example and it doesn't matter here, because everything stays on your computer. In a real project it goes in a sensitive variable or a Key Vault, never hardcoded.

cd 01-postgresql
terraform init
terraform plan     # 2 resources: the resource group and the server
terraform apply

The apply isn't instant: expect a minute or two. When it's done, Floci's UI shows the server and its JSON, shaped just like it would be in Azure.

It's a real PostgreSQL

This is the interesting part: it's not a simulation. Floci starts a PostgreSQL container in your Docker:

docker ps --filter name=floci-az-pg-

The container is named floci-az-pg- plus the server name. Docker maps it to a random port on your machine; to find it:

docker port floci-az-pg-example-psqlflexibleserver 5432

Floci also reports a connection host, but it's the container's internal Docker name and doesn't work from your computer. Use localhost and the port from docker port.

Connecting with pgAdmin

In pgAdmin, register a new server with these values:

It connects, and you can create tables, insert rows and query like in any PostgreSQL. If you create a table from pgAdmin and refresh Floci's UI, it shows up there too: it's the same database.

With psql it's the same:

psql "host=127.0.0.1 port=<PORT> dbname=postgres user=psqladmin password=H@Sh1CoR3! sslmode=disable"

A curious detail: in Terraform I asked for version 12, and Terraform and the API both say "12". But if you ask the database with SELECT version();, in my test it answered PostgreSQL 17.11. Floci uses the postgres:17-alpine image regardless of the version you request.

Since it's a real Postgres, you can go further: add Terraform's PostgreSQL provider and create databases, roles or schemas as infrastructure as code, all without spending anything.

Example 2: a virtual machine that says running and doesn't exist

The second example is a Linux VM, also from the official documentation (azurerm_linux_virtual_machine). I don't create another resource group: I reuse the one from example 1 with a data block. That's why this folder is applied after 01-postgresql.

Folder 02-vm/main.tf:

data "azurerm_resource_group" "rg" {
  name = "rg-floci-demo"
}

resource "azurerm_virtual_network" "example" {
  name                = "example-network"
  address_space       = ["10.0.0.0/16"]
  location            = data.azurerm_resource_group.rg.location
  resource_group_name = data.azurerm_resource_group.rg.name
}

resource "azurerm_subnet" "example" {
  name                 = "internal"
  resource_group_name  = data.azurerm_resource_group.rg.name
  virtual_network_name = azurerm_virtual_network.example.name
  address_prefixes     = ["10.0.2.0/24"]
}

resource "azurerm_network_interface" "example" {
  name                = "example-nic"
  location            = data.azurerm_resource_group.rg.location
  resource_group_name = data.azurerm_resource_group.rg.name

  ip_configuration {
    name                          = "internal"
    subnet_id                     = azurerm_subnet.example.id
    private_ip_address_allocation = "Dynamic"
  }
}

resource "azurerm_linux_virtual_machine" "example" {
  name                = "example-machine"
  resource_group_name = data.azurerm_resource_group.rg.name
  location            = data.azurerm_resource_group.rg.location
  size                = "Standard_D4_v5"
  admin_username      = "adminuser"
  network_interface_ids = [
    azurerm_network_interface.example.id,
  ]

  admin_ssh_key {
    username   = "adminuser"
    public_key = file("${path.module}/demo_id_rsa.pub")
  }

  os_disk {
    caching              = "ReadWrite"
    storage_account_type = "Standard_LRS"
  }

  source_image_reference {
    publisher = "Canonical"
    offer     = "0001-com-ubuntu-server-jammy"
    sku       = "22_04-lts"
    version   = "latest"
  }
}

The documentation uses file("~/.ssh/id_rsa.pub"), your personal key. For practice I prefer a throwaway key inside the folder, kept apart from yours:

cd ../02-vm
ssh-keygen -t rsa -b 4096 -f ./demo_id_rsa -N ""
terraform init
terraform apply    # 4 resources: network, subnet, network interface and VM

The apply succeeds and Floci's UI shows the VM as running. But if you look at your containers:

docker ps

They're the same as before. No machine was created. With the default settings, the VM is control plane only: the API says it exists and it's on, and there's nothing behind it.

The network doesn't do anything either. The subnet is 10.0.2.0/24, but in my test the VM's network interface got the IP 10.0.0.4: it isn't even inside its own subnet. VNets, subnets and security groups exist for Terraform, but they don't isolate anything.

If you want the VM to be something: with FLOCI_AZ_SERVICES_VM_MOCKED: "false" in the compose file, each VM becomes an ubuntu:22.04 container. It's still not a VM: no kernel of its own, your user isn't there, the SSH key isn't there and there's no sshd. Starting and stopping the VM does start and stop the container.

So is it useful? Yes, for what it is: practicing Terraform syntax, dependencies between resources and the plan, apply and destroy cycle. It's no good for testing what happens inside the machine.

Example 3: AKS, which is really k3s

The third example is a Kubernetes cluster with azurerm_kubernetes_cluster, also copied from the documentation. Floci doesn't create an AKS cluster, of course: it starts a k3s container (a lightweight Kubernetes distribution) and presents it as AKS. It's real Kubernetes: kubectl get nodes answers and you can deploy pods.

First, the right image (bug #264)

With the official floci/floci-az:0.13.0 image, the AKS apply never finishes: the k3s container starts and works, but Floci doesn't notice and the cluster stays in Creating forever. It's bug floci-az#264, still open as I write this. The cause is that the native image doesn't have HTTPS enabled in a Java library it uses to check that k3s is ready.

What worked: building the JVM image from the 0.13.0 source. It takes about 6 minutes:

git clone --depth 1 --branch 0.13.0 https://github.com/floci-io/floci-az.git /tmp/floci-az
docker build -t floci-az-jvm-local:0.13.0 -f /tmp/floci-az/docker/Dockerfile /tmp/floci-az

And in the compose file, swap the image:

    image: floci-az-jvm-local:0.13.0

Do this before you start. Changing the image recreates the Floci container, and since state lives in memory, you lose everything you had created. If you're going to try AKS, start with the JVM image from the beginning; the other examples work the same with it.

The code

Folder 03-aks/main.tf:

data "azurerm_resource_group" "rg" {
  name = "rg-floci-demo"
}

resource "azurerm_kubernetes_cluster" "example" {
  name                = "example-aks1"
  location            = data.azurerm_resource_group.rg.location
  resource_group_name = data.azurerm_resource_group.rg.name
  dns_prefix          = "exampleaks1"

  node_provisioning_profile {
    mode = "Manual"
  }

  default_node_pool {
    name       = "default"
    node_count = 1
    vm_size    = "Standard_D2_v2"
  }

  identity {
    type = "SystemAssigned"
  }

  tags = {
    Environment = "Production"
  }
}

output "cluster_id" {
  value = azurerm_kubernetes_cluster.example.id
}

Two differences from the documentation:

• node_provisioning_profile. The azurerm 5.8.0 docs example doesn't validate against its own provider: it fails with Insufficient node_provisioning_profile blocks. That's not Floci's fault; the same happens on real Azure. Adding the block with mode = "Manual" fixes it.
• No kube_config outputs. The docs include outputs with kube_config[0].client_certificate and kube_config_raw. With Floci 0.13.0 they fail with Invalid index, because Floci returns the kubeconfig under a different name than the one the provider looks for, so kube_config ends up empty. I replaced them with the cluster ID, which you can use to request the kubeconfig by hand.

cd ../03-aks
terraform init
terraform apply

The first time, Docker pulls the rancher/k3s image (almost 2 minutes in my test). With the image already pulled, the apply took about 30 seconds.

Getting the kubeconfig and using kubectl

Since the provider doesn't get the kubeconfig, I ask Floci's API for it and point the server address to 127.0.0.1:

ID=$(terraform output -raw cluster_id)

/usr/bin/curl -s -X POST "https://localhost:4577${ID}/listClusterAdminCredential?api-version=2025-07-01" \
  | jq -r '.kubeconfigs[0].value' | base64 -d \
  | sed -E 's#server: https://[^:]+:([0-9]+)#server: https://127.0.0.1:\1#' > kubeconfig-floci

kubectl --kubeconfig kubeconfig-floci get nodes
kubectl --kubeconfig kubeconfig-floci create deployment hola --image=nginx:alpine
kubectl --kubeconfig kubeconfig-floci get pods

In my test, get nodes showed one Ready node running k3s v1.34.1, and the nginx deployment reached Running. With this you can practice a full flow: create the cluster with Terraform and then deploy things on top with the Kubernetes provider.

Real errors and how I fixed them

None of the examples worked when copied as is. These are the errors that came up, in order:

Plans that never come out clean

There's another detail that isn't an error, but it's annoying: after apply, the next terraform plan doesn't always say "No changes". Floci doesn't store some fields, and Terraform wants to set them again:

• PostgreSQL: zone = "1" shows up on every plan.
• VM: additional_capabilities stays at "1 to change".
• AKS: the node pool type, identity and other fields. This is the serious one: the plan wants to destroy and recreate the cluster.

For practice, lifecycle { ignore_changes = [...] } solves it. For example, on the PostgreSQL server:

  lifecycle {
    ignore_changes = [zone]
  }

And on AKS:

  lifecycle {
    ignore_changes = [
      default_node_pool[0].type,
      identity,
      node_provisioning_profile,
      oidc_issuer_enabled,
      support_plan,
      node_os_upgrade_channel,
    ]
  }

Keep in mind: those ignore_changes exist only because of the emulator. If you later take the same code to real Azure, remove them.

What works and what doesn't in Floci for Azure

This is what I tested with floci-az 0.13.0. Floci emulates many more services, but here I only state what I saw working.

About Storage, because there's a trap: Floci reports storage endpoints using Azure's real domain (<account>.blob.core.windows.net). And the account name in the official azurerm_storage_blob example exists in real Azure: when creating the account, azurerm 4.x queries those endpoints (I saw it in my test; with 5.8.0 I didn't observe it), so copying that example without changing the name can end up sending requests to someone else's account. If you try storage, use your own unusual account name. Also, with azurerm 5.x, azurerm_storage_container always fails against Floci, and azurerm_storage_blob uploads the file and then fails with 501 Not Implemented. In my test I created the container and the blob with the Azure CLI pointed at Floci. That's why storage didn't make it into the video.

When should you use Floci, and when not?

Good for:

• Learning Azure and Terraform with no account, no credit card and no fear of a bill.
• Iterating on Terraform modules: trying syntax, dependencies and the plan/apply/destroy cycle many times, fast.
• Tests with real databases: PostgreSQL is real, so you can try scripts, migrations or the PostgreSQL provider.
• Practicing Kubernetes on something that's created like an AKS cluster.

Not good for:

• Permissions. There's no real RBAC: Floci accepts any credentials.
• Private networking and isolation. VNets, subnets and network rules do nothing.
• Virtual machines. There's no VM behind them.
• Security testing of any kind.
• Validating that your code works on Azure. The ignore_changes and tweaks in this guide are only for the emulator. Whatever you're taking to production, test it on real Azure.

I wish I'd had something like this when I was learning.

Everything lives in memory

With FLOCI_AZ_STORAGE_MODE: memory, Floci's state lives in the container's memory. If the container restarts, everything you created is gone. Your terraform.tfstate, on the other hand, still says the resources exist; a terraform apply creates them again.

Floci has persistence modes. I tried hybrid mode and for practice it was worse: after a restart the resource groups and networks were gone, but the PostgreSQL server was left half-there, in Creating with no container. For practice, I stick with memory.

Cleanup: leaving your computer as it was

Destroy in reverse order, because 02-vm and 03-aks depend on the resource group from 01-postgresql:

cd 03-aks && terraform destroy
cd ../02-vm && terraform destroy
cd ../01-postgresql && terraform destroy
cd .. && docker compose down

Floci creates containers outside the compose project (PostgreSQL, k3s and, if you turned mocking off, the VMs). When Floci shuts down, the PostgreSQL one is removed, but the k3s and VM containers can be left orphaned (k3s even keeps running). All of them carry the floci_emulator=floci-az label:

docker ps -a --filter label=floci_emulator=floci-az
docker rm -f $(docker ps -aq --filter label=floci_emulator=floci-az)

If you run another Floci on the same machine, that filter finds its containers too. Check the list before deleting.

While they're alive, the PostgreSQL and k3s containers publish their ports on every network interface (0.0.0.0), not just 127.0.0.1. With the example password, anyone on your network could connect to that Postgres. Don't leave them running on a public network, and delete them when you're done.

Finally, if you won't use Floci again, remove the certificate from the keychain (the commands are in the certificate section) and, to free up space, delete the floci-az-jvm-local:0.13.0, rancher/k3s and postgres:17-alpine images.

Frequently asked questions

Do I need an Azure account to use Floci? No. The provider uses fake credentials and use_cli = false, and Floci doesn't validate credentials. You don't need a subscription, az login or a credit card.

Does Floci work with Terraform and the azurerm 5 provider? Yes. I tested it with azurerm 5.8.0 and Terraform 1.14.3. You need metadata_host, and instead of skip_provider_registration (gone in 4 and 5) you use resource_provider_registrations = "none".

Are the resources Floci creates real? It depends on the service. PostgreSQL and AKS start real containers (Postgres and k3s). VMs and networks are control plane only: the API says they exist, but there's nothing behind them.

Does it work on Windows or Linux? Floci runs on Docker, but I only tested it on macOS. The TLS certificate step is different on each operating system and I didn't verify it outside Mac.

Is what I create kept if I restart Floci? No, with the setup in this guide everything lives in memory. A terraform apply creates it again.

Next steps

With this you have a practice Azure on your computer. The idea I want to keep exploring is using the emulator as a first step: write and test the Terraform locally as much as possible, then take that same configuration to real Azure.

That's the plan for the Terraform series I'm building: a private architecture on Azure Container Apps, built layer by layer with Terraform.

The code for this guide is at https://github.com/kevorojas/floci-azure-terraform. And if there's an Azure service you'd like to see tested on Floci, leave it in the video's comments.