Skip to content

Commit 5a48530

Browse files
authored
tools: remove terraform-bundle. (hashicorp#28876)
* tools: remove terraform-bundle. terraform-bundle is no longer supported in the main branch of terraform. Users can build terraform-bundle from terraform tagged v0.15 and older. * add a README pointing users to the v0.15 branch
1 parent 79c6109 commit 5a48530

14 files changed

Lines changed: 6 additions & 1118 deletions

File tree

‎.circleci/config.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ jobs:
9393
- run:
9494
name: Run Go E2E Tests
9595
command: |
96-
gotestsum --format=short-verbose --junitfile $TEST_RESULTS_DIR/gotestsum-report.xml -- -p 2 -cover -coverprofile=cov_e2e.part ./internal/command/e2etest ./tools/terraform-bundle/e2etest
96+
gotestsum --format=short-verbose --junitfile $TEST_RESULTS_DIR/gotestsum-report.xml -- -p 2 -cover -coverprofile=cov_e2e.part ./internal/command/e2etest
9797
9898
# save coverage report parts
9999
- persist_to_workspace:

‎internal/providercache/dir.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ func NewDir(baseDir string) *Dir {
5858
// running.
5959
//
6060
// This is primarily intended for portable unit testing and not particularly
61-
// useful in "real" callers, with the exception of terraform-bundle.
61+
// useful in "real" callers.
6262
func NewDirWithPlatform(baseDir string, platform getproviders.Platform) *Dir {
6363
return &Dir{
6464
baseDir: baseDir,

‎tools/terraform-bundle/CHANGELOG.md‎

Lines changed: 0 additions & 11 deletions
This file was deleted.

‎tools/terraform-bundle/README.md‎

Lines changed: 4 additions & 212 deletions
Original file line numberDiff line numberDiff line change
@@ -1,214 +1,6 @@
11
# terraform-bundle
22

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.

‎tools/terraform-bundle/config.go‎

Lines changed: 0 additions & 87 deletions
This file was deleted.

‎tools/terraform-bundle/e2etest/doc.go‎

Lines changed: 0 additions & 2 deletions
This file was deleted.

‎tools/terraform-bundle/e2etest/main_test.go‎

Lines changed: 0 additions & 39 deletions
This file was deleted.

0 commit comments

Comments
 (0)