Terraform

Description

This plugin enables you to run Terraform against providers in a Vela pipeline.

Source Code: https://github.com/go-vela/vela-terraform

Registry: https://hub.docker.com/r/target/vela-terraform

Usage

NOTE:
Users should refrain from using latest as the tag for the Docker image.
It is recommended to use a semantically versioned tag instead.

Sample of adding installing terraform version:

steps:
  - name: apply
    image: target/vela-terraform:latest
    pull: always
    parameters:
      action: apply
      auto_approve: true # Required for versions of Terraform 0.12.x
      version: 0.11.7

Sample of adding init options to Terraform configuration:

steps:
  - name: apply
    image: target/vela-terraform:latest
    pull: always
    parameters:
      action: apply
      auto_approve: true # Required for versions of Terraform 0.12.x
      init_options:
        get_plugins: true

Sample of applying Terraform configuration:

steps:
  - name: apply
    image: target/vela-terraform:latest
    pull: always
    parameters:
      action: apply
      auto_approve: true # Required for versions of Terraform 0.12.x

Sample of destroying Terraform configuration:

steps:
  - name: destroy
    image: target/vela-terraform:latest
    pull: always
    parameters:
      action: destroy
      auto_approve: true # Required for versions of Terraform 0.12.x

Sample of formatting Terraform configuration files:

steps:
  - name: fmt
    image: target/vela-terraform:latest
    pull: always
    parameters:
      action: fmt

Sample of planning Terraform configuration:

steps:
  - name: plan
    image: target/vela-terraform:latest
    pull: always
    parameters:
      action: plan

Sample of validating Terraform configuration:

steps:
  - name: validate
    image: target/vela-terraform:latest
    pull: always
    parameters:
      action: validate

Secrets

NOTE: Users should refrain from configuring sensitive information in your pipeline in plain text.

Internal

Users can use Vela internal secrets to substitute these sensitive values at runtime:

steps:
  - name: apply
    image: target/vela-terraform:latest
    pull: always
+   secrets: [ terraform_username, terraform_password ]
    parameters:
      action: apply
      auto_approve: true # Required for versions of Terraform 0.12.x
-     username: octocat
-     password: superSecretPassword

This example will add the secrets to the apply step as environment variables:
TERRAFORM_USERNAME=<value>
TERRAFORM_PASSWORD=<value>

External

The plugin accepts the following files for authentication:

Parameter	Volume Configuration
`password`	`/vela/parameters/terraform/password`, `/vela/secrets/terraform/password`
`username`	`/vela/parameters/terraform/username`, `/vela/secrets/terraform/username`

Users can use Vela external secrets to substitute these sensitive values at runtime:

steps:
  - name: apply
    image: target/vela-terraform:latest
    pull: always
    parameters:
      action: apply
      auto_approve: true # Required for versions of Terraform 0.12.x
-     username: octocat
-     password: superSecretPassword

This example will read the secret values in the volume stored at /vela/secrets/

Parameters

NOTE:
The plugin supports reading all parameters via environment variables or files.
Any values set from a file take precedence over values set from the environment.
Terraform commands will be invoked in the current directory by default.

The following parameters are used to configure the image:

Name	Description	Required	Default	Environment Variables
`action`	action to perform with Terraform	`true`	`N/A`	`PARAMETER_ACTION` `TERRAFORM_ACTION`
`init_options`	options to use for Terraform init operation	`false`	`N/A`	`PARAMETER_INIT_OPTIONS` `TERRAFORM_INIT_OPTIONS`
`log_level`	set the log level for the plugin	`true`	`info`	`PARAMETER_LOG_LEVEL` `TERRAFORM_LOG_LEVEL`
`machine`	netrc machine name to communicate with	`true`	`github.com`	`PARAMETER_MACHINE` `TERRAFORM_MACHINE` `VELA_NETRC_MACHINE`
`password`	netrc password for authentication	`true`	set by Vela	`PARAMETER_PASSWORD` `TERRAFORM_PASSWORD` `VELA_NETRC_PASSWORD`
`username`	netrc user name for authentication	`true`	set by Vela	`PARAMETER_USERNAME` `TERRAFORM_USERNAME` `VELA_NETRC_USERNAME`
`version`	set the Terraform CLI version	`true`	`1.2.7`	`PARAMETER_VERSION` `TERRAFORM_VERSION`

The following parameters can be used within the init_options to configure the image:

Name	Description	Required	Default
`backend`	configure the backend for this configuration	`true`	`N/A`
`backend_configs`	this is merged with what is in the configuration file	`true`	`N/A`
`force_copy`	suppress prompts about copying state data	`true`	`N/A`
`from_module`	copy the contents of the given module into the target directory before initialization	`true`	`N/A`
`get`	download any modules for this configuration	`true`	`N/A`
`get_plugins`	download any missing plugins for this configuration	`true`	`N/A`
`input`	ask for input for variables if not directly set	`true`	`N/A`
`lock`	lock the state file when locking is supported	`false`	`N/A`
`lock_timeout`	duration to retry a state lock	`false`	`N/A`
`no_color`	disables colors in output	`false`	`N/A`
`plugin_dirs`	directory containing plugin binaries; overrides all default search paths for plugins	`false`	`N/A`
`reconfigure`	reconfigure the backend, ignoring any saved configuration	`false`	`N/A`
`upgrade`	install the latest version allowed within configured constraints	`false`	`N/A`
`verify_plugins`	verify the authenticity and integrity of automatically downloaded plugins	`false`	`N/A`

Apply

The following parameters are used to configure the apply action:

Command uses Terraform CLI command defaults if not overridden in config.

Name	Description	Required	Default	Environment Variables
`auto_approve`	skip interactive approval of applying resources	`false`	`false`	`PARAMETER_AUTO_APPROVE` `TERRAFORM_AUTO_APPROVE`
`backup`	path to backup the existing state file	`false`	`N/A`	`PARAMETER_BACKUP` `TERRAFORM_BACKUP`
`directory`	the directory containing Terraform files to apply	`false`	`.`	`PARAMETER_DIRECTORY` `TERRAFORM_DIRECTORY`
`lock`	lock the state file when locking is supported	`false`	`false`	`PARAMETER_LOCK` `TERRAFORM_LOCK`
`lock_timeout`	duration to retry a state lock	`false`	`N/A`	`PARAMETER_LOCK_TIMEOUT` `TERRAFORM_LOCK_TIMEOUT`
`no_color`	disables colors in output	`false`	`false`	`PARAMETER_NO_COLOR` `TERRAFORM_NO_COLOR`
`parallelism`	number of concurrent operations as Terraform walks its graph	`false`	`N/A`	`PARAMETER_PARALLELISM` `TERRAFORM_PARALLELISM`
`refresh`	update state prior to checking for differences	`false`	`false`	`PARAMETER_REFRESH` `TERRAFORM_REFRESH`
`state`	path to read and save state	`false`	`N/A`	`PARAMETER_STATE` `TERRAFORM_STATE`
`state_out`	path to write updated state file	`false`	`N/A`	`PARAMETER_STATE_OUT` `TERRAFORM_STATE_OUT`
`target`	resource to target	`false`	`N/A`	`PARAMETER_TARGET` `TERRAFORM_TARGET`
`vars`	a map of variables to pass to the Terraform (`<key>=<value>`)	`false`	`N/A`	`PARAMETER_VARS` `TERRAFORM_VARS`
`var_files`	a list of var files to use	`false`	`N/A`	`PARAMETER_VAR_FILES` `TERRAFORM_VAR_FILES`

Destroy

The following parameters are used to configure the destroy action:

Command uses Terraform CLI command defaults if not overridden in config.

Name	Description	Required	Default	Environment Variables
`auto_approve`	skip interactive approval of destroying resources	`false`	`false`	`PARAMETER_AUTO_APPROVE` `TERRAFORM_AUTO_APPROVE`
`backup`	path to backup the existing state file	`false`	`N/A`	`PARAMETER_BACKUP` `TERRAFORM_BACKUP`
`directory`	the directory containing Terraform files to destroy	`false`	`.`	`PARAMETER_DIRECTORY` `TERRAFORM_DIRECTORY`
`lock`	lock the state file when locking is supported	`false`	`false`	`PARAMETER_LOCK` `TERRAFORM_LOCK`
`lock_timeout`	duration to retry a state lock	`false`	`N/A`	`PARAMETER_LOCK_TIMEOUT` `TERRAFORM_LOCK_TIMEOUT`
`no_color`	disables colors in output	`false`	`false`	`PARAMETER_NO_COLOR` `TERRAFORM_NO_COLOR`
`parallelism`	number of concurrent operations as Terraform walks its graph	`false`	`N/A`	`PARAMETER_PARALLELISM` `TERRAFORM_PARALLELISM`
`refresh`	update state prior to checking for differences	`false`	`false`	`PARAMETER_REFRESH` `TERRAFORM_REFRESH`
`state`	path to read and save state	`false`	`N/A`	`PARAMETER_STATE` `TERRAFORM_STATE`
`state_out`	path to write updated state file	`false`	`N/A`	`PARAMETER_STATE_OUT` `TERRAFORM_STATE_OUT`
`target`	resource to target	`false`	`N/A`	`PARAMETER_TARGET` `TERRAFORM_TARGET`
`vars`	a map of variables to pass to the Terraform (`<key>=<value>`)	`false`	`N/A`	`PARAMETER_VARS` `TERRAFORM_VARS`
`var_files`	a list of var files to use	`false`	`N/A`	`PARAMETER_VAR_FILES` `TERRAFORM_VAR_FILES`

Format

The following parameters are used to configure the fmt action:

Command uses Terraform CLI command defaults if not overridden in config.

Name	Description	Required	Default	Environment Variables
`check`	validate if the input is formatted	`false`	`false`	`PARAMETER_CHECK` `TERRAFORM_CHECK`
`diff`	diffs of formatting changes	`false`	`false`	`PARAMETER_DIFF` `TERRAFORM_DIFF`
`directory`	the directory containing Terraform files to format	`false`	`.`	`PARAMETER_DIRECTORY` `TERRAFORM_DIRECTORY`
`list`	list files whose formatting differs	`false`	`false`	`PARAMETER_LIST` `TERRAFORM_LIST`
`write`	write result to source file instead of STDOUT	`false`	`false`	`PARAMETER_WRITE` `TERRAFORM_WRITE`

Plan

The following parameters are used to configure the plan action:

Command uses Terraform CLI command defaults if not overridden in config.

Name	Description	Required	Default	Environment Variables
`destroy`	destroy all resources managed by the given configuration and state	`false`	`false`	`PARAMETER_DESTROY` `TERRAFORM_DESTROY`
`detailed_exit_code`	return detailed exit codes when the command exits	`false`	`false`	`PARAMETER_DETAILED_EXIT_CODE` `TERRAFORM_DETAILED_EXIT_CODE`
`directory`	the directory containing Terraform files to plan	`false`	`.`	`PARAMETER_DIRECTORY` `TERRAFORM_DIRECTORY`
`input`	ask for input for variables if not directly set	`false`	`false`	`PARAMETER_INPUT` `TERRAFORM_INPUT`
`lock`	lock the state file when locking is supported	`false`	`false`	`PARAMETER_LOCK` `TERRAFORM_LOCK`
`lock_timeout`	duration to retry a state lock	`false`	`N/A`	`PARAMETER_LOCK_TIMEOUT` `TERRAFORM_LOCK_TIMEOUT`
`module_depth`	specifies the depth of modules to show in the output	`false`	`N/A`	`PARAMETER_MODULE_DEPTH` `TERRAFORM_MODULE_DEPTH`
`no_color`	disables colors in output	`false`	`false`	`PARAMETER_NO_COLOR` `TERRAFORM_NO_COLOR`
`parallelism`	number of concurrent operations as Terraform walks its graph	`false`	`N/A`	`PARAMETER_PARALLELISM` `TERRAFORM_PARALLELISM`
`refresh`	update state prior to checking for differences	`false`	`false`	`PARAMETER_REFRESH` `TERRAFORM_REFRESH`
`state`	path to read and save state	`false`	`N/A`	`PARAMETER_STATE` `TERRAFORM_STATE`
`target`	resource to target	`false`	`N/A`	`PARAMETER_TARGET` `TERRAFORM_TARGET`
`vars`	a map of variables to pass to the Terraform (`<key>=<value>`)	`false`	`N/A`	`PARAMETER_VARS` `TERRAFORM_VARS`
`var_files`	a list of var files to use	`false`	`N/A`	`PARAMETER_VAR_FILES` `TERRAFORM_VAR_FILES`

Validate

The following parameters are used to configure the validate action:

Command uses Terraform CLI command defaults if not overridden in config.

Name	Description	Required	Default	Environment Variables
`check_variables`	command will check whether all required variables have been specified	`false`	`false`	`PARAMETER_CHECK_VARIABLES` `TERRAFORM_CHECK_VARIABLES`
`directory`	the directory containing Terraform files to validate	`false`	`.`	`PARAMETER_DIRECTORY` `TERRAFORM_DIRECTORY`
`no_color`	disables colors in output	`false`	`false`	`PARAMETER_NO_COLOR` `TERRAFORM_NO_COLOR`
`vars`	a map of variables to pass to the Terraform (`<key>=<value>`)	`false`	`N/A`	`PARAMETER_VARS` `TERRAFORM_VARS`
`var_files`	a list of var files to use	`false`	`N/A`	`PARAMETER_VAR_FILES` `TERRAFORM_VAR_FILES`

Template

COMING SOON!

Troubleshooting

You can start troubleshooting this plugin by tuning the level of logs being displayed:

steps:
  - name: apply
    image: target/vela-terraform:latest
    pull: always
    parameters:
      action: apply
      auto_approve: true
+     log_level: trace

You can also instruct the Terraform CLI to output verbose logging:

steps:
  - name: apply
    image: target/vela-terraform:latest
    pull: always
+   environment:
+     TF_LOG: TRACE
    parameters:
      action: apply
      auto_approve: true

Below are a list of common problems and how to solve them:

Last modified March 8, 2022: feat(openssh): Add SSH & SCP documentation (#287) (fe29de8f)