feat: add wait_for_desired_state to retry block for JMESPath-based state polling

[Copilot]

• Add wait_for_desired_state attribute to retry schema (internal/retry/schema.go)
• Add WaitForDesiredState field to RetryValue model with all boilerplate (internal/retry/retryable_errors.go)
• Add JMESPath string validator (internal/services/myvalidator/)
• Add NewRetryOptionsForWaitForDesiredState function (internal/clients/options.go)
• Wire up the new retry options in azapi_resource.go GET after PUT
• Wire up the new retry options in azapi_data_plane_resource.go GET after PUT
• Add unit tests for the new retry option (internal/clients/options_test.go)
• Update existing retry tests to include new field
• Add JMESPath validator unit tests
• Address code review feedback
• Run security checks (CodeQL: 0 alerts)
• Fix gofmt formatting and regenerate docs

Original prompt

---

This section details on the original issue you should resolve

<issue_title>feat: consider adding wait for desired state after azapi_resource create</issue_title>
<issue_description>Hi @ms-henglu

In the AzureRM provider, certain resources have a custom poller for the GET after PUT read. This allows the certain resources to wait until they are in a particular state before proceeding.

We need this because the API will sometimes return complete, but the resource has not finished provisioning.

Example resource: Microsoft.AAD/domainServices@2025-06-01

We should wait for the following:

"properties": {
    "replicaSets": [
        {
            // ...
            "serviceStatus": "Running"
            // ...
        }
    ]
}

Proposal

Implement a user-configurable custom wait_for_desired_state attribute that uses JMESPath expressions which must evaluate to true. Else the GET is retried.

E.g.

resource "azapi_resource" "example" {
  # other stuff ...
  wait_for_desired_state = [
    "properties.replicaSets[?serviceStatus != 'Running'] | length(@) == `0`" # must evaluate to true
    "properties.something == `ok`" # simpler example
  ]
}

We then implement a custom ShouldRetry func here:

terraform-provider-azapi/internal/services/azapi_resource.go

Lines 906 to 909 in 6438c33

	RetryOptions: clients.CombineRetryOptions(
	clients.NewRetryOptionsForReadAfterCreate(),
	clients.NewRetryOptions(plan.Retry),
	),

We could add:

clients.NewRetryFromWaitForDesiredState(plan.WaitForDesiredState)

We already have the JMESpath functions we need in the utils package.

</issue_description>

Comments on the Issue (you are @copilot in this section)

@ms-henglu Hi @matt-FFFFFF ,

Thank you for taking time to report this issue.

This is a great idea, and the implementation looks good to me.

How about putting it inside the retry block?

@matt-FFFFFF @ms-henglu I agree that retry is good place for this. Would you accept a PR? @ms-henglu Hi @matt-FFFFFF , absolutely, I’d appreciate the help! Please feel free to open a PR.

• Fixes feat: consider adding wait for desired state after azapi_resource create #1031

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[matt-FFFFFF]

@copilot fix CI errors

[Copilot]

@copilot fix CI errors

Fixed in 584c342. Two issues:

1. internal/retry/retryable_errors.go had misaligned struct fields — fixed with gofmt
2. Docs needed regeneration to include the new wait_for_desired_state attribute in the retry schema docs — added the line to all 8 affected doc files

The gosec failures are pre-existing (in tools/generator-data-plane-doc/main.go and internal/clients/account.go) and unrelated to this PR.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• checkpoint-api.hashicorp.com
  • Triggering command: /tmp/go-build3872524963/b001/exe/tfplugindocs /tmp/go-build3872524963/b001/exe/tfplugindocs -complete -buildid ur1qJEC7WAVf2SEHyDJL/ur1qJEC7WAVf2SEHyDJL -goversion go1.24.13 -c=4 -nolocalimports -importcfg /tmp/go-build3872524963/b234/importcfg -pack /opt/hostedtoolcache/go/1.24.13/x64/src/vendor/golang.org/x/net/http/httpproxy/proxy.go (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)