Repository files navigation

This is a Terraform mixin forPorter.

This will install the latest mixin release via the Porter CLI.

porter mixin install terraform

Following commands build the terraform mixin.

git clone https://github.com/getporter/terraform-mixin.gitcd terraform-mixin# Learn about Mage in our CONTRIBUTING.mdgo run mage.go EnsureMagemage build

Then, to install the resulting mixin into PORTER_HOME, executemage install

mixins:-terraform:clientVersion:1.0.3workingDir:myinfrainitFile:providers.tfinstallHost:install.example.comproviderHost:providers.example.com

The Terraform client version can be specified via theclientVersion configuration when declaring this mixin.

TheworkingDir configuration setting is the relative path to your terraform files. Defaults to "terraform".

Terraform providers are installed into the bundle during porter build.We recommend that you put your provider declarations into a single file, e.g. "terraform/providers.tf".Then useinitFile to specify the relative path to this file within workingDir.This will dramatically improve Docker image layer caching and performance when building, publishing and installing the bundle.

Note: this approach isn't suitable when using terraform modules as those need to be "initilized" as well but aren't specified in theinitFile. You shouldn't specifiy aninitFile in this situation.

Optional host that mirrors the official terraform installation athttps://releases.hashicorp.com/* in order to install in an air-gappedenvironment.

Optional host to use as a network mirror when installing terraform providers.This needs to conform to theTerraform registryprotocol.

When you declare the mixin, you can disable the mixin from customizing the azure user agent string

mixins:-terraform:userAgentOptOut:true

By default, the terraform mixin adds the porter and mixin version to the user agent string used by the azure provider.We use this to understand which version of porter and the mixin are being used by a bundle, and assist with troubleshooting.Below is an example of what the user agent string looks like:

AZURE_HTTP_USER_AGENT="getporter/porter/v1.0.0 getporter/terraform/v1.2.3"

You can add your own custom strings to the user agent string by editing yourtemplate Dockerfile and setting the AZURE_HTTP_USER_AGENT environment variable.

The simplest way to use this mixin with Porter is to let Porter track the Terraformstate as actions are executed. This can be done via a parameter of typefile that has a source of a corresponding output (of the samefile type). Each time the bundle is executed, the output will capture the updated state file and inject it into the next action via its parameter correlate.

Here is an example setup that works with Porter v0.38:

parameters:  -name:tfstatetype:file# This designates the path within the installer to place the parameter valuepath:/cnab/app/terraform/terraform.tfstate# Here we tell Porter that the value for this parameter should come from the 'tfstate' outputsource:output:tfstateoutputs:  -name:tfstatetype:file# This designates the path within the installer to read the output frompath:/cnab/app/terraform/terraform.tfstate

If you are working with the Porter v1 prerelease, use the new state section:

state:  -name:tfstatepath:terraform/terraform.tfstate  -name:tfvarspath:terraform/terraform.tfvars.json

TheTabbyCats Tracker bundle is a good example of how to use the terraform mixin with the Porter v1 prerelease.

The specified path inside the installer (/cnab/app/terraform/terraform.tfstate) should be where Terraform will be looking to read/write its state. For a full example bundle using this approach, see thebasic-tf-example.

Alternatively, state can be managed by a remote backend. When doing so, each action step needs to supply the remote backend config viabackendConfig. In the step examples below, the configuration has key/value pairs according to theAzurerm backend.

By default the mixin will create a defaultterraform.tfvars.jsonfile from thevars block during during the install step.

To use this file, atfvars file parameter and output must be added to persist it for subsequent steps.

This can be disabled by settingdisableVarFile totrue during install.

Here is an example setup using the tfvar file:

parameters:  -name:tfvarstype:file# This designates the path within the installer to place the parameter valuepath:/cnab/app/terraform/terraform.tfvars.json# Here we tell Porter that the value for this parameter should come from the 'tfvars' outputsource:output:tfvars  -name:footype:stringapplyTo:      -install  -name:baztype:stringdefault:blazapplyTo:      -installoutputs:  -name:tfvarstype:file# This designates the path within the installer to read the output frompath:/cnab/app/terraform/terraform.tfvars.jsoninstall:  -terraform:description:"Install Azure Key Vault"vars:foo:barbaz:bizoutputs:      -name:vault_uriupgrade:# No var block required  -terraform:description:"Install Azure Key Vault"outputs:      -name:vault_uriuninstall:# No var block required  -terraform:description:"Install Azure Key Vault"outputs:      -name:vault_uri

and with var file disabled

parameters:  -name:footype:stringapplyTo:      -install  -name:baztype:stringdefault:blazapplyTo:      -installinstall:  -terraform:description:"Install Azure Key Vault"disableVarFile:truevars:foo:barbaz:bizoutputs:      -name:vault_uriuninstall:# Var block required  -terraform:description:"Install Azure Key Vault"vars:foo:barbaz:biz

install:  -terraform:description:"Install Azure Key Vault"backendConfig:key:"mybundle.tfstate"storage_account_name:"mystorageacct"container_name:"mycontainer"access_key:"myaccesskey"outputs:      -name:vault_uri

upgrade:  -terraform:description:"Upgrade Azure Key Vault"backendConfig:key:"mybundle.tfstate"storage_account_name:"mystorageacct"container_name:"mycontainer"access_key:"myaccesskey"outputs:      -name:vault_uri

An invoke step is used for any custom action (not one ofinstall,upgrade oruninstall).

By default, the command given toterraform will be the step name. Here it isshow,resulting interraform show with the provided configuration.

show:  -terraform:description:"Invoke 'terraform show'"backendConfig:key:"mybundle.tfstate"storage_account_name:"mystorageacct"container_name:"mycontainer"access_key:"myaccesskey"

Or, if the step name does not match the intended terraform command, the commandcan be supplied via thearguments: section, like so:

printVersion:  -terraform:description:"Invoke 'terraform version'"arguments:        -version

uninstall:  -terraform:description:"Uninstall Azure Key Vault"backendConfig:key:"mybundle.tfstate"storage_account_name:"mystorageacct"container_name:"mycontainer"access_key:"myaccesskey"

See further examples in theExamples directory

As seen above, outputs can be declared for a step. All that is needed is the name of the output.

For each output listed,terraform output <output name> is invoked to fetch the output valuefrom the state file for use by Porter. Outputs can be saved to the filesystem so that subsequentsteps can use the file by specifying thedestinationFile field. This is particularly usefulwhen your terraform module creates a Kubernetes cluster. In the example below, the modulecreates a cluster, and then writes the kubeconfig to /root/.kube/config so that the rest of thebundle can immediately use the cluster.

install:  -terraform:description:"Create a Kubernetes cluster"outputs:      -name:kubeconfigdestinationFile:/root/.kube/config

See the PorterOutputs documentation on how to wire upoutputs for use in a bundle.