Update remote.Client interface's methods to return diagnostics instead of primitive errors

[SarahFrench]

This PR is stacked on #37496

This PR updates the interfaces that are used for reading and saving state to/from remote locations. The changed code is used in all backends in the remote-state folder.

By making these interfaces return diagnostics we allow backends to return warnings to users, instead of just errors.

Target Release

N/A

Rollback Plan

• If a change needs to be reverted, we will roll out an update to the code within 7 days.

Changes to Security Controls

Are there any changes to security controls (access controls, encryption, logging) in this pull request? If so, explain.

CHANGELOG entry

• This change is user-facing and I added a changelog entry.
• This change is not user-facing.

[SarahFrench]

gcs backend tests:

% go test github.com/hashicorp/terraform/internal/backend/remote-state/gcs       
ok      github.com/hashicorp/terraform/internal/backend/remote-state/gcs        122.093s

kubernetes tests:

% go test github.com/hashicorp/terraform/internal/backend/remote-state/kubernetes
ok      github.com/hashicorp/terraform/internal/backend/remote-state/kubernetes 54.227s

pg tests:

% go test github.com/hashicorp/terraform/internal/backend/remote-state/pg        
ok      github.com/hashicorp/terraform/internal/backend/remote-state/pg 1.603s

[SarahFrench]

I learned what's required to run the azure tests and found that they passed, except for some tests that were skipped due to requiring more specific permissions or due to needing to run in specific environments.

Test results are below - I think that this is sufficient as the skip and failures are not due to this PR's changes.

