Skip to main content
Terraform Utility Modules 0.10.0Last updated in version 0.9.6

Run PEX as Resource

View SourceRelease Notes

This module runs the provided PEX binary in a portable manner that works with multiple platforms and python versions, in the context of a local-exec provisioner in Terraform.

This module uses prepare-pex-environment under the hood. See What is PEX? for more details on what is a PEX file and how to construct one for use with this module.

Data Source vs Resource​

Terraform provides two escape hatches where a first-class Terraform provider is not more appropriate. The escape hatches allow you to call out to arbitrary binaries available on the operator machine. These are:

This module uses the Provisioner approach (you can see the run-pex-as-data-source module for running it as a data source). Which approach to use depends on your needs:

  • Data sources are calculated every time a terraform state needs to be refreshed. This includes all plan and apply calls, even if the data source isn't explicitly changed.
  • Data sources are useful if the logic can be used to determine if a resource needs to be changed.
  • Data sources can output values that can be used in other parts of the Terraform code. You cannot do this with the provisioner approach.
  • There are limitations with Data Sources and dependencies. See this terraform issue comment for example.
  • Provisioners with a null_resource implements the standard resource life cycle (create, destroy, etc).
  • Provisioners with a null_resource have explicit controls on when to trigger.

Sample Usage​

main.tf

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S RUN-PEX-AS-RESOURCE MODULE
# ------------------------------------------------------------------------------------------------------

module "run_pex_as_resource" {

  source = "git::git@github.com:gruntwork-io/terraform-aws-utilities.git//modules/run-pex-as-resource?ref=v0.10.0"

  # ----------------------------------------------------------------------------------------------------
  # REQUIRED VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # Parts of the path (folders and file names) to the python package directory
  # housing the pex file.
  pex_module_path_parts = <list(string)>

  # Parts of the path (folders and files names) to the PEX executable for python
  # as a list of strings.
  python_pex_path_parts = <list(string)>

  # Main function of the script, encoded as SCRIPT_MODULE:FUNCTION. So for
  # example, if the main function of the script is in a file named
  # `entrypoint.py` which houses the function `main`, then this should be
  # `entrypoint:main`.
  script_main_function = <string>

  # ----------------------------------------------------------------------------------------------------
  # OPTIONAL VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # The arguments to pass to the command as a string
  command_args = ""

  # If you set this variable to false, this module will not run the PEX script.
  # This is used as a workaround because Terraform does not allow you to use the
  # 'count' parameter on modules. By using this parameter, you can optionally
  # enable the null_resource within this module.
  enabled = true

  # Additional environment variables to set for the command.
  env = {}

  # If you set this variable to true, this module will pass in the json encoded
  # triggers that were used when the resource was created. If the script expects
  # option args, use var.previous_trigger_option to set which option to pass the
  # triggers json as.
  pass_in_previous_triggers = false

  # Pass in the json encoded trigger with this string as the option to passing
  # into the command. E.g, setting this to `--triggers` will pass in the option
  # `--triggers TRIGGERS_JSON`.
  previous_trigger_option = ""

  # A map of arbitrary strings that, when changed, will force the null resource
  # to be replaced, re-running any associated provisioners.
  triggers = null

}


Reference​

Required​

pex_module_path_partslist(string)required

Parts of the path (folders and file names) to the python package directory housing the pex file.

python_pex_path_partslist(string)required

Parts of the path (folders and files names) to the PEX executable for python as a list of strings.

script_main_functionstringrequired

Main function of the script, encoded as SCRIPT_MODULE:FUNCTION. So for example, if the main function of the script is in a file named entrypoint.py which houses the function main, then this should be entrypoint:main.

Optional​

command_argsstringoptional

The arguments to pass to the command as a string

""
Details

   We don't use null here because this is interpolated into the python script.

enabledbooloptional

If you set this variable to false, this module will not run the PEX script. This is used as a workaround because Terraform does not allow you to use the 'count' parameter on modules. By using this parameter, you can optionally enable the null_resource within this module.

true
envmap(string)optional

Additional environment variables to set for the command.

{}

If you set this variable to true, this module will pass in the json encoded triggers that were used when the resource was created. If the script expects option args, use previous_trigger_option to set which option to pass the triggers json as.

false

Pass in the json encoded trigger with this string as the option to passing into the command. E.g, setting this to --triggers will pass in the option --triggers TRIGGERS_JSON.

""
triggersmap(string)optional

A map of arbitrary strings that, when changed, will force the null resource to be replaced, re-running any associated provisioners.

null