install

README

hc-install

An experimental Go module for downloading or locating HashiCorp binaries, verifying signatures and checksums, and asserting version constraints.

This module is a successor to tfinstall, available in pre-1.0 versions of terraform-exec. Current users of tfinstall are advised to move to hc-install before upgrading terraform-exec to v1.0.0.

hc-install is not a package manager

This library is intended for use within Go programs or automated environments (such as CIs) which have some business downloading or otherwise locating HashiCorp binaries.

The included command-line utility, hc-install, is a convenient way of using the library in ad-hoc or CI shell scripting outside of Go.

hc-install does not:

• Determine suitable installation path based on target system. e.g. in /usr/bin or /usr/local/bin on Unix based system.
• Deal with execution of installed binaries (via service files or otherwise).
• Upgrade existing binaries on your system.
• Add nor link downloaded binaries to your $PATH.

API

The Installer offers a few high-level methods:

• Ensure(context.Context, []src.Source) to find, install, or build a product version
• Install(context.Context, []src.Installable) to install a product version

Sources

The Installer methods accept number of different Source types. Each comes with different trade-offs described below.

• fs.{AnyVersion,ExactVersion,Version} - Finds a binary in $PATH (or additional paths)
  • Pros:
    • This is most convenient when you already have the product installed on your system which you already manage.
  • Cons:
    • Only relies on a single version, expects you to manage the installation
    • Not recommended for any environment where product installation is not controlled or managed by you (e.g. default GitHub Actions image managed by GitHub)
• releases.{LatestVersion,ExactVersion} - Downloads, verifies & installs any known product from releases.hashicorp.com
  • Pros:
    • Fast and reliable way of obtaining any pre-built version of any product
    • Allows installation of enterprise versions
  • Cons:
    • Installation may consume some bandwidth, disk space and a little time
    • Potentially less stable builds (see checkpoint below)
• checkpoint.LatestVersion - Downloads, verifies & installs any known product available in HashiCorp Checkpoint
  • Pros:
    • Checkpoint typically contains only product versions considered stable
  • Cons:
    • Installation may consume some bandwidth, disk space and a little time
    • Currently doesn't allow installation of old versions or enterprise versions (see releases above)
• build.GitRevision - Clones raw source code and builds the product from it
  • Pros:
    • Useful for catching bugs and incompatibilities as early as possible (prior to product release).
  • Cons:
    • Building from scratch can consume significant amount of time & resources (CPU, memory, bandwith, disk space)
    • There are no guarantees that build instructions will always be up-to-date
    • There's increased likelihood of build containing bugs prior to release
    • Any CI builds relying on this are likely to be fragile

Example Usage

See examples at https://pkg.go.dev/github.com/hashicorp/hc-install#example-Installer.

CLI

In addition to the Go library, which is the intended primary use case of hc-install, we also distribute CLI.

The CLI comes with some trade-offs:

• more limited interface compared to the flexible Go API (installs specific versions of products via releases.ExactVersion)
• minimal environment pre-requisites (no need to compile Go code)
• see "hc-install is not a package manager"

Installation

Given that one of the key roles of the CLI/library is integrity checking, you should choose the installation method which involves the same level of integrity checks, and/or perform these checks yourself. go install provides only minimal to no integrity checks, depending on exact use. We recommend any of the installation methods documented below.

Homebrew (macOS / Linux)

Homebrew

brew install hashicorp/tap/hc-install

Linux

We support Debian & Ubuntu via apt and RHEL, CentOS, Fedora and Amazon Linux via RPM.

You can follow the instructions in the Official Packaging Guide to install the package from the official HashiCorp-maintained repositories. The package name is hc-install in all repositories.

Other platforms

1. Download for the latest version relevant for your operating system and architecture.
2. Verify integrity by comparing the SHA256 checksums which are part of the release (called hc-install_<VERSION>_SHA256SUMS).
3. Install it by unzipping it and moving it to a directory included in your system's PATH.
4. Check that you have installed it correctly via hc-install --version. You should see the latest version printed to your terminal.

Usage

Usage: hc-install install [options] -version <version> <product>

  This command installs a HashiCorp product.
  Options:
    -version  [REQUIRED] Version of product to install.
    -path     Path to directory where the product will be installed. Defaults
              to current working directory.

hc-install install -version 1.3.7 terraform

hc-install: will install terraform@1.3.7
installed terraform@1.3.7 to /current/working/dir/terraform

Documentation

Index

