Use '-refresh' cli arg for plan creation and add as module arg

Sometimes we want our task to create a plan without the usual implied
state-refresh.  The default behavior of Terraform (either no-arg, or
'-refresh=true') is to always refresh state sources when the plan is
created.  When the user knows better, they can override, as they can
already on cli.

changelogs/fragments/20250121-add-refresh-arg.yml

@@ -0,0 +1,5 @@
+---
+minor_changes:
+  - Use "refresh" arg on plan command line (i.e. "terraform plan
+    -refresh=<arg>", defaults true), and allow user override in module args
+    (https://github.com/ansible-collections/cloud.terraform/pull/168)

plugins/module_utils/terraform_commands.py

@@ -107,6 +107,7 @@ def plan(
         target_plan_file_path: str,
         targets: List[str],
         destroy: bool,
+        refresh: bool,
         state_args: List[str],
         variables_args: List[str],
     ) -> Tuple[bool, bool, str, str]:
@@ -123,6 +124,7 @@ def plan(
             command.extend(["-target", t])
         if destroy:
             command.append("-destroy")
+        command.append(f"-refresh={refresh}")
         command.extend(state_args)
         command.extend(variables_args)
 

plugins/modules/terraform.py

@@ -129,6 +129,15 @@
         that accepts locks (such as S3+DynamoDB).
     type: int
     version_added: 1.0.0
+  refresh:
+    description:
+      - Boolean argument for the C(-refresh=) option, to freshen terraform
+        resource/data state during Plan generation.  State refresh normally
+        happens by default, but can be countermanded by giving a C(false)
+        value here.
+    type: bool
+    default: true
+    version_added: 1.0.0
   force_init:
     description:
       - To avoid duplicating infra, if a state file can't be found this will
@@ -445,6 +454,7 @@ def main() -> None:
             lock=dict(type="bool", default=True),
             lock_timeout=dict(type="int"),
             force_init=dict(type="bool", default=False),
+            refresh=dict(type="bool", default=True),
             backend_config=dict(type="dict"),
             backend_config_files=dict(type="list", elements="path"),
             init_reconfigure=dict(type="bool", default=False),
@@ -570,6 +580,7 @@ def main() -> None:
             plan_result_changed, plan_result_any_destroyed, plan_stdout, plan_stderr = terraform.plan(
                 target_plan_file_path=plan_file_to_apply,
                 targets=module.params.get("targets"),
+                refresh=module.params.get("refresh", True),
                 destroy=state == "absent",
                 state_args=get_state_args(state_file),
                 variables_args=variables_args,