Merge pull request #2 from stategraph/feat/dry-run-mode

feat: add dry-run mode to preview API calls and flyctl commands

Author: joshpollara

CLAUDE.md

@@ -63,3 +63,4 @@ Every resource implements `Resource`, `ResourceWithConfigure`, and `ResourceWith
 | `api_url`    | `FLY_API_URL`    | No       |
 | `org_slug`   | `FLY_ORG`        | No       |
 | `flyctl_path` | `FLYCTL_PATH`   | No       |
+| `dry_run`    | `FLY_DRY_RUN`   | No       |

README.md

@@ -155,9 +155,41 @@ terraform import fly_ip_address.v6 my-app/ip-id
 | `api_url` | `FLY_API_URL` | API base URL (default: `https://api.machines.dev/v1`) |
 | `org_slug` | `FLY_ORG` | Default organization |
 | `flyctl_path` | `FLYCTL_PATH` | Path to flyctl binary (default: search PATH) |
+| `dry_run` | `FLY_DRY_RUN` | Preview commands without executing them (see below) |
 
 Generate a token: `fly tokens create org`
 
+## Dry-run mode
+
+Dry-run mode shows you exactly what API calls and flyctl commands would be executed during an apply, without actually making any changes to your infrastructure.
+
+Enable it via the provider config or environment variable:
+
+```hcl
+provider "fly" {
+  dry_run = true
+}
+```
+
+```bash
+FLY_DRY_RUN=1 terraform apply
+```
+
+Terraform warnings will show each intercepted mutation:
+
+```
+Warning: Dry Run [1]
+  POST https://api.machines.dev/v1/apps/my-app/machines/abc123/lease body={"ttl":60}
+
+Warning: Dry Run [2]
+  POST https://api.machines.dev/v1/apps/my-app/machines/abc123 body={...}
+
+Warning: Dry Run [3]
+  /usr/local/bin/flyctl ips allocate-v6 -a my-app
+```
+
+Read operations (state refresh, imports, data sources) work normally so Terraform can build an accurate plan. Only mutating operations (create, update, delete) are intercepted.
+
 ## Development
 
 ### Requirements

internal/models/provider_data.go

@@ -1,6 +1,9 @@
 package models
 
 import (
+	"fmt"
+
+	"github.com/hashicorp/terraform-plugin-framework/diag"
 	"github.com/stategraph/terraform-provider-fly/pkg/apiclient"
 	"github.com/stategraph/terraform-provider-fly/pkg/flyctl"
 )
@@ -9,4 +12,20 @@ import (
 type ProviderData struct {
 	APIClient *apiclient.Client
 	Flyctl    *flyctl.Executor
+	DryRun    bool
+}
+
+// FlushDryRunWarnings drains accumulated dry-run messages from the API client
+// and flyctl executor, adding each as a Terraform warning diagnostic.
+func FlushDryRunWarnings(diags *diag.Diagnostics, client *apiclient.Client, flyctl *flyctl.Executor) {
+	if client != nil {
+		for i, msg := range client.FlushDryRunMessages() {
+			diags.AddWarning(fmt.Sprintf("Dry Run [%d]", i+1), msg)
+		}
+	}
+	if flyctl != nil {
+		for i, msg := range flyctl.FlushDryRunMessages() {
+			diags.AddWarning(fmt.Sprintf("Dry Run [%d]", i+1), msg)
+		}
+	}
 }

internal/provider/provider.go

@@ -27,6 +27,7 @@ type FlyProviderModel struct {
 	APIURL     types.String `tfsdk:"api_url"`
 	OrgSlug    types.String `tfsdk:"org_slug"`
 	FlyctlPath types.String `tfsdk:"flyctl_path"`
+	DryRun     types.Bool   `tfsdk:"dry_run"`
 }
 
 func New(version string) func() provider.Provider {
@@ -61,6 +62,10 @@ func (p *FlyProvider) Schema(_ context.Context, _ provider.SchemaRequest, resp *
 				Description: "Path to the flyctl binary. Can also be set via FLYCTL_PATH. If unset, searches PATH for flyctl or fly.",
 				Optional:    true,
 			},
+			"dry_run": schema.BoolAttribute{
+				Description: "When true, flyctl commands are logged but not executed. Useful for previewing what commands would run. Can also be set via FLY_DRY_RUN.",
+				Optional:    true,
+			},
 		},
 	}
 }
@@ -95,6 +100,7 @@ func (p *FlyProvider) Configure(ctx context.Context, req provider.ConfigureReque
 	}
 
 	client := apiclient.NewClient(token, p.version, opts...)
