Simple yet flexible Go installations

This Puppet module has sane defaults to keep a standard installation simple, but is flexible enough to support automatic updates, multiple installations of diferent versions, and running Puppet as a non-root user.

Usage

Standard, single install

The golang class installs Go under /usr/local/go/, and symlinks the binaries into /usr/local/bin/.

include golang

By default it installs the latest version but never upgrades it after the initial installation. You can set it to automatically upgrade by passing latest to ensure, either with hiera (golang::ensure: latest), or with a class declaration:

class { 'golang':
  ensure => latest,
}

You may force it to install a specific version by passing it to ensure:

class { 'golang':
  ensure => '1.19.1',
}

Of course, you can also use ensure to uninstall Go:

class { 'golang':
  ensure => absent,
}

Multiple installs

You can install Go in other places and as other users using the golang::installation defined type, and you can link its binaries into a bin directory with golang::linked_binaries:

golang::installation { '/home/user/go-1.19.1':
  ensure => '1.19.1',
  owner  => 'user',
  group  => 'user',
}

golang::linked_binaries { '/home/user/go-1.19.1':
  into_bin => '/home/user/bin',
}

To install the latest version, set ensure => latest on golang::installation. To remove the installation or symlinks, just use ensure => absent.

Running Puppet as a non-root user

You can use the defined types to install Go even when running as a non-root user. owner and group default to the user and group running Puppet:

golang::installation { '/home/me/go':
  ensure => latest,
}

golang::linked_binaries { '/home/me/go':
  into_bin => '/home/me/bin',
}

Limitations

This does not support Windows.

Development status

This is stable. I have no features planned for the future, though I’m open to suggestions.

I will occasionally make 0.0.1 releases to keep this updated with the latest version of PDK.

Reference

There is specific documentation for individual parameters in REFERENCE.md. That file is generated with:

pdk bundle exec puppet strings generate --format markdown

Reference

Table of Contents

Classes

• golang: Install go in /usr/local/go and /usr/local/bin

Defined types

• golang::from_tarball: Install Go from a binary tarball
• golang::installation: Install Go in a local directory
• golang::linked_binaries: Link binaries from Go installation into a directory

Functions

• golang::latest_version: Get the lastest stable version number for Go
• golang::state_file: Figure out the default state file path for a given $go_dir

Data types

• Golang::Ensure: Valid ensure values for golang::installation
• Golang::Version: A Go version

Classes

golang

Most people will not need to change any parameter other than perhaps setting $ensure to latest.

Parameters

The following parameters are available in the golang class:

• ensure
• version
• link_binaries
• source_prefix
• os
• arch
• source

ensure

Data type: Golang::Ensure

• present: Make sure any version of Go is installed.
• latest: Make sure the latest stable version of Go is installed.
• absent: Make sure Go is uninstalled.
• version: Make sure exactly the specified version of Go is installed. For example, '1.19.1'.

Default value: present

version

Data type: Optional[Golang::Version]

Deprecated. Use $ensure instead. If this parameter is set it will only be honored if $ensure is present.

Default value: undef

link_binaries

Data type: Array[String[1]]

The binaries to symlink into /usr/local/bin.

Default value: ['go', 'gofmt']

source_prefix

Data type: Stdlib::HTTPUrl

URL to directory that contains the archive to download.

Default value: 'https://go.dev/dl'

os

Data type: String[1]

The OS to use to determine what archive to download.

Default value:

