Azure / Azure/Azure-Verified-Modules
Define AVM ownership and removal semantics for azapi_update_resource
- Dominant language
- PowerShell
- Stars
- 580
- Forks
- 161
- Avg merge
- 11h 3m
- Merged PRs (30d)
- 15
Description
## Problem
`azapi_update_resource` implements partial ownership: it GETs the existing resource, merges the configured body over the response, and PUTs the result. A property omitted from Terraform therefore remains in Azure. With `ignore_missing_property = true` by default, the stale remote property can also disappear from Terraform's comparison, leaving a clean plan.
That behavior is valid for a resource intended to manage only a subset of a larger object. It is unsafe when an AVM module presents a map or nested object as fully managed and consumers reasonably expect removing configuration to remove it remotely.
Azure/terraform-azurerm-avm-res-web-site#377 demonstrated the failure mode. It fixed non-convergent null drift by omitting nested authentication and backup objects. The plans became clean, but removed authorization policies and schedules could remain live. Azure/terraform-azurerm-avm-res-web-site#384 now takes a revert-first approach and retains special handling only for the two Azure response shapes actually observed.
## Scope of impact
Potentially affected modules have all of these characteristics:
1. They use `azapi_update_resource`.
2. Their public interface implies ownership of optional properties, nested objects, or map entries.
3. A consumer can remove a previously configured value.
4. The implementation represents removal by omitting the property.
Mocked Terraform tests do not expose this behavior because they stop at the rendered body; the GET-merge-PUT happens inside the provider against a live resource.
## Guidance needed
Please define AVM-wide rules for choosing `azapi_update_resource` versus replacement semantics. At minimum, I believe the guidance should state:
- Omission from an `azapi_update_resource` body means "stop managing/preserve remote value", not "clear".
- A module must not claim complete ownership or removal behavior unless it uses replacement semantics or an explicit service-verified clearing representation.
- Reviews changing `property = condition ? value : null` into conditional omission must treat that as a behavior change on `azapi_update_resource`.
- Removal-sensitive behavior needs configured-to-removed transition coverage against Azure; mocked body assertions are not sufficient.
- Existing AVM modules using `azapi_update_resource` should be audited for interfaces whose apparent ownership exceeds the provider's partial-merge semantics.
The durable remediation may require provider features, state-preserving migrations to `azapi_resource`, or explicit partial-ownership documentation depending on the endpoint.
## References
- Azure/terraform-azurerm-avm-res-web-site#377
- Azure/terraform-azurerm-avm-res-web-site#378
- Azure/terraform-azurerm-avm-res-web-site#382
- Azure/terraform-azurerm-avm-res-web-site#384
- AzAPI implementation: `internal/services/azapi_update_resource.go` calls `MergeObjectWithOption(existing, requestBody, ...)`.
_Drafted by Copilot with GPT-5.6 Sol._
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with internal/services/azapi_update_resource.go, especially its MergeObjectWithOption(existing, requestBody, ...) call, then read references #377, #378, #382, and #384. Done means documenting AVM-wide ownership and removal rules, identifying affected azapi_update_resource modules, and specifying where live configured-to-removed transition coverage is required.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure
- Domain
- cloud, documentation, infrastructure
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100