github.com/rstandt/terraform@v0.12.32-0.20230710220336-b1063613405c/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  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. There is some slack in
    38  this requirement due to the fact that the module installation behavior changes
    39  rarely, but please note that in particular bundles for versions of
    40  Terraform before v0.12 must be built from a `terraform-bundle` built against
    41  a Terraform v0.11 tag at the latest, since Terraform v0.12 installs plugins
    42  in a different way that is not compatible.
    43  
    44  ## Usage
    45  
    46  `terraform-bundle` uses a simple configuration file to define what should
    47  be included in a bundle. This is designed so that it can be checked into
    48  version control and used by an automated build and deploy process.
    49  
    50  The configuration file format works as follows:
    51  
    52  ```hcl
    53  terraform {
    54    # Version of Terraform to include in the bundle. An exact version number
    55    # is required.
    56    version = "0.10.0"
    57  }
    58  
    59  # Define which provider plugins are to be included
    60  providers {
    61    # Include the newest "aws" provider version in the 1.0 series.
    62    aws = ["~> 1.0"]
    63  
    64    # Include both the newest 1.0 and 2.0 versions of the "google" provider.
    65    # Each item in these lists allows a distinct version to be added. If the
    66    # two expressions match different versions then _both_ are included in
    67    # the bundle archive.
    68    google = ["~> 1.0", "~> 2.0"]
    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 build with the operating
    73    # system and architecture that terraform enterprise is running, e.g. linux and amd64
    74    customplugin = ["0.1"]
    75  }
    76  
    77  ```
    78  
    79  The `terraform` block defines which version of Terraform will be included
    80  in the bundle. An exact version is required here.
    81  
    82  The `providers` block defines zero or more providers to include in the bundle
    83  along with core Terraform. Each attribute in this block is a provider name,
    84  and its value is a list of version constraints. For each given constraint,
    85  `terraform-bundle` will find the newest available version matching the
    86  constraint and include it in the bundle.
    87  
    88  It is allowed to specify multiple constraints for the same provider, in which
    89  case multiple versions can be included in the resulting bundle. Each constraint
    90  string given results in a separate plugin in the bundle, unless two constraints
    91  resolve to the same concrete plugin.
    92  
    93  Including multiple versions of the same provider allows several configurations
    94  running on the same system to share an installation of the bundle and to
    95  choose a version using version constraints within the main Terraform
    96  configuration. This avoids the need to upgrade all configurations to newer
    97  versions in lockstep.
    98  
    99  After creating the configuration file, e.g. `terraform-bundle.hcl`, a bundle
   100  zip file can be produced as follows:
   101  
   102  ```
   103  $ terraform-bundle package terraform-bundle.hcl
   104  ```
   105  
   106  By default the bundle package will target the operating system and CPU
   107  architecture where the tool is being run. To override this, use the `-os` and
   108  `-arch` options. For example, to build a bundle for on-premises Terraform
   109  Enterprise:
   110  
   111  ```
   112  $ terraform-bundle package -os=linux -arch=amd64 terraform-bundle.hcl
   113  ```
   114  
   115  The bundle file is assigned a name that includes the core Terraform version
   116  number, a timestamp to the nearest hour of when the bundle was built, and the
   117  target OS and CPU architecture. It is recommended to refer to a bundle using
   118  this composite version number so that bundle archives can be easily
   119  distinguished from official release archives and from each other when multiple
   120  bundles contain the same core Terraform version.
   121  
   122  To include custom plugins in the bundle file, create a local directory "./plugins"
   123  and put all the plugins you want to include there. Optionally, you can use the
   124  `-plugin-dir` flag to specify a location where to find the plugins. To be recognized
   125  as a valid plugin, the file must have a name of the form
   126  `terraform-provider-<NAME>_v<VERSION>`. In
   127  addition, ensure that the plugin is built using the same operating system and
   128  architecture used for Terraform Enterprise. Typically this will be `linux` and `amd64`.
   129  
   130  ## Provider Resolution Behavior
   131  
   132  Terraform's provider resolution behavior is such that if a given constraint
   133  can be resolved by any plugin already installed on the system it will use
   134  the newest matching plugin and not attempt automatic installation.
   135  
   136  Therefore if automatic installation is not desired, it is important to ensure
   137  that version constraints within Terraform configurations do not exclude all
   138  of the versions available from the bundle. If a suitable version cannot be
   139  found in the bundle, Terraform _will_ attempt to satisfy that dependency by
   140  automatic installation from the official repository. If you want
   141  `terraform init` to explicitly fail instead of contacting the repository, pass
   142  the `-get-plugins=false` option.
   143  
   144  For full details about provider resolution, see
   145  [How Terraform Works: Plugin Discovery](https://www.terraform.io/docs/extend/how-terraform-works.html#discovery).
   146  
   147  The downloaded provider archives are verified using the same signature check
   148  that is used for auto-installed plugins, using Hashicorp's release key. At
   149  this time, the core Terraform archive itself is _not_ verified in this way;
   150  that may change in a future version of this tool.
   151  
   152  ## Installing a Bundle in Terraform Enterprise
   153  
   154  If using a Terraform Enterprise instance in an "air-gapped"
   155  environment, this tool can produce a custom Terraform version package, which
   156  includes a set of provider plugins along with core Terraform.
   157  
   158  To create a suitable bundle, use the `-os` and `-arch` options as described
   159  above to produce a bundle targeting `linux_amd64`. You can then place this
   160  archive on an HTTP server reachable by the Terraform Enterprise hosts and
   161  install it as per
   162  [Administration: Managing Terraform Versions](https://www.terraform.io/docs/enterprise/admin/resources.html#managing-terraform-versions).
   163  
   164  After clicking the "Add Terraform Version" button:
   165  
   166  1. In the "Version" field, enter the generated bundle version from the bundle
   167     filename, which will be of the form `N.N.N-bundleYYYYMMDDHH`.
   168  2. In the "URL" field, enter the URL where the generated bundle archive can be found.
   169  3. In the "SHA256 Checksum" field, enter the SHA256 hash of the file, which can
   170     be found by running `sha256sum <FILE>` or `shasum -a256 <FILE>`.
   171  
   172  The new bundle version can then be selected as the Terraform version for
   173  any workspace. When selected, configurations that require only plugins
   174  included in the bundle will run without trying to auto-install.
   175  
   176  Note that the above does _not_ apply to Terraform Pro, or to Terraform Premium
   177  when not running a private install. In these packages, Terraform versions
   178  are managed centrally across _all_ organizations and so custom bundles are not
   179  supported.
   180  
   181  For more information on the available Terraform Enterprise packages, see
   182  [the Terraform product site](https://www.hashicorp.com/products/terraform/).