Cram sheet — Automate deployment by using ARM templates or Bicep files

Twenty questions, and the majority of them turn on one sentence in the documentation that contradicts what most people assume: an incremental deployment is not a partial update.

The two deployment modes

• The default mode is incremental.
• Incremental: Resource Manager leaves unchanged resources that exist in the resource group but are not in the template. Resources in the template are added.
• Complete: Resource Manager deletes resources that exist in the resource group but are not in the template. Complete mode is no longer recommended and is being gradually deprecated in favour of deployment stacks.
• Always run what-if before a complete-mode deployment — it is the documented advice, and the reason is that the deletion is not announced any other way.

The sentence that decides this topic

⚠ Incremental does not mean partial. From the documentation, on redeploying an existing resource in incremental mode:

all properties are reapplied. The properties aren't incrementally added. A common misunderstanding is to think properties that aren't specified in the template are left unchanged.

Properties you leave out are reset to their default values. The resource definition in a template is always the final state of the resource; it cannot express a partial update. So the correct answer to "how do I change one setting without disturbing the others" is never "omit the others" — it is to specify every non-default value you want to keep.

What-if, export and decompile

• what-if predicts. It makes no changes to existing resources, and it works at resource group, subscription, management group and tenant scope.
• ⚠ what-if cannot see through a templateLink: resources deployed via template links inside nested deployments, template specs included, do not appear in the results. A clean what-if is not proof that nothing else changes.
• Decompiling JSON to Bicep is best-effort: there is no guaranteed mapping, you may have to fix warnings and errors, and decompilation can fail outright where an accurate conversion is not possible.

Traps

Check yourself

Where these figures come from

Every figure above was read from the raw documentation below on the day this sheet was written. The sha1 is git hash-object over the bytes as fetched, so a doc that changes underneath this sheet can be detected rather than assumed.