github.com/justnom/terraform@v0.5.4-0.20180524223219-170a1530d1ca/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/).