• type Installer
  • func NewInstaller() *Installer
  • func (i *Installer) Ensure(ctx context.Context, sources []src.Source) (string, error)
  • func (i *Installer) Install(ctx context.Context, sources []src.Installable) (string, error)
  • func (i *Installer) Remove(ctx context.Context) error
  • func (i *Installer) SetLogger(logger *log.Logger)
• type RemoveFunc

Examples

• Installer
• Installer (EnterpriseVersion)
• Installer (InstallAndBuildMultipleVersions)
• Installer (LatestVersionConstrained)
• Installer (MultipleVersions)

Types

type Installer

type Installer struct {
	// contains filtered or unexported fields
}

Example

Installation of a single exact version

ctx := context.Background()
i := install.NewInstaller()
defer i.Remove(ctx)
v1_3 := version.Must(version.NewVersion("1.3.7"))

execPath, err := i.Install(ctx, []src.Installable{
	&releases.ExactVersion{
		Product: product.Terraform,
		Version: v1_3,
	},
})
if err != nil {
	log.Fatal(err)
}
log.Printf("Terraform %s installed to %s", v1_3, execPath)

// run any tests

Example (EnterpriseVersion)

Installation of a single exact enterprise version

ctx := context.Background()
i := install.NewInstaller()
defer i.Remove(ctx)
v1_9 := version.Must(version.NewVersion("1.9.8"))
licenseDir := "/some/path"

execPath, err := i.Install(ctx, []src.Installable{
	&releases.ExactVersion{
		Product: product.Vault,
		Version: v1_9,
		Enterprise: &releases.EnterpriseOptions{ // specify that we want the enterprise version
			LicenseDir: licenseDir, // where license files should be placed (required for enterprise versions)
		},
	},
})
if err != nil {
	log.Fatal(err)
}
log.Printf("Vault %s Enterprise installed to %s; license information installed to %s", v1_9, execPath, licenseDir)

// run any tests

Example (InstallAndBuildMultipleVersions)

Installation and building of multiple versions

ctx := context.Background()
i := install.NewInstaller()
defer i.Remove(ctx)

vc := version.MustConstraints(version.NewConstraint("~> 1.3"))
rv := &releases.Versions{
	Product:     product.Terraform,
	Constraints: vc,
}

versions, err := rv.List(ctx)
if err != nil {
	log.Fatal(err)
}
versions = append(versions, &build.GitRevision{
	Product: product.Terraform,
	Ref:     "HEAD",
})

for _, installableVersion := range versions {
	execPath, err := i.Ensure(context.Background(), []src.Source{
		installableVersion,
	})
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("Terraform %s installed to %s", installableVersion, execPath)
	// run any tests
}

Example (LatestVersionConstrained)

Locating or installing latest version per constraint

ctx := context.Background()
i := install.NewInstaller()
defer i.Remove(ctx)

v1 := version.MustConstraints(version.NewConstraint("~> 1.0"))

execPath, err := i.Ensure(context.Background(), []src.Source{
	&fs.Version{
		Product:     product.Terraform,
		Constraints: v1,
	},
	&releases.LatestVersion{
		Product:     product.Terraform,
		Constraints: v1,
	},
})
if err != nil {
	log.Fatal(err)
}
log.Printf("Terraform %s available at %s", v1, execPath)

// run any tests

Example (MultipleVersions)

Installation of multiple versions

ctx := context.Background()
i := install.NewInstaller()
defer i.Remove(ctx)

v1_1 := version.Must(version.NewVersion("1.1.0"))
execPath, err := i.Install(context.Background(), []src.Installable{
	&releases.ExactVersion{
		Product: product.Terraform,
		Version: v1_1,
	},
})
if err != nil {
	log.Fatal(err)
}
log.Printf("Terraform %s available at %s", v1_1, execPath)

// run any 1.1 tests

v1_3 := version.Must(version.NewVersion("1.3.0"))
execPath, err = i.Install(context.Background(), []src.Installable{
	&releases.ExactVersion{
		Product: product.Terraform,
		Version: v1_3,
	},
})
if err != nil {
	log.Fatal(err)
}
log.Printf("Terraform %s available at %s", v1_3, execPath)

// run any 1.3 tests

func NewInstaller

func NewInstaller() *Installer

func (*Installer) Ensure

func (i *Installer) Ensure(ctx context.Context, sources []src.Source) (string, error)

func (*Installer) Install

func (i *Installer) Install(ctx context.Context, sources []src.Installable) (string, error)

func (*Installer) Remove

func (i *Installer) Remove(ctx context.Context) error

func (*Installer) SetLogger

func (i *Installer) SetLogger(logger *log.Logger)

type RemoveFunc

type RemoveFunc func(ctx context.Context) error