|
1 | 1 | # terraform-bundle |
2 | 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 | | -In some cases, this can be solved by installing provider plugins into the |
13 | | -[user plugins directory](https://www.terraform.io/docs/configuration/providers.html#third-party-plugins). |
14 | | -However, this doesn't always meet the needs of automated deployments. |
15 | | - |
16 | | -`terraform-bundle` provides an alternative, by allowing the auto-download |
17 | | -process to be run out-of-band on a separate machine that _does_ have access |
18 | | -to the repository. The result is a zip file that can be extracted onto the |
19 | | -target system to install both the desired Terraform version and a selection |
20 | | -of providers, thus avoiding the need for on-the-fly plugin installation. |
21 | | - |
22 | | -## Building |
23 | | - |
24 | | -To build `terraform-bundle` from source, set up a Terraform development |
25 | | -environment per [Terraform's own README](../../README.md) and then install |
26 | | -this tool from within it: |
27 | | - |
28 | | -``` |
29 | | -$ go install ./tools/terraform-bundle |
30 | | -``` |
31 | | - |
32 | | -This will install `terraform-bundle` in `$GOPATH/bin`, which is assumed by |
33 | | -the rest of this README to be in `PATH`. |
34 | | - |
35 | | -`terraform-bundle` is a repackaging of the module installation functionality |
36 | | -from Terraform itself, so for best results you should build from the tag |
37 | | -relating to the version of Terraform you plan to use. For example, use the v0.12 |
38 | | -tag to build a version of terraform-bundle compatible with Terraform v0.12*. |
39 | | - |
40 | | -## Usage |
41 | | - |
42 | | -`terraform-bundle` uses a simple configuration file to define what should |
43 | | -be included in a bundle. This is designed so that it can be checked into |
44 | | -version control and used by an automated build and deploy process. |
45 | | - |
46 | | -The configuration file format works as follows: |
47 | | - |
48 | | -```hcl |
49 | | -terraform { |
50 | | - # Version of Terraform to include in the bundle. An exact version number |
51 | | - # is required. |
52 | | - version = "0.10.0" |
53 | | -} |
54 | | -
|
55 | | -# Define which provider plugins are to be included |
56 | | -providers { |
57 | | - # Include the newest "aws" provider version in the 1.0 series. |
58 | | - aws = { |
59 | | - versions = ["~> 1.0"] |
60 | | - } |
61 | | -
|
62 | | - # Include both the newest 1.0 and 2.0 versions of the "google" provider. |
63 | | - # Each item in these lists allows a distinct version to be added. If the |
64 | | - # two expressions match different versions then _both_ are included in |
65 | | - # the bundle archive. |
66 | | - google = { |
67 | | - versions = ["~> 1.0", "~> 2.0"] |
68 | | - } |
69 | | -
|
70 | | - # Include a custom plugin to the bundle. Will search for the plugin in the |
71 | | - # plugins directory and package it with the bundle archive. Plugin must have |
72 | | - # a name of the form: terraform-provider-*, and must be built with the operating |
73 | | - # system and architecture that terraform enterprise is running, e.g. linux and amd64. |
74 | | - customplugin = { |
75 | | - versions = ["0.1"] |
76 | | - source = "myorg/customplugin" |
77 | | - } |
78 | | -} |
79 | | -
|
80 | | -``` |
81 | | - |
82 | | -The `terraform` block defines which version of Terraform will be included |
83 | | -in the bundle. An exact version is required here. |
84 | | - |
85 | | -The `providers` block defines zero or more providers to include in the bundle |
86 | | -along with core Terraform. Each attribute is a provider name, and its value is a |
87 | | -block with the list of version constraints and (optional) source. For each given |
88 | | -constraint, `terraform-bundle` will find the newest available version matching |
89 | | -the constraint and include it in the bundle. |
90 | | - |
91 | | -It is allowed to specify multiple constraints for the same provider, in which |
92 | | -case multiple versions can be included in the resulting bundle. Each constraint |
93 | | -string given results in a separate plugin in the bundle, unless two constraints |
94 | | -resolve to the same concrete plugin. |
95 | | - |
96 | | -Including multiple versions of the same provider allows several configurations |
97 | | -running on the same system to share an installation of the bundle and to |
98 | | -choose a version using version constraints within the main Terraform |
99 | | -configuration. This avoids the need to upgrade all configurations to newer |
100 | | -versions in lockstep. |
101 | | - |
102 | | -After creating the configuration file, e.g. `terraform-bundle.hcl`, a bundle |
103 | | -zip file can be produced as follows: |
104 | | - |
105 | | -``` |
106 | | -$ terraform-bundle package terraform-bundle.hcl |
107 | | -``` |
108 | | - |
109 | | -By default the bundle package will target the operating system and CPU |
110 | | -architecture where the tool is being run. To override this, use the `-os` and |
111 | | -`-arch` options. For example, to build a bundle for on-premises Terraform |
112 | | -Enterprise: |
113 | | - |
114 | | -``` |
115 | | -$ terraform-bundle package -os=linux -arch=amd64 terraform-bundle.hcl |
116 | | -``` |
117 | | - |
118 | | -The bundle file is assigned a name that includes the core Terraform version |
119 | | -number, a timestamp to the nearest hour of when the bundle was built, and the |
120 | | -target OS and CPU architecture. It is recommended to refer to a bundle using |
121 | | -this composite version number so that bundle archives can be easily |
122 | | -distinguished from official release archives and from each other when multiple |
123 | | -bundles contain the same core Terraform version. |
124 | | - |
125 | | -## Custom Plugins |
126 | | -To include custom plugins in the bundle file, create a local directory named |
127 | | -`./.plugins` and put all the plugins you want to include there, under the |
128 | | -required [sub directory](#plugins-directory-layout). Optionally, you can use the |
129 | | -`-plugin-dir` flag to specify a location where to find the plugins. To be |
130 | | -recognized as a valid plugin, the file must have a name of the form |
131 | | -`terraform-provider-<NAME>`. In addition, ensure that the plugin is built using |
132 | | -the same operating system and architecture used for Terraform Enterprise. |
133 | | -Typically this will be `linux` and `amd64`. |
134 | | - |
135 | | -### Plugins Directory Layout |
136 | | -To include custom plugins in the bundle file, you must specify a "source" |
137 | | -attribute in the configuration and place the plugin in the appropriate |
138 | | -subdirectory under `./.plugins`. The directory must have the following layout: |
139 | | - |
140 | | -``` |
141 | | -./.plugins/$SOURCEHOST/$SOURCENAMESPACE/$NAME/$VERSION/$OS_$ARCH/ |
142 | | -``` |
143 | | - |
144 | | -When installing custom plugins, you may choose any arbitrary identifier for the |
145 | | -$SOURCEHOST and $SOURCENAMESPACE subdirectories. |
146 | | - |
147 | | -For example, given the following configuration and a plugin built for Terraform Enterprise: |
148 | | - |
149 | | -``` |
150 | | -providers { |
151 | | - customplugin = { |
152 | | - versions = ["0.1"] |
153 | | - source = "example.com/myorg/customplugin" |
154 | | - } |
155 | | -} |
156 | | -``` |
157 | | - |
158 | | -The binary must be placed in the following directory: |
159 | | - |
160 | | -``` |
161 | | -./.plugins/example.com/myorg/customplugin/0.1/linux_amd64/ |
162 | | -``` |
163 | | - |
164 | | -## Provider Resolution Behavior |
165 | | - |
166 | | -Terraform's provider resolution behavior is such that if a given constraint |
167 | | -can be resolved by any plugin already installed on the system it will use |
168 | | -the newest matching plugin and not attempt automatic installation. |
169 | | - |
170 | | -Therefore if automatic installation is not desired, it is important to ensure |
171 | | -that version constraints within Terraform configurations do not exclude all |
172 | | -of the versions available from the bundle. If a suitable version cannot be |
173 | | -found in the bundle, Terraform _will_ attempt to satisfy that dependency by |
174 | | -automatic installation from the official repository. |
175 | | - |
176 | | -For full details about provider resolution, see |
177 | | -[How Terraform Works: Plugin Discovery](https://www.terraform.io/docs/extend/how-terraform-works.html#discovery). |
178 | | - |
179 | | -The downloaded provider archives are verified using the same signature check |
180 | | -that is used for auto-installed plugins, using Hashicorp's release key. At |
181 | | -this time, the core Terraform archive itself is _not_ verified in this way; |
182 | | -that may change in a future version of this tool. |
183 | | - |
184 | | -## Installing a Bundle in Terraform Enterprise |
185 | | - |
186 | | -If using a Terraform Enterprise instance in an "air-gapped" |
187 | | -environment, this tool can produce a custom Terraform version package, which |
188 | | -includes a set of provider plugins along with core Terraform. |
189 | | - |
190 | | -To create a suitable bundle, use the `-os` and `-arch` options as described |
191 | | -above to produce a bundle targeting `linux_amd64`. You can then place this |
192 | | -archive on an HTTP server reachable by the Terraform Enterprise hosts and |
193 | | -install it as per |
194 | | -[Administration: Managing Terraform Versions](https://www.terraform.io/docs/enterprise/admin/resources.html#managing-terraform-versions). |
195 | | - |
196 | | -After clicking the "Add Terraform Version" button: |
197 | | - |
198 | | -1. In the "Version" field, enter the generated bundle version from the bundle |
199 | | - filename, which will be of the form `N.N.N-bundleYYYYMMDDHH`. |
200 | | -2. In the "URL" field, enter the URL where the generated bundle archive can be found. |
201 | | -3. In the "SHA256 Checksum" field, enter the SHA256 hash of the file, which can |
202 | | - be found by running `sha256sum <FILE>` or `shasum -a256 <FILE>`. |
203 | | - |
204 | | -The new bundle version can then be selected as the Terraform version for |
205 | | -any workspace. When selected, configurations that require only plugins |
206 | | -included in the bundle will run without trying to auto-install. |
207 | | - |
208 | | -Note that the above does _not_ apply to Terraform Pro, or to Terraform Premium |
209 | | -when not running a private install. In these packages, Terraform versions |
210 | | -are managed centrally across _all_ organizations and so custom bundles are not |
211 | | -supported. |
212 | | - |
213 | | -For more information on the available Terraform Enterprise packages, see |
214 | | -[the Terraform product site](https://www.hashicorp.com/products/terraform/). |
| 3 | +terraform-bundle is no longer actively maintained. We recommend that you switch |
| 4 | +to one of the [alternative provider installation methods](https://www.terraform.io/docs/cli/config/config-file.html#provider-installation) |
| 5 | +introduced in Terraform v0.13. To continue using terraform-bundle, you can build |
| 6 | +terraform-bundle from the v0.15 branch of the terraform repository. |
0 commit comments