install

package module
v0.8.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 6, 2023 License: MPL-2.0 Imports: 7 Imported by: 0

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

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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

Output:
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

Output:
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
}

Output:
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

Output:
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

Output:

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

Source Files

View all Source files

Directories

Path Synopsis
cmd
hc-install
internal
build
httpclient
pubkey
releasesjson
src
testutil
validators

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.