{"canonical_url":"https://engineer.company/glossary/bicep/","content_markdown":"# Bicep\n\n## What it is\n\nBicep is a language from Microsoft for writing Azure infrastructure down as\ntext: which resources exist, what they are called, how each is configured and\nhow they connect to one another. A Bicep file lists no steps. It states the end\nresult, and Azure Resource Manager, the layer Azure management requests\npass through, works out what to create, change or leave alone to get there.\nSomeone asking “what is Bicep?” usually wants to know whether it replaces\nclicking through the Azure portal. It does, and that is most of its value.\n\nUnderneath, Bicep is a friendlier way to write something Azure already\nunderstood. Resource Manager has long accepted deployment templates written in\nJSON, which are complete but hard to read and harder to review. During a\ndeployment the Bicep command-line tool converts a `.bicep` file into one of\nthose JSON templates, and Resource Manager deploys it exactly as it would a\nhand-written one. Microsoft states that Bicep supports every resource type and\nAPI version as soon as a resource provider introduces it, previews included, so\na new service is usable without waiting for anyone to update a plug-in. Existing\nJSON templates can be decompiled into Bicep, which makes moving an older estate\nacross a mechanical job rather than a rewrite.\n\nA small file shows the shape. Parameters come first, then resources, each with a\nsymbolic name the rest of the file can refer to:\n\n```text\nparam env string\nparam location string = resourceGroup().location\n\nresource store 'Microsoft.Storage/storageAccounts@2023-05-01' = {\n  name: 'st${env}${uniqueString(resourceGroup().id)}'\n  location: location\n  sku: {\n    name: 'Standard_LRS'\n  }\n  kind: 'StorageV2'\n}\n```\n\nWhen another resource mentions `store.id`, Bicep infers that it has to wait for\nthe storage account, so nobody writes the order by hand, and Resource Manager\ndeploys whatever does not depend on anything else in parallel. A file can call\nanother file as a module, which lets a team describe “a database with its\nnetwork rules” once and reuse it everywhere. Values that differ per environment\nlive in a separate `.bicepparam` file. Microsoft is explicit that Bicep is free,\nopen source and not meant as a general programming language: it has loops,\nconditions and functions, but only in service of describing resources.\n\nHow does Bicep compare with the alternatives? Against ARM JSON, it is the same\nengine with a far shorter source. Against Terraform, the main differences are\nreach and state: Terraform covers many clouds and keeps a state file of its own,\nwhile Bicep’s Azure Resource Manager workflow keeps no state file of its own,\nbecause Azure stores the deployment state. Bicep [extensions](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-extension)\nalso support resources outside Resource Manager, including Kubernetes and Microsoft Graph. Against Pulumi, which describes infrastructure in\ngeneral-purpose languages such as TypeScript or Go, Bicep trades flexibility for\na smaller language that is quick to read in review.\n\n## Why it matters\n\nInfrastructure built by hand has no history. A setting changed in the portal\nleaves no reason behind it, nobody reviews it before it happens, and rebuilding\nthe environment after a bad day depends on someone remembering every click. Once\nthe infrastructure is a set of files in the repository, it gets what application\ncode already has: a pull request, a reviewer, a history and a way back.\n\nThe second gain is sameness. Development, staging and production built from the\nsame files with different parameters differ only where the parameters say they\ndo. Bicep deployments are idempotent, which in Microsoft's words means the same\nfile deployed many times gives “the same resource types in the same state”. A\ndeployment is therefore safe to repeat, and a fresh environment is the same\ncommand pointed at a new resource group.\n\nThe third is visibility before change. The what-if operation compares a file\nwith what is running and lists each resource it would create, modify or delete\nbefore anything is touched. Paired with a pull request, that preview turns “I\nthink this only changes the firewall rule” into something a reviewer can check.\n\nThe costs are worth naming. Resource coverage depends on the deployment workflow and its extensions, so DNS\nat another provider or resources in a second cloud may still need a separate tool.\nIn the Resource Manager workflow, Bicep describes Azure resources; packages and\nfiles inside a virtual machine belong to configuration management such as Ansible. And Resource\nManager's defaults around deletion and redeployment surprise people who expect a\ndesired-state tool to remove what the file no longer mentions, which section\nfour covers.\n\n## What it looks like in practice\n\nSeveral of the Azure projects on this site rest on Bicep, and three show what it\ndoes for a team over time.\n\nOn one platform the whole Azure estate is written in Bicep.\n[Every environment comes out of the same templates](/portfolio/provisioned-azure-infrastructure-as-code/):\nthe api and www as Azure Container Apps, a PostgreSQL Flexible Server, Redis for\ncaching, Front Door with a WAF policy in front, and the network underneath it\n(VNet, NSG, private DNS), with Log Analytics wired in for diagnostics and images\npulled from the project's Azure Container Registry. Because it is all\nparameterised, standing up a new environment or changing an existing one is a\npull request. The page reports the result as environments that became\nreproducible and reviewable, and drift that stopped being a mystery because the\ncode is the source of truth.\n\nThe same templates carry the release path.\n[Releases move from development to staging to production](/portfolio/owned-end-to-end-platform-deployments-to-azure/),\nand the Bicep keeps the target infrastructure identical from one environment to\nthe next, so a build is never promoted into a subtly different place.\nConfiguration that differs per environment is kept apart from the secrets, which\nlets one built artefact pass through every stage without a rebuild.\n\nAnd Bicep holds part of the recovery plan.\n[Backup retention is configured in the Bicep beside the database it protects](/portfolio/implemented-backups-and-disaster-recovery-as-code/),\nso point-in-time restore is a property of the template rather than a setting\nsomeone once clicked. The environment around the database is code too, which\nmatters because restoring data into an environment that has to be rebuilt from\nmemory is hardly recovery. The page then names what remains open: geo-redundancy\nis switched off, and the recovery-time objective is proposed rather than\nmeasured. A template shows what is configured; only a drill shows how long a\nrestore takes.\n\n## Where it goes wrong\n\nMost Bicep trouble comes from expecting it to behave like a tool that owns\neverything in a resource group. By default it owns only what the file mentions,\nand only in the way the file says.\n\n**A setting changed in the portal disappears at the next deployment.**\nRedeploying a resource reapplies all of its properties, and any property the\ntemplate leaves out is reset to its default. A hotfix made by hand during an\nincident is undone by the next routine release. Treat the file as the full final\nstate of each resource, write every non-default value into it, and make urgent\nchanges through a pull request. A deployment stack's deny settings can block\nedits outside the deployment altogether.\n\n**A resource removed from the template keeps running and keeps costing money.**\nThe default deployment mode is incremental: resources in the resource group that\nthe file does not mention are left alone. Delete a database from the code and it\nstays in Azure. Microsoft's answer is deployment stacks. A stack records the\nresources it manages, and its `actionOnUnmanage` setting decides whether one\nthat drops out of the file is detached or deleted. Complete mode also deletes\nwhat the file omits, but Microsoft recommends against it and is phasing it out.\n\n**The what-if preview lists changes nobody made.** A property the file leaves\nout, but that Azure fills in with a default during deployment, can be reported\nas deleted, and Microsoft calls this noise. Any property set from the\n`reference` function is reported as changing every time, and values such as\n`utcNow()` or a secure parameter exist only during the deployment, so what-if\nshows them unevaluated. Run it on every pull request, read it as a draft, and\nset the noisy properties explicitly so the real changes stand out:\n\n```sh\naz deployment group what-if \\\n  --resource-group rg-staging \\\n  --template-file main.bicep \\\n  --parameters staging.bicepparam\n```\n\n**A password shows up in the deployment history.** A plain string parameter is\nrecorded with the deployment, where anyone with read access to the deployment\nhistory can see it. Mark secret parameters with the `@secure()` decorator, which\nkeeps the value out of deployment history and logs, and keep the secret itself\nin Key Vault rather than in a parameter file in the repository.\n\n## Further reading\n\n- [What is Bicep?](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/overview)\n  — Microsoft's own overview: the language, its benefits and what it is not\n  trying to be.\n- [Bicep modules](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/modules)\n  — splitting a deployment into files that call each other.\n- [Parameters in Bicep files](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/parameters)\n  — types, decorators, defaults, and what `@secure()` keeps out of the history.\n- [Deployment modes](https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/deployment-modes)\n  — incremental against complete, and what each does with resources the file\n  does not mention.\n- [Bicep deployment what-if operation](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/deploy-what-if)\n  — previewing a deployment, the change types and the known sources of noise.\n- [Deployment stacks](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/deployment-stacks)\n  — managing resources as one unit, with deletion and deny settings.\n\n\u003chttps://engineer.company/glossary/bicep/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"What Bicep is, how it compares with ARM JSON and Terraform, how one set of files keeps Azure environments alike, and the four mistakes that bite most.","formats":{"gemtext":"https://engineer.company/glossary/bicep/index.gmi","gopher":"https://engineer.company/glossary/bicep/gophermap","html":"https://engineer.company/glossary/bicep/","json":"https://engineer.company/glossary/bicep/index.json","markdown":"https://engineer.company/glossary/bicep/index.md","pdf":"https://engineer.company/glossary/bicep/index.pdf"},"kind":"page","language":"en","title":"What is Bicep?","url":"https://engineer.company/glossary/bicep/","version":1}