$facts['kernel'] ? {
    'Linux'  => 'linux',
    'Darwin' => 'darwin',
    default  => $facts['kernel']

arch

Data type: String[1]

The architecture to use to determine what archive to download.

Default value:

$facts['os']['hardware'] ? {
    undef     => 'amd64', # Assume amd64 if os.hardware is missing.
    'aarch64' => 'arm64',
    'armv7l'  => 'armv6l',
    'i686'    => '386',
    'x86_64'  => 'amd64',
    default   => $facts['os']['hardware']

source

Data type: Optional[Stdlib::HTTPUrl]

Deprecated. Use golang::from_tarball instead:

golang::from_tarball { '/usr/local/go':
  ensure => $ensure,
  source => $source,
}

golang::linked_binaries { '/usr/local/go':
  ensure   => $ensure,
  into_bin => '/usr/local/bin',
}

If this is set it overrides everything else except $ensure == absent.

Default value: undef

Defined types

golang::from_tarball

Install Go from a binary tarball

Examples

Standard usage

golang::from_tarball { '/usr/local/go':
  source => 'https://go.dev/dl/go1.19.1.darwin-amd64.tar.gz',
}

Running puppet as user

golang::from_tarball { '/home/user/go/go':
  source => 'https://go.dev/dl/go1.19.1.darwin-amd64.tar.gz',
}

Parameters

The following parameters are available in the golang::from_tarball defined type:

• source
• ensure
• go_dir
• owner
• group
• mode
• state_file

source

Data type: Stdlib::HTTPUrl

The URL to the binary tarball to install. If the URL changes and $ensure is present, $go_dir will be wiped and the new tarball will be installed.

ensure

Data type: Enum[present, any_version, absent]

• present: Make sure Go is installed from $source.
• any_version: Make sure Go is installed regardless of what version it is. This will not upgrade Go if $source changes.
• absent: Make sure Go is uninstalled.

Default value: present

go_dir

Data type: Stdlib::Unixpath

The path where the tarball should be installed. This path will be managed by this resource.

Default value: $name

owner

Data type: Variant[String[1], Integer[0]]

The user that should own $go_dir. May be a user name or a UID.

Default value: $facts['identity']['user']

group

Data type: Variant[String[1], Integer[0]]

The group that should own $go_dir. May be a group name or a GID.

Default value: $facts['identity']['group']

mode

Data type: String[1]

The mode for $go_dir.

Default value: '0755'

state_file

Data type: Stdlib::Unixpath

Where to store state information.

This file will contain the URL to the tarball. If the file contents don’t match the URL passed in $source, then we know that we need to download the tarball and replace the installation.

This defaults to a file in the same directory as $go_dir, but with a . prefix and a .source_url suffix. For example, if $go_dir is '/usr/local/go', then this will default to '/usr/local/.go.source_url'.

Default value: golang::state_file($go_dir)

golang::installation

Install Go in a local directory

Examples

Simple: install once and never update

golang::installation { '/usr/local/go': }

For a user

golang::installation { '/home/user/go/go':
  ensure => latest,
  owner  => 'user',
  group  => 'user',
}

A specific version

golang::installation { '/usr/local/go-1.19.1':
  ensure => '1.19.1',
}

Parameters

The following parameters are available in the golang::installation defined type:

• ensure
• go_dir
• source_prefix
• os
• arch
• owner
• group
• mode
• state_file

ensure

Data type: Golang::Ensure

• present: Make sure any version of Go is installed.
• latest: Make sure the latest stable version of Go is installed.
• absent: Make sure Go is uninstalled.
• version: Make sure exactly the specified version of Go is installed. For example, '1.19.1'.

Default value: present

go_dir

Data type: Stdlib::Unixpath

The path where Go should be installed. This path will be managed by golang::from_tarball.

Default value: $name

source_prefix

Data type: Stdlib::HTTPUrl

URL to directory that contains the archive to download.

Default value: 'https://go.dev/dl'

os

Data type: String[1]

The OS to use to determine what archive to download.

Default value:

$facts['kernel'] ? {
    'Linux'  => 'linux',
    'Darwin' => 'darwin',
    default  => $facts['kernel']

arch

Data type: String[1]

The architecture to use to determine what archive to download.

Default value:

$facts['os']['hardware'] ? {
    undef     => 'amd64', # Assume amd64 if os.hardware is missing.
    'aarch64' => 'arm64',
    'armv7l'  => 'armv6l',
    'i686'    => '386',
    'x86_64'  => 'amd64',
    default   => $facts['os']['hardware']

owner

Data type: Variant[String[1], Integer[0]]

The user that should own $go_dir. May be a user name or a UID.

Default value: $facts['identity']['user']

group

Data type: Variant[String[1], Integer[0]]

The group that should own $go_dir. May be a group name or a GID.

Default value: $facts['identity']['group']

mode

Data type: String[1]

The mode for $go_dir.

Default value: '0755'

state_file

Data type: Stdlib::Unixpath

Where to store state information.

This file will contain the URL to the tarball. If the file contents don’t match the URL we generate, then we know that we need to download the tarball and replace the installation.

This defaults to a file in the same directory as $go_dir, but with a . prefix and a .source_url suffix. For example, if $go_dir is '/usr/local/go', then this will default to '/usr/local/.go.source_url'.

Default value: golang::state_file($go_dir)

golang::linked_binaries

Link binaries from Go installation into a directory

Examples

Standard usage

golang::linked_binaries { '/usr/local/go':
  into_bin => '/usr/local/bin',
}

User install

golang::linked_binaries { '/home/user/go/go':
  into_bin => '/home/user/bin',
}

Parameters

The following parameters are available in the golang::linked_binaries defined type:

• into_bin
• ensure
• go_dir
• binaries

into_bin

Data type: Stdlib::Unixpath

The directory to link the binaries into.

ensure

Data type: Enum[present, absent]

• present: Make sure links are present.
• absent: Make sure links are absent.

Default value: present

go_dir

Data type: Stdlib::Unixpath

The directory where Go is installed.

Default value: $name

binaries

Data type: Array[String[1]]

The binaries to link.

Default value: ['go', 'gofmt']

Functions

golang::latest_version

Type: Ruby 4.x API

Makes a request to the passed URL to find the latest stable version of Go. The request will be cached for 10 minutes, so repeated calls to this function will return the same thing for at least that amount of time.

golang::latest_version(Stdlib::HTTPUrl $url)

Makes a request to the passed URL to find the latest stable version of Go. The request will be cached for 10 minutes, so repeated calls to this function will return the same thing for at least that amount of time.

Returns: Golang::Version The version number, e.g. '1.19.1'.

Raises:

• Puppet::Error If the URL is invalid, the request failed, it didn’t understand the returned JSON, or it couldn’t find a version that was listed as stable.

url

Data type: Stdlib::HTTPUrl

The URL to check. This should usually be 'https://go.dev/dl/?mode=json' unless you are getting Go from elsewhere.

golang::state_file

Type: Puppet Language

The location must be outside of $go_dir, and it must be writable by the same user (if Puppet is not being run as root).

golang::state_file(Stdlib::Absolutepath $go_dir)

The location must be outside of $go_dir, and it must be writable by the same user (if Puppet is not being run as root).

Returns: Stdlib::Absolutepath Where to store the state file by default

Raises:

• Puppet::Error If $go_dir is '/' or a few other things, this will fail because there isn’t a reasonable default outside of $go_dir itself.

go_dir

Data type: Stdlib::Absolutepath

Where Go will be installed

Data types

Golang::Ensure

Valid ensure values for golang::installation

Alias of Variant[Enum[present, latest, absent], Golang::Version]

Golang::Version

Generally something like '1.8.1', but may also be something like '1.3rc1'.

Alias of Pattern[/\A[1-9]\d*(\.\d+)*([a-z]+\d+)?\z/]

Change log

All notable changes to this project will be documented in this file.

Release 1.2.8

Release 1.2.7

Security fix

Certain Go tarballs (see below) had files owned by non-root users:

❯ curl -SsL https://go.dev/dl/go1.20.14.darwin-amd64.tar.gz | tar -tzvf - | head -3
drwxr-xr-x  0 0      0           0 Feb  2 10:19 go/
-rw-r--r--  0 gopher wheel    1339 Feb  2 10:09 go/CONTRIBUTING.md
-rw-r--r--  0 gopher wheel    1479 Feb  2 10:09 go/LICENSE

In this case, the non-root user in question mapped to the first user created on the macOS system (UID 501).

When running as root, previous versions of dp-golang would preserve file ownership when extracting the tarball, even if owner was set to something else. This meant that files, such as the go binary, ended up being writable by a non-root user.

This version of dp-golang enables tar’s --no-same-owner and --no-same-permissions flags, which cause files to be extracted as the user running Puppet, or as the user/group specified in the Puppet code.

GitHub security advisory: GHSA-8h8m-h98f-vv84

Affected Go tarballs

• Go for macOS version 1.4.3 through 1.21rc3, inclusive.
• go1.4-bootstrap-20170518.tar.gz
• go1.4-bootstrap-20170531.tar.gz

Changes

As part of the security fix mentioned above, it became necessary to be more agressive about ensuring that the owner and group of files in the installation are correct. dp-golang now deletes and recreates any Go installation it finds that has a file or directory with the wrong owner or group.

Release 1.2.6

• Synced with PDK.

Release 1.2.5

• Updated automatic PR checks to run acceptance tests with both Puppet 7 and Puppet 8 (Puppet 6 is still supported by this module, but unfortunately the acceptance test framework does not support it).
• Updated metadata to support puppet/archive 7.0.0.
• Synced with PDK.

Release 1.2.4

• Added a section about development status (stable; no features planned) to README.md.
• Synced with PDK.

Release 1.2.3

No functional changes. This release is solely to keep the released module from getting too far out of sync with git after multiple pdk updates.

Release 1.2.2

Bug fixes

• Fix in-page anchor link in README.md.

Release 1.2.1

Improvements

• Added more links to REFERENCE.md from README.md to make it easier to find reference documentation.

Bug fixes

• Anchor links seem to be broken on the Forge, so we now update links to REFERENCE.md and other markdown files to point to GitHub when making a release.
• The Hiera example in README.md referenced the deprecated golang::version instead of golang::ensure.

Release 1.2.0

Features

• Added option of ensure => latest to automatically keep Go installations at the latest stable version.
• Added golang::installation to allow multiple installs of standard Go packages from https://go.dev/dl on the same system. Installations can be owned by any user.
• Added golang::from_tarball to explicitly install from a binary tarball.
• Added golang::linked_binaries link binaries from a Go installation into a bin directory.

Improvements

• Use Stdlib::HTTPUrl data type for URL parameters.

Bug fixes

• Updated minimum Puppet version to match puppet/archive. Archive version 4.0.0 requires Puppet 5.5.8 or higher, so this module must as well.

Deprecations

• The $version parameter on golang is now deprecated. Pass the version to $ensure instead.
• The $source parameter on golang is now deprecated. Use golang::from_tarball instead.

Release 1.1.0

Features

• Added ensure parameter to allow uninstalling Go.

Bug fixes

• Used pre-release version of Puppet Strings to (mostly) fix parameter default values in REFERENCE.md.

Release 1.0.7

Features

• Latest Go version (1.19.1) installed by default.

Release 1.0.6

Bug fixes

• Updated change log.

Release 1.0.5 (withdrawn)

Features

• Latest Go version (1.18.3) installed by default.

Bug fixes

• Updated to use the current Go domain (golang.org → go.dev).
• Metadata updated to support the most recent version of puppet/archive.

Release 1.0.4

Features

• Latest Go version (1.16.7) installed by default.

Bug fixes

• The godoc binary no longer ships in the Go package, so this no longer links it into /usr/local/bin by default. Note: this does not remove the link if it already exists.
• Metadata updated to support the most recent version of puppet/archive.

Release 1.0.3

Features

• #2: support convenient installation on Raspberry Pi 2B and 3B.

Bug fixes

• #2: default to the correct 64-bit ARM binary on 64 bit ARM, e.g. on the Raspberry Pi 4.

Release 1.0.2

Features

• Latest Go version (1.13.6) installed by default.
• #2: support convenient installation on Raspberry Pi 4.