=== RUN TestBackend_impl
--- PASS: TestBackend_impl (0.00s)
=== RUN TestBackendConfig
=== PAUSE TestBackendConfig
=== RUN TestAccBackendAccessKeyBasic
=== PAUSE TestAccBackendAccessKeyBasic
=== RUN TestAccBackendSASTokenBasic
=== PAUSE TestAccBackendSASTokenBasic
=== RUN TestAccBackendGithubOIDCBasic
=== PAUSE TestAccBackendGithubOIDCBasic
=== RUN TestAccBackendADOPipelinesOIDCBasic
=== PAUSE TestAccBackendADOPipelinesOIDCBasic
=== RUN TestAccBackendAzureADAuthBasic
=== PAUSE TestAccBackendAzureADAuthBasic
=== RUN TestAccBackendAzureADAuthBasicWithBlobEndpointLookup
=== PAUSE TestAccBackendAzureADAuthBasicWithBlobEndpointLookup
=== RUN TestAccBackendManagedServiceIdentityBasic
=== PAUSE TestAccBackendManagedServiceIdentityBasic
=== RUN TestAccBackendServicePrincipalClientCertificateBasic
=== PAUSE TestAccBackendServicePrincipalClientCertificateBasic
=== RUN TestAccBackendServicePrincipalClientSecretBasic
=== PAUSE TestAccBackendServicePrincipalClientSecretBasic
=== RUN TestAccBackendAccessKeyLocked
=== PAUSE TestAccBackendAccessKeyLocked
=== RUN TestAccBackendServicePrincipalLocked
=== PAUSE TestAccBackendServicePrincipalLocked
=== RUN TestRemoteClientAccessKeyBasic
=== PAUSE TestRemoteClientAccessKeyBasic
=== RUN TestRemoteClientManagedServiceIdentityBasic
=== PAUSE TestRemoteClientManagedServiceIdentityBasic
=== RUN TestRemoteClientSasTokenBasic
=== PAUSE TestRemoteClientSasTokenBasic
=== RUN TestRemoteClientServicePrincipalBasic
=== PAUSE TestRemoteClientServicePrincipalBasic
=== RUN TestRemoteClientAccessKeyLocks
=== PAUSE TestRemoteClientAccessKeyLocks
=== RUN TestRemoteClientServicePrincipalLocks
=== PAUSE TestRemoteClientServicePrincipalLocks
=== RUN TestPutMaintainsMetaData
=== PAUSE TestPutMaintainsMetaData
=== CONT TestBackendConfig
=== CONT TestAccBackendAccessKeyLocked
=== CONT TestAccBackendAzureADAuthBasic
=== CONT TestAccBackendGithubOIDCBasic
=== CONT TestAccBackendADOPipelinesOIDCBasic
=== NAME TestAccBackendGithubOIDCBasic
helpers_test.go:55: Skipping test since not running in GitHub Actions
=== NAME TestAccBackendADOPipelinesOIDCBasic
helpers_test.go:64: Skipping test since not running in ADO Pipelines
--- SKIP: TestAccBackendGithubOIDCBasic (0.00s)
--- SKIP: TestAccBackendADOPipelinesOIDCBasic (0.00s)
=== CONT TestRemoteClientAccessKeyLocks
=== CONT TestAccBackendManagedServiceIdentityBasic
helpers_test.go:46: Skipping test since not running in Azure
--- SKIP: TestAccBackendManagedServiceIdentityBasic (0.00s)
=== CONT TestRemoteClientSasTokenBasic
=== CONT TestAccBackendServicePrincipalClientSecretBasic
=== CONT TestRemoteClientServicePrincipalBasic
=== CONT TestRemoteClientServicePrincipalLocks
=== CONT TestRemoteClientManagedServiceIdentityBasic
helpers_test.go:46: Skipping test since not running in Azure
--- SKIP: TestRemoteClientManagedServiceIdentityBasic (0.00s)
=== CONT TestAccBackendSASTokenBasic
=== NAME TestBackendConfig
=== CONT TestPutMaintainsMetaData
--- PASS: TestBackendConfig (0.00s)
=== CONT TestAccBackendAccessKeyBasic
=== NAME TestAccBackendServicePrincipalClientSecretBasic
=== NAME TestRemoteClientServicePrincipalBasic
=== NAME TestAccBackendAccessKeyLocked
=== NAME TestAccBackendSASTokenBasic
=== NAME TestRemoteClientSasTokenBasic
=== NAME TestAccBackendAccessKeyBasic
=== NAME TestAccBackendAzureADAuthBasic
backend_test.go:225: error: executing request: unexpected status 403 (403 This request is not authorized to perform this operation using this permission.) with AuthorizationPermissionMismatch: This request is not authorized to perform this operation using this permission.
RequestId:23f39206-101e-0048-5261-176b9f000000
Time:2025-08-27T14:48:02.5497323Z
=== NAME TestRemoteClientAccessKeyLocks
=== NAME TestAccBackendAccessKeyLocked
=== NAME TestRemoteClientServicePrincipalLocks
=== NAME TestAccBackendAccessKeyLocked
=== CONT TestRemoteClientAccessKeyBasic
--- FAIL: TestAccBackendAzureADAuthBasic (91.02s)
=== NAME TestRemoteClientAccessKeyBasic
--- PASS: TestRemoteClientAccessKeyBasic (100.00s)
=== CONT TestAccBackendServicePrincipalLocked
--- PASS: TestAccBackendServicePrincipalLocked (144.14s)
=== CONT TestAccBackendAzureADAuthBasicWithBlobEndpointLookup
backend_test.go:258: error: executing request: unexpected status 403 (403 This request is not authorized to perform this operation using this permission.) with AuthorizationPermissionMismatch: This request is not authorized to perform this operation using this permission.
RequestId:c72c02aa-601e-0063-7a64-17c10c000000
Time:2025-08-27T15:10:37.4580434Z
--- FAIL: TestAccBackendAzureADAuthBasicWithBlobEndpointLookup (0.00s)
=== CONT TestAccBackendServicePrincipalClientCertificateBasic
backend_test.go:299: Skipping since ARM_CLIENT_CERTIFICATE_PATH is not specified!
--- SKIP: TestAccBackendServicePrincipalClientCertificateBasic (0.00s)
--- PASS: TestPutMaintainsMetaData (91.79s)
--- PASS: TestRemoteClientSasTokenBasic (96.30s)
--- PASS: TestRemoteClientServicePrincipalBasic (96.81s)
--- PASS: TestRemoteClientAccessKeyLocks (108.66s)
--- PASS: TestAccBackendAccessKeyBasic (113.55s)
--- PASS: TestAccBackendSASTokenBasic (113.66s)
--- PASS: TestAccBackendServicePrincipalClientSecretBasic (115.17s)
--- PASS: TestRemoteClientServicePrincipalLocks (115.33s)
--- PASS: TestAccBackendAccessKeyLocked (133.10s)
FAIL

[SarahFrench]

I've run the tests for the s3 backend:

% go test github.com/hashicorp/terraform/internal/backend/remote-state/s3   
ok      github.com/hashicorp/terraform/internal/backend/remote-state/s3 13.888s

[SarahFrench]

Note for reviewers: I've run tests on the following backends:

• gcs, kubernetes, pg: Update remote.Client interface's methods to return diagnostics instead of primitive errors #37502 (comment)
• s3: Update remote.Client interface's methods to return diagnostics instead of primitive errors #37502 (comment)
• azure: Update remote.Client interface's methods to return diagnostics instead of primitive errors #37502 (comment)

[SarahFrench]

This is the place where the Put and Get methods are called by other Core code. All other calls to the affected methods in this PR are tests.

[SarahFrench]

This shows that any warnings returned are lost here, but we can update the calling code in future - I wanted to keep the scope of this PR minimal!

[github-actions]

I'm going to lock this pull request because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active contributions.
If you have found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.