+	// DryRun is set below after config is resolved.
 
 	// Resolve flyctl binary path.
 	flyctlPath := config.FlyctlPath.ValueString()
@@ -113,14 +119,23 @@ func (p *FlyProvider) Configure(ctx context.Context, req provider.ConfigureReque
 		binaryPath = ""
 	}
 
+	dryRun := config.DryRun.ValueBool()
+	if !dryRun && os.Getenv("FLY_DRY_RUN") != "" {
+		dryRun = true
+	}
+
+	client.DryRun = dryRun
+
 	var executor *flyctl.Executor
 	if binaryPath != "" {
 		executor = flyctl.NewExecutor(binaryPath, token)
+		executor.DryRun = dryRun
 	}
 
 	pd := &models.ProviderData{
 		APIClient: client,
 		Flyctl:    executor,
+		DryRun:    dryRun,
 	}
 
 	resp.DataSourceData = pd

internal/resources/app_resource.go

@@ -98,6 +98,7 @@ func (r *appResource) Configure(_ context.Context, req resource.ConfigureRequest
 }
 
 func (r *appResource) Create(ctx context.Context, req resource.CreateRequest, resp *resource.CreateResponse) {
+	defer models.FlushDryRunWarnings(&resp.Diagnostics, r.client, nil)
 	var plan models.AppResourceModel
 	resp.Diagnostics.Append(req.Plan.Get(ctx, &plan)...)
 	if resp.Diagnostics.HasError() {
@@ -168,13 +169,15 @@ func (r *appResource) Read(ctx context.Context, req resource.ReadRequest, resp *
 }
 
 func (r *appResource) Update(_ context.Context, _ resource.UpdateRequest, resp *resource.UpdateResponse) {
+	defer models.FlushDryRunWarnings(&resp.Diagnostics, r.client, nil)
 	resp.Diagnostics.AddError(
 		"Update not supported",
 		"All attributes of fly_app require replacement. Update should never be called.",
 	)
 }
 
 func (r *appResource) Delete(ctx context.Context, req resource.DeleteRequest, resp *resource.DeleteResponse) {
+	defer models.FlushDryRunWarnings(&resp.Diagnostics, r.client, nil)
 	var state models.AppResourceModel
 	resp.Diagnostics.Append(req.State.Get(ctx, &state)...)
 	if resp.Diagnostics.HasError() {

internal/resources/certificate_resource.go

@@ -103,6 +103,7 @@ func (r *certificateResource) Configure(_ context.Context, req resource.Configur
 }
 
 func (r *certificateResource) Create(ctx context.Context, req resource.CreateRequest, resp *resource.CreateResponse) {
+	defer models.FlushDryRunWarnings(&resp.Diagnostics, r.client, nil)
 	var plan models.CertificateResourceModel
 	resp.Diagnostics.Append(req.Plan.Get(ctx, &plan)...)
 	if resp.Diagnostics.HasError() {
@@ -161,13 +162,15 @@ func (r *certificateResource) Read(ctx context.Context, req resource.ReadRequest
 }
 
 func (r *certificateResource) Update(_ context.Context, _ resource.UpdateRequest, resp *resource.UpdateResponse) {
+	defer models.FlushDryRunWarnings(&resp.Diagnostics, r.client, nil)
 	resp.Diagnostics.AddError(
 		"Update not supported",
 		"All attributes of fly_certificate require replacement. Update should never be called.",
 	)
 }
 
 func (r *certificateResource) Delete(ctx context.Context, req resource.DeleteRequest, resp *resource.DeleteResponse) {
+	defer models.FlushDryRunWarnings(&resp.Diagnostics, r.client, nil)
 	var state models.CertificateResourceModel
 	resp.Diagnostics.Append(req.State.Get(ctx, &state)...)
 	if resp.Diagnostics.HasError() {

internal/resources/egress_ip_resource.go

@@ -85,6 +85,7 @@ func (r *egressIPResource) Configure(_ context.Context, req resource.ConfigureRe
 }
 
 func (r *egressIPResource) Create(ctx context.Context, req resource.CreateRequest, resp *resource.CreateResponse) {
+	defer models.FlushDryRunWarnings(&resp.Diagnostics, nil, r.flyctl)
 	var plan models.EgressIPResourceModel
 	resp.Diagnostics.Append(req.Plan.Get(ctx, &plan)...)
 	if resp.Diagnostics.HasError() {
@@ -94,7 +95,7 @@ func (r *egressIPResource) Create(ctx context.Context, req resource.CreateReques
 	appName := plan.App.ValueString()
 
 	// Allocate command doesn't support --json, use Run then list.
-	_, err := r.flyctl.Run(ctx, "ips", "allocate-egress", "-a", appName, "--yes")
+	_, err := r.flyctl.RunMut(ctx, "ips", "allocate-egress", "-a", appName, "--yes")
 	if err != nil {
 		resp.Diagnostics.AddError("Error allocating egress IP", err.Error())
 		return
@@ -164,17 +165,19 @@ func (r *egressIPResource) Read(ctx context.Context, req resource.ReadRequest, r
 }
 
 func (r *egressIPResource) Update(_ context.Context, _ resource.UpdateRequest, resp *resource.UpdateResponse) {
+	defer models.FlushDryRunWarnings(&resp.Diagnostics, nil, r.flyctl)
 	resp.Diagnostics.AddError("Update not supported", "All attributes of fly_egress_ip require replacement.")
 }
 
 func (r *egressIPResource) Delete(ctx context.Context, req resource.DeleteRequest, resp *resource.DeleteResponse) {
+	defer models.FlushDryRunWarnings(&resp.Diagnostics, nil, r.flyctl)
 	var state models.EgressIPResourceModel
 	resp.Diagnostics.Append(req.State.Get(ctx, &state)...)
 	if resp.Diagnostics.HasError() {
 		return
 	}
 
-	_, err := r.flyctl.Run(ctx, "ips", "release-egress", state.Address.ValueString(), "-a", state.App.ValueString())
+	_, err := r.flyctl.RunMut(ctx, "ips", "release-egress", state.Address.ValueString(), "-a", state.App.ValueString())
 	if err != nil {
 		if flyctl.IsNotFound(err) {
 			return

internal/resources/extension_resource.go

@@ -130,6 +130,7 @@ func getStringAttrFromState(ctx context.Context, state tfsdk.State, attrName str
 }
 
 func (r *extensionResource) Create(ctx context.Context, req resource.CreateRequest, resp *resource.CreateResponse) {
+	defer models.FlushDryRunWarnings(&resp.Diagnostics, nil, r.flyctl)
 	name, diags := getStringAttrFromPlan(ctx, req.Plan, "name")
 	resp.Diagnostics.Append(diags...)
 	if resp.Diagnostics.HasError() {
@@ -157,7 +158,7 @@ func (r *extensionResource) Create(ctx context.Context, req resource.CreateReque
 	}
 
 	var result flyctlExtension
-	err := r.flyctl.RunJSON(ctx, &result, args...)
+	err := r.flyctl.RunJSONMut(ctx, &result, args...)
 	if err != nil {
 		resp.Diagnostics.AddError(fmt.Sprintf("Error creating %s extension", r.config.TypeName), err.Error())
 		return
@@ -188,17 +189,19 @@ func (r *extensionResource) Read(ctx context.Context, req resource.ReadRequest,
 }
 
 func (r *extensionResource) Update(_ context.Context, _ resource.UpdateRequest, resp *resource.UpdateResponse) {
+	defer models.FlushDryRunWarnings(&resp.Diagnostics, nil, r.flyctl)
 	resp.Diagnostics.AddError("Update not supported", fmt.Sprintf("All attributes of fly_ext_%s require replacement.", r.config.TypeName))
 }
 
 func (r *extensionResource) Delete(ctx context.Context, req resource.DeleteRequest, resp *resource.DeleteResponse) {
+	defer models.FlushDryRunWarnings(&resp.Diagnostics, nil, r.flyctl)
 	name, diags := getStringAttrFromState(ctx, req.State, "name")
 	resp.Diagnostics.Append(diags...)
 	if resp.Diagnostics.HasError() {
 		return
 	}
 
-	_, err := r.flyctl.Run(ctx, "ext", r.config.TypeName, "destroy", name, "--yes")
+	_, err := r.flyctl.RunMut(ctx, "ext", r.config.TypeName, "destroy", name, "--yes")
 	if err != nil {
 		if flyctl.IsNotFound(err) {
 			return

internal/resources/ip_address_resource.go

@@ -105,6 +105,7 @@ func (r *ipAddressResource) Configure(_ context.Context, req resource.ConfigureR
 }
 
 func (r *ipAddressResource) Create(ctx context.Context, req resource.CreateRequest, resp *resource.CreateResponse) {
+	defer models.FlushDryRunWarnings(&resp.Diagnostics, nil, r.flyctl)
 	var plan models.IPAddressResourceModel
 	resp.Diagnostics.Append(req.Plan.Get(ctx, &plan)...)
 	if resp.Diagnostics.HasError() {
@@ -141,12 +142,22 @@ func (r *ipAddressResource) Create(ctx context.Context, req resource.CreateReque
 	}
 
 	// Allocate commands don't support --json, so use Run then list to get details.
-	_, err := r.flyctl.Run(ctx, args...)
+	_, err := r.flyctl.RunMut(ctx, args...)
 	if err != nil {
 		resp.Diagnostics.AddError("Error allocating IP address", err.Error())
 		return
 	}
 
+	// In dry-run mode, no IP was actually allocated. Set placeholder state.
+	if r.flyctl.DryRun {
+		plan.ID = types.StringValue("dry-run")
+		plan.Address = types.StringValue("")
+		plan.Region = types.StringValue("")
+		plan.CreatedAt = types.StringValue("")
+		resp.Diagnostics.Append(resp.State.Set(ctx, &plan)...)
+		return
+	}
+
 	// List IPs to find the newly allocated one.
 	ips, err := r.listIPs(ctx, appName)
 	if err != nil {
@@ -216,20 +227,22 @@ func (r *ipAddressResource) Read(ctx context.Context, req resource.ReadRequest,
 }
 
 func (r *ipAddressResource) Update(_ context.Context, _ resource.UpdateRequest, resp *resource.UpdateResponse) {
+	defer models.FlushDryRunWarnings(&resp.Diagnostics, nil, r.flyctl)
 	resp.Diagnostics.AddError(
 		"Update not supported",
 		"All attributes of fly_ip_address require replacement. Update should never be called.",
 	)
 }
 
 func (r *ipAddressResource) Delete(ctx context.Context, req resource.DeleteRequest, resp *resource.DeleteResponse) {
+	defer models.FlushDryRunWarnings(&resp.Diagnostics, nil, r.flyctl)
 	var state models.IPAddressResourceModel
 	resp.Diagnostics.Append(req.State.Get(ctx, &state)...)
 	if resp.Diagnostics.HasError() {
 		return
 	}
 
-	_, err := r.flyctl.Run(ctx, "ips", "release", state.Address.ValueString(), "-a", state.App.ValueString())
+	_, err := r.flyctl.RunMut(ctx, "ips", "release", state.Address.ValueString(), "-a", state.App.ValueString())
 	if err != nil {
 		if flyctl.IsNotFound(err) {
 			return

internal/resources/litefs_cluster_resource.go

@@ -81,6 +81,7 @@ func (r *liteFSClusterResource) Configure(_ context.Context, req resource.Config
 }
 
 func (r *liteFSClusterResource) Create(ctx context.Context, req resource.CreateRequest, resp *resource.CreateResponse) {
+	defer models.FlushDryRunWarnings(&resp.Diagnostics, nil, r.flyctl)
 	var plan models.LiteFSClusterResourceModel
 	resp.Diagnostics.Append(req.Plan.Get(ctx, &plan)...)
 	if resp.Diagnostics.HasError() {
@@ -94,7 +95,7 @@ func (r *liteFSClusterResource) Create(ctx context.Context, req resource.CreateR
 	}
 
 	var result flyctlLiteFSCluster
-	err := r.flyctl.RunJSON(ctx, &result, args...)
+	err := r.flyctl.RunJSONMut(ctx, &result, args...)
 	if err != nil {
 		resp.Diagnostics.AddError("Error creating LiteFS cluster", err.Error())
 		return
@@ -135,17 +136,19 @@ func (r *liteFSClusterResource) Read(ctx context.Context, req resource.ReadReque
 }
 
 func (r *liteFSClusterResource) Update(_ context.Context, _ resource.UpdateRequest, resp *resource.UpdateResponse) {
+	defer models.FlushDryRunWarnings(&resp.Diagnostics, nil, r.flyctl)
 	resp.Diagnostics.AddError("Update not supported", "All attributes of fly_litefs_cluster require replacement.")
 }
 
 func (r *liteFSClusterResource) Delete(ctx context.Context, req resource.DeleteRequest, resp *resource.DeleteResponse) {
+	defer models.FlushDryRunWarnings(&resp.Diagnostics, nil, r.flyctl)
 	var state models.LiteFSClusterResourceModel
 	resp.Diagnostics.Append(req.State.Get(ctx, &state)...)
 	if resp.Diagnostics.HasError() {
 		return
 	}
 
-	_, err := r.flyctl.Run(ctx, "litefs-cloud", "clusters", "destroy", state.Name.ValueString(), "--yes")
+	_, err := r.flyctl.RunMut(ctx, "litefs-cloud", "clusters", "destroy", state.Name.ValueString(), "--yes")
 	if err != nil {
 		if flyctl.IsNotFound(err) {
 			return