github.com/robertreppel/terraform@v0.11.8-0.20180412164320-05291ab9822d/tools/terraform-bundle/README.md (about) 1 # terraform-bundle 2 3 `terraform-bundle` is a helper program to create "bundle archives", which are 4 zip files that contain both a particular version of Terraform and a number 5 of provider plugins. 6 7 Normally `terraform init` will download and install the plugins necessary to 8 work with a particular configuration, but sometimes Terraform is deployed in 9 a network that, for one reason or another, cannot access the official 10 plugin repository for automatic download. 11 12 `terraform-bundle` provides an alternative, by allowing the auto-download 13 process to be run out-of-band on a separate machine that _does_ have access 14 to the repository. The result is a zip file that can be extracted onto the 15 target system to install both the desired Terraform version and a selection 16 of providers, thus avoiding the need for on-the-fly plugin installation. 17 18 ## Building 19 20 To build `terraform-bundle` from source, set up a Terraform development 21 environment per [Terraform's own README](../../README.md) and then install 22 this tool from within it: 23 24 ``` 25 $ go install ./tools/terraform-bundle 26 ``` 27 28 This will install `terraform-bundle` in `$GOPATH/bin`, which is assumed by 29 the rest of this README to be in `PATH`. 30 31 ## Usage 32 33 `terraform-bundle` uses a simple configuration file to define what should 34 be included in a bundle. This is designed so that it can be checked into 35 version control and used by an automated build and deploy process. 36 37 The configuration file format works as follows: 38 39 ```hcl 40 terraform { 41 # Version of Terraform to include in the bundle. An exact version number 42 # is required. 43 version = "0.10.0" 44 } 45 46 # Define which provider plugins are to be included 47 providers { 48 # Include the newest "aws" provider version in the 1.0 series. 49 aws = ["~> 1.0"] 50 51 # Include both the newest 1.0 and 2.0 versions of the "google" provider. 52 # Each item in these lists allows a distinct version to be added. If the 53 # two expressions match different versions then _both_ are included in 54 # the bundle archive. 55 google = ["~> 1.0", "~> 2.0"] 56 57 # Include a custom plugin to the bundle. Will search for the plugin in the 58 # plugins directory, and package it with the bundle archive. Plugin must have 59 # a name of the form: terraform-provider-*, and must be build with the operating 60 # system and architecture that terraform enterprise is running, e.g. linux and amd64 61 customplugin = ["0.1"] 62 } 63 64 ``` 65 66 The `terraform` block defines which version of Terraform will be included 67 in the bundle. An exact version is required here. 68 69 The `providers` block defines zero or more providers to include in the bundle 70 along with core Terraform. Each attribute in this block is a provider name, 71 and its value is a list of version constraints. For each given constraint, 72 `terraform-bundle` will find the newest available version matching the 73 constraint and include it in the bundle. 74 75 It is allowed to specify multiple constraints for the same provider, in which 76 case multiple versions can be included in the resulting bundle. Each constraint 77 string given results in a separate plugin in the bundle, unless two constraints 78 resolve to the same concrete plugin. 79 80 Including multiple versions of the same provider allows several configurations 81 running on the same system to share an installation of the bundle and to 82 choose a version using version constraints within the main Terraform 83 configuration. This avoids the need to upgrade all configurations to newer 84 versions in lockstep. 85 86 After creating the configuration file, e.g. `terraform-bundle.hcl`, a bundle 87 zip file can be produced as follows: 88 89 ``` 90 $ terraform-bundle package terraform-bundle.hcl 91 ``` 92 93 By default the bundle package will target the operating system and CPU 94 architecture where the tool is being run. To override this, use the `-os` and 95 `-arch` options. For example, to build a bundle for on-premises Terraform 96 Enterprise: 97 98 ``` 99 $ terraform-bundle package -os=linux -arch=amd64 terraform-bundle.hcl 100 ``` 101 102 The bundle file is assigned a name that includes the core Terraform version 103 number, a timestamp to the nearest hour of when the bundle was built, and the 104 target OS and CPU architecture. It is recommended to refer to a bundle using 105 this composite version number so that bundle archives can be easily 106 distinguished from official release archives and from each other when multiple 107 bundles contain the same core Terraform version. 108 109 To include custom plugins in the bundle file, create a local directory "./plugins" 110 and put all the plugins you want to include there. Optionally, you can use the 111 `-plugin-dir` flag to specify a location where to find the plugins. To be recognized 112 as a valid plugin, the file must have a name of the form: "terraform-provider-*-v*". In 113 addition, ensure that the plugin is build using the same operating system and 114 architecture used for terraform enterprise. Typically this will be linux and amd64. 115 116 ## Provider Resolution Behavior 117 118 Terraform's provider resolution behavior is such that if a given constraint 119 can be resolved by any plugin already installed on the system it will use 120 the newest matching plugin and not attempt automatic installation. 121 122 Therefore if automatic installation is not desired, it is important to ensure 123 that version constraints within Terraform configurations do not exclude all 124 of the versions available from the bundle. If a suitable version cannot be 125 found in the bundle, Terraform _will_ attempt to satisfy that dependency by 126 automatic installation from the official repository. 127 128 The downloaded provider archives are verified using the same signature check 129 that is used for auto-installed plugins, using Hashicorp's release key. At 130 this time, the core Terraform archive itself is _not_ verified in this way; 131 that may change in a future version of this tool. 132 133 ## Installing a Bundle in On-premises Terraform Enterprise 134 135 If using a private install of Terraform Enterprise in an "air-gapped" 136 environment, this tool can produce a custom _tool package_ for Terraform, which 137 includes a set of provider plugins along with core Terraform. 138 139 To create a suitable bundle, use the `-os` and `-arch` options as described 140 above to produce a bundle targeting `linux_amd64`. You can then place this 141 archive on an HTTP server reachable by the Terraform Enterprise hosts and 142 install it as per 143 [Managing Tool Versions](https://github.com/hashicorp/terraform-enterprise-modules/blob/master/docs/managing-tool-versions.md). 144 145 After choosing the "Add Tool Version" button, be sure to set the Tool to 146 "terraform" and then enter as the Version the generated bundle version from 147 the bundle filename, which will be of the form `N.N.N-bundleYYYYMMDDHH`. 148 Enter the URL at which the generated bundle archive can be found, and the 149 SHA256 hash of the file which can be determined by running the tool 150 `sha256sum` with the given file. 151 152 The new bundle version can then be selected as the Terraform version for 153 any workspace. When selected, configurations that require only plugins 154 included in the bundle will run without trying to auto-install. 155 156 Note that the above does _not_ apply to Terraform Pro, or to Terraform Premium 157 when not running a private install. In these packages, Terraform versions 158 are managed centrally across _all_ organizations and so custom bundles are not 159 supported. 160 161 For more information on the available Terraform Enterprise packages, see 162 [the Terraform product site](https://www.hashicorp.com/products/terraform/).