REFERENCE.md

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/]