sr2c.terraform.terraform_module role – Deploy resources using a Terraform module

Note

This role is part of the sr2c.terraform collection (version 1.0.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it use: ansible-galaxy collection install sr2c.terraform.

To use it in a playbook, specify: sr2c.terraform.terraform_module.

Entry point main – Deploy resources using a Terraform module

Synopsis

  • Writes a root module that calls terraform_module_source as module.this, generates a plan, and once the plan is approved (interactive mode) applies that saved plan. The module’s outputs are stored in the host variable named by terraform_module_outputs_var.

  • Works with Terraform 1.5.7 or later and with OpenTofu. To use tofu, set terraform_module_binary_path.

  • Runs on any host with a POSIX shell that Terraform or OpenTofu supports, such as Linux, macOS, FreeBSD, OpenBSD and Solaris.

  • The role works in a temporary directory that is removed after the run, so it fails unless terraform_module_backend_config or terraform_module_workdir is set. A local backend with a relative path still loses the state.

  • In check mode the role plans but never applies or destroys.

  • Sets the facts terraform_module_plan (the plan as displayed), terraform_module_plan_file (removed with the temporary directory) and terraform_module_plan_has_changes.

  • Requires the jmespath Python library on the host running the role.

Parameters

Parameter

Comments

terraform_module_action

string

apply plans and applies.

destroy plans a destroy and applies it.

plan-apply and plan-destroy only plan.

Choices:

  • "apply" ← (default)

  • "destroy"

  • "plan-apply"

  • "plan-destroy"

terraform_module_backend_config

dictionary

The backend, as a dict with the backend type (for example s3) as its only key and that backend’s arguments as its value.

The terraform_s3_backend_config fact from sr2c.terraform.terraform_s3_backend can be used as the s3 value once a key is added.

Default: {"local": {}}

terraform_module_binary_path

path

The terraform or tofu binary. Defaults to terraform on the controller’s PATH.

terraform_module_end_play_on_approval_rejection

boolean

End the play for the host when a plan is rejected. When false, the role carries on without applying.

Choices:

  • false

  • true ← (default)

terraform_module_extra

dictionary

Extra top-level blocks for the root module, such as provider or resource.

The merge is not recursive, so a terraform, module or output key replaces the role’s own block.

Default: {}

terraform_module_force_init

boolean

Run terraform init even when terraform_module_plan_file_input is set.

Choices:

  • false ← (default)

  • true

terraform_module_force_unlock

boolean

If the state is locked when planning, release the lock and plan again.

This releases any lock, including one held by a run still in progress, so only use it for a stale lock.

Choices:

  • false ← (default)

  • true

terraform_module_init_argv_extra

list / elements=string

Extra arguments for terraform init.

Default: []

terraform_module_inputs

dictionary

The input variables for the module.

Strings are Terraform templates, so ${...} and %{...} in a value are evaluated.

Default: {}

terraform_module_interactive

boolean

Wait for an operator to type yes before applying a plan with changes.

The prompt is shown once per batch of hosts, so one yes approves every host in the batch.

With no terminal, as in AWX or CI, the role fails before applying, so set false for unattended runs.

Choices:

  • false

  • true ← (default)

terraform_module_no_log

boolean

Hide task results that can contain sensitive values (the JSON plan, outputs, apply and destroy results, and the generated configuration), even with -v or --diff. Set to false to debug.

Choices:

  • false

  • true ← (default)

terraform_module_outputs_var

string

The host variable to store the module’s outputs in, as a dict keyed by output name. It is {} when there are none.

Default: "terraform_module_outputs"

terraform_module_parallelism

integer

Passed to terraform plan as -parallelism.

Default: 10

terraform_module_plan_argv_extra

list / elements=string

Extra arguments for terraform plan.

Default: []

terraform_module_plan_file_input

path

A saved plan file to apply instead of planning. A relative path is resolved from the working directory.

terraform init is skipped unless terraform_module_force_init is true, so use the terraform_module_workdir the plan was made in.

terraform_module_preview_plan

boolean

Display the plan before it is applied.

Choices:

  • false

  • true ← (default)

terraform_module_required_providers_config

dictionary

The required_providers block of the root module.

Default: {}

terraform_module_source

string / required

The module to deploy, as any module source, for example sr2c/tor-bridge/aws.

Local paths must be absolute, as a relative path is resolved from the working directory.

terraform_module_version

string

The version constraint, for sources that support one, such as the Terraform registry.

terraform_module_workdir

path

An existing, empty directory to work in instead of a temporary one. It is kept after the run.

If terraform_module_backend_config changes, run once with terraform_module_init_argv_extra set to ["-reconfigure"].

Use a separate directory for each host.

terraform_module_workdir_clean_enabled

boolean

Remove the temporary working directory after the run. Has no effect when terraform_module_workdir is set.

Choices:

  • false

  • true ← (default)

Authors