Azure / Azure/Azure-Verified-Modules

Define AVM ownership and removal semantics for azapi_update_resource

Open
#2,901 1 comment 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.