Skip to content

Cloud, backend/remote: forward -minimal-refresh to HCPT and TFE - #39310

Merged
austinvalle merged 10 commits into
mainfrom
shweta/minimal-refresh-remote
Oct 2, 2026
Merged

austinvalle merged 10 commits into
mainfrom
shweta/minimal-refresh-remote

Conversation

@shwetamurali

@shwetamurali shwetamurali commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Forwards the -minimal-refresh planning option to HCP Terraform / Terraform Enterprise through the cloud block and the legacy remote backend.

Core already supports -minimal-refresh locally, but remote operations reject it with a temporary "Minimal refresh mode is currently not supported" error, because HCP Terraform and go-tfe didn't support it yet. HCP Terraform's Runs API now accepts a minimal-refresh run attribute, and go-tfe v1.112.0 exposes it (hashicorp/go-tfe#1502).

Changes Made

  • go-tfe: bumps github.com/hashicorp/go-tfe from v1.110.0 to v1.112.0
  • Forwarding (cloud and remote): sets MinimalRefresh = true on the run create options only when -minimal-refresh is requested. It stays nil otherwise, so ordinary runs never send the attribute and older servers see no change.
  • Server capability check: replaces the temporary rejection with a check on the server's TFP-API-Version, following the existing -target / -replace / -refresh-only pattern in the remote backend. If the version is below MinimalRefreshMinAPIVersion (2.7) or can't be parsed, Terraform returns an error before any run is created:

    The host does not support the -minimal-refresh option. If you use Terraform Enterprise, upgrade to a version that supports minimal refresh. Otherwise, run without -minimal-refresh.

Older servers silently drop unknown run attributes, so without this check a run on an older server would quietly do a full refresh.

Tests

Manual testing

Terraform built from this branch against a local HCP Terraform stack

API 2.6: plan -minimal-refresh and apply -minimal-refresh are rejected by Core before any run is created:

Error: Minimal refresh is not supported

The host <host> does not support the -minimal-refresh option. If you use
Terraform Enterprise, upgrade to a version that supports minimal refresh.
Otherwise, run without -minimal-refresh.

-minimal-refresh with -refresh=false or -refresh-only is still rejected by argument parsing and a plain plan works as before.

API 2.7:

Command minimal-refresh plan-only Status
plan -minimal-refresh true true planned_and_finished
apply -minimal-refresh true false applied
plan false true planned_and_finished

All runs had refresh: true, refresh-only: false. Atlas validation errors still reach the user.

Specs
New tests in internal/cloud/backend_minimal_refresh_test.go and internal/backend/remote/backend_minimal_refresh_test.go, using the mock client:

  • plan/apply with -minimal-refresh → MinimalRefresh == true; without it → nil (not false)
  • plan stays speculative, apply is applicable
  • API version below the minimum, or unparseable → error, no run created
  • API version at or above the minimum → forwarded

The mock runs client now records MinimalRefresh from the create options.

Manual testing against a local HCP Terraform stack: see below / to be added.

Follow-ups (not in this PR)

  • Add the minimum Terraform Enterprise version to the docs once the TFE release is known.

Target Release

1.17.x

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.

v1.112.0 adds the minimal-refresh run attribute (MinimalRefresh on
RunCreateOptions and Run).
Send the minimal-refresh run attribute only when -minimal-refresh is
requested, so ordinary runs never include it. Replace the temporary
"not supported" diagnostics with a check that the server's
TFP-API-Version is at least MinimalRefreshMinAPIVersion, returning an
error before any run is created otherwise.

MinimalRefreshMinAPIVersion is provisional and must be updated to the
API version that ships minimal refresh support.
Send the minimal-refresh run attribute only when -minimal-refresh is
requested, and replace the temporary "not supported" diagnostics with
the same API version check used by the cloud integration.
@shwetamurali shwetamurali changed the title Shweta/minimal refresh remote Cloud, backend/remote: forward -minimal-refresh to HCPT and TFE Sep 29, 2026
@shwetamurali shwetamurali added the 1.17-backport If you add this label to a PR before merging, backport-assistant will open a new PR once merged label Sep 29, 2026
@shwetamurali shwetamurali changed the title Cloud, backend/remote: forward -minimal-refresh to HCPT and TFE Cloud, backend/remote: forward -minimal-refresh to HCPT and TFE Sep 29, 2026

@austinvalle austinvalle left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know this is still in draft but I took a look early 👀, hopefully not too much noise if any of the stuff I commented on was in-progress

Comment thread .changes/v1.17/ENHANCEMENTS-20260929-180158.yaml Outdated
Comment thread internal/backend/remote/backend_minimal_refresh_test.go Outdated
Comment thread internal/backend/remote/backend_minimal_refresh_test.go Outdated
Comment thread internal/backend/remote/backend_minimal_refresh_test.go Outdated
Comment thread internal/backend/remote/backend_minimal_refresh_test.go Outdated
@shwetamurali shwetamurali added the no-changelog-needed Add this to your PR if the change does not require a changelog entry label Sep 30, 2026
@shwetamurali
shwetamurali marked this pull request as ready for review October 1, 2026 14:04
@shwetamurali
shwetamurali requested review from a team as code owners October 1, 2026 14:04

@austinvalle austinvalle left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR looks good! I think we can wait for the version to be fully decided before we merge this PR so I'll hold off on approval until that's updated 👍🏻

@austinvalle
austinvalle merged commit 8259ba6 into main Oct 2, 2026
9 checks passed
@austinvalle
austinvalle deleted the shweta/minimal-refresh-remote branch October 2, 2026 12:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

1.17-backport If you add this label to a PR before merging, backport-assistant will open a new PR once merged no-changelog-needed Add this to your PR if the change does not require a changelog entry

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants