.\" Automatically generated by Pandoc 2.2.1
.\"
.TH "G10K" "1" "January 2019" "0.5.7" "User Commands"
.hy
.SH NAME
.PP
\f[B]g10k\f[] \- Puppet environment and module deployment
.SH SYNOPSIS
.PP
\f[B]g10k\f[] [\f[I]OPTIONS\f[]]
.PP
\f[B]g10k\f[] \f[B]\[en]version\f[]
.SH DESCRIPTION
.PP
\f[B]g10k\f[] is a tool for deploying Puppet environments and modules,
much like r10k.
Its an almost drop\-in replacement for r10k with additional features
such as caching, version\-pre\-checking and distinct SSH keys for each
source.
In general it also a lot faster than the original r10k.
.SH OPTIONS
.TP
.B \-branch string
which git branch of the Puppet environment to update, e.g.\ core_foobar
.RS
.RE
.TP
.B \-cachedir string
allows overriding of the g10k config file cachedir setting, the folder
in which g10k will download git repositories and Forge modules
.RS
.RE
.TP
.B \-check4update
only check if the is newer version of the Puppet module avaialable.
Does implicitly set dryrun to true
.RS
.RE
.TP
.B \-checksum
get the md5 check sum for each Puppetlabs Forge module and verify the
integrity of the downloaded archive.
Increases g10k run time!
.RS
.RE
.TP
.B \-config string
which config file to use
.RS
.RE
.TP
.B \-debug
log debug output, defaults to false
.RS
.RE
.TP
.B \-dryrun
do not modify anything, just print what would be changed
.RS
.RE
.TP
.B \-force
purge the Puppet environment directory and do a full sync
.RS
.RE
.TP
.B \-gitobjectsyntaxnotsupported
if your git version is too old to support reference syntax like
master^{object} use this setting to revert to the older syntax
.RS
.RE
.TP
.B \-info
log info output, defaults to false
.RS
.RE
.TP
.B \-maxextractworker int
how many Goroutines are allowed to run in parallel for local Git and
Forge module extracting processes (git clone, untar and gunzip) (default
20)
.RS
.RE
.TP
.B \-maxworker int
how many Goroutines are allowed to run in parallel for Git and Forge
module resolving (default 50)
.RS
.RE
.TP
.B \-module string
which module of the Puppet environment to update, e.g.\ stdlib
.RS
.RE
.TP
.B \-moduledir string
allows overriding of Puppetfile specific moduledir setting, the folder
in which Puppet modules will be extracted
.RS
.RE
.TP
.B \-outputname string
overwrite the environment name if \-branch is specified
.RS
.RE
.TP
.B \-puppetfile
install all modules from Puppetfile in cwd
.RS
.RE
.TP
.B \-puppetfilelocation string
which Puppetfile to use in \-puppetfile mode (default
\[lq]./Puppetfile\[rq])
.RS
.RE
.TP
.B \-quiet
no output, defaults to false
.RS
.RE
.TP
.B \-retrygitcommands
if g10k should purge the local repository and retry a failed git command
(clone or remote update) instead of failing
.RS
.RE
.TP
.B \-tags
to pull tags as well as branches
.RS
.RE
.TP
.B \-usecachefallback
if g10k should try to use its cache for sources and modules instead of
failing
.RS
.RE
.TP
.B \-usemove
do not use hardlinks to populate your Puppet environments with
Puppetlabs Forge modules.
Instead uses simple move commands and purges the Forge cache directory
after each run! (Useful for g10k runs insidea Docker container)
.RS
.RE
.TP
.B \-verbose
log verbose output, defaults to false
.RS
.RE
.TP
.B \-version
show build time and version number
.RS
.RE
.SH NOTES
.IP \[bu] 2
Before using g10k with a large Puppet setup with many modules, be sure
to increase the amount of open file handles (nfiles) and number of child
processes (nproc), see limits.conf(5) for details.
.IP \[bu] 2
If you are using a private Git or Forge server think about adjusting the
\f[C]\-maxworker\f[] parameter/config setting before DOSing your own
infrastructure (default 50)
.IP \[bu] 2
To protect your local machine use \f[C]\-maxextractworker\f[]
parameter/config setting with which you can limit the number of
Goroutines that are allowed to run in parallel for local Git and Forge
module extracting processes (git clone, untar and gunzip) (default 20)
.IP \[bu] 2
To use g10k behind a proxy, set the environment variables
\f[C]http_proxy\f[] or \f[C]https_proxy\f[].
E.g.
\f[C]http_proxy=http://proxy.domain.tld:8080\ ./g10k\ \-puppetfile\f[].
See https://golang.org/pkg/net/http/#ProxyFromEnvironment for details.
.SH ADDITIONAL PUPPETFILE FEATURES
.IP \[bu] 2
link Git module branch to the current environment branch:
.IP
.nf
\f[C]
mod\ \[aq]awesomemodule\[aq],
\ \ \ \ :git\ =>\ \[aq]http://github.com/foo/bar.git\[aq],
\ \ \ \ :link\ =>\ \[aq]true\[aq]
\f[]
.fi
.PP
If you are in environment branch \f[C]dev\f[] then g10k would try to
check out this module with branch \f[C]dev\f[].
This helps to be able to use the same Puppetfile over multiple
environment branches and makes merges easier.
See https://github.com/xorpaul/g10k/issues/6 for details.
.PP
Now also supports the r10k setting name
\f[C]:branch\ =>\ :control_branch\f[] See
https://github.com/xorpaul/g10k/issues/73
.IP \[bu] 2
only clone if branch/tag/commit exists
.IP
.nf
\f[C]
mod\ \[aq]awesomemodule\[aq],
\ \ \ \ :git\ =>\ \[aq]http://github.com/foo/bar.git\[aq],
\ \ \ \ :ignore\-unreachable\ =>\ \[aq]true\[aq]
\f[]
.fi
.PP
In combination with the previous link feature you don't need to keep all
environment branches also available for your modules.
See https://github.com/xorpaul/g10k/issues/9 for details.
.IP \[bu] 2
use different Forge base URL for your modules in your Puppetfile
.IP
.nf
\f[C]
forge.baseUrl\ http://foobar.domain.tld/
\f[]
.fi
.IP \[bu] 2
skip version checks for latest Forge modules for a certain time to speed
up the sync
.IP
.nf
\f[C]
forge.cacheTtl\ 4h
\f[]
.fi
.PP
You need to specify the TTL value in the form of golang Duration
(https://golang.org/pkg/time/#ParseDuration)
.IP \[bu] 2
try multiple Git branches for a Puppet module until one can be used
.IP
.nf
\f[C]
mod\ \[aq]stdlib\[aq],
\ \ \ \ :git\ =>\ \[aq]https://github.com/puppetlabs/puppetlabs\-stdlib.git\[aq],
\ \ \ \ :fallback\ =>\ \[aq]4.889.x|foobar|master\[aq]
\f[]
.fi
.PP
In this example g10k tries to use the branches:
.PP
\f[C]4.889.x\f[] \-> \f[C]foobar\f[] \-> \f[C]master\f[]
.PP
Because there are no branches \f[C]4.889.x\f[] or \f[C]foobar\f[].
.PP
All without failing or error messages.
.PP
Tip: You can see which branch was used, when using the
\f[C]\-verbose\f[] parameter:
.IP
.nf
\f[C]
\&./g10k\ \-puppetfile\ \-verbose
2016/11/08\ 14:16:40\ Executing\ git\ \-\-git\-dir\ ./tmp/https\-__github.com_puppetlabs_puppetlabs\-stdlib.git\ remote\ update\ \-\-prune\ took\ 1.05001s
2016/11/08\ 14:16:40\ Executing\ git\ \-\-git\-dir\ ./tmp/https\-__github.com_puppetlabs_puppetlabs\-stdlib.git\ log\ \-n1\ \-\-pretty=format:%H\ master\ took\ 0.00299s
Synced\ ./Puppetfile\ with\ 4\ git\ repositories\ and\ 0\ Forge\ modules\ in\ 1.1s\ with\ git\ (1.1s\ sync,\ I/O\ 0.0s)\ and\ Forge\ (0.0s\ query+download,\ I/O\ 0.0s)
\f[]
.fi
.PP
Now also supports the r10k setting name
\f[C]:default_branch\ =>\ \[aq]master\[aq]\f[] See
https://github.com/xorpaul/g10k/issues/73
.IP \[bu] 2
additional Forge attribute \f[C]:sha256sum\f[]:
.PP
For (some) increased security you can add a SHA256 sum for each Forge
module, which g10k will verify after downloading the respective .tar.gz
file:
.IP
.nf
\f[C]
mod\ \[aq]puppetlabs/ntp\[aq],\ \[aq]6.0.0\[aq],\ :sha256sum\ =>\ \[aq]a988a172a3edde6ac2a26d0e893faa88d37bc47465afc50d55225a036906c944\[aq]
\f[]
.fi
.PP
This does provide a very crude way to detect manipulated Forge modules
and MITM attacks until the Puppetlabs Forge does support some sort of
signing of Forge module releases.
.PP
If the SHA256 sum does not match the expected hash sum, g10k will warn
the user and retry a download until giving up:
.IP
.nf
\f[C]
Resolving\ Forge\ modules\ (0/1)\ \ \ \-\-\-\ [\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-]\ \ \ 0%
WARNING:\ calculated\ sha256sum\ a988a172a3edde6ac2a26d0e893faa88d37bc47465afc50d55225a036906c944\ for\ ./tmp/puppetlabs\-ntp\-6.0.0.tar.gz\ does\ not\ match\ expected\ sha256sum\ a988a172a3edde6ac2a26d0e893faa88d37bc47465afc50d55225a036906c94
Resolving\ Forge\ modules\ (0/1)\ \ \ \-\-\-\ [\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-]\ \ \ 0%
WARNING:\ calculated\ sha256sum\ a988a172a3edde6ac2a26d0e893faa88d37bc47465afc50d55225a036906c944\ for\ ./tmp/puppetlabs\-ntp\-6.0.0.tar.gz\ does\ not\ match\ expected\ sha256sum\ a988a172a3edde6ac2a26d0e893faa88d37bc47465afc50d55225a036906c94
2016/12/08\ 18:05:11\ downloadForgeModule():\ giving\ up\ for\ Puppet\ module\ puppetlabs\-ntp\ version:\ 6.0.0
\f[]
.fi
.PP
(The Forge module retry count in case the Puppetlabs Forge provided MD5
sum, file archive size or SHA256 sum doesn't match defaults to
\f[C]1\f[], but will be user configurable later.)
.IP \[bu] 2
override g10k cache directory with environment variable
.PP
You can use the following environment variable to make g10k use a
different cache directory:
.IP
.nf
\f[C]
g10k_cachedir=/var/tmp\ g10k\ ...
\f[]
.fi
.PP
This will also override the \f[C]\-cachedir\f[] parameter.
.SH ADDITIONAL CONFIG FEATURES
.IP \[bu] 2
you can enforce version numbers of Forge modules in your Puppetfiles
instead of \f[C]:latest\f[] or \f[C]:present\f[] by adding
\f[C]force_forge_versions:\ true\f[] to the g10k config in the specific
resource
.IP
.nf
\f[C]
\-\-\-
:cachedir:\ \[aq]/tmp/g10k\[aq]

sources:
\ \ example:
\ \ \ \ remote:\ \[aq]https://github.com/xorpaul/g10k\-environment.git\[aq]
\ \ \ \ basedir:\ \[aq]/tmp/example/\[aq]
\ \ \ \ force_forge_versions:\ true
\f[]
.fi
.PP
If g10k then encounters \f[C]:latest\f[] or \f[C]:present\f[] for a
Forge module it errors out with:
.IP
.nf
\f[C]
2016/11/15\ 18:45:38\ Error:\ Found\ present\ setting\ for\ forge\ module\ in\ /tmp/example/example_benchmark/Puppetfile\ for\ module\ puppetlabs/concat\ line:\ mod\ \[aq]puppetlabs/concat\[aq]\ and\ force_forge_versions\ is\ set\ to\ true!\ Please\ specify\ a\ version\ (e.g.\ \[aq]2.3.0\[aq])
\f[]
.fi
.IP \[bu] 2
g10k can let you know if your source does not contain the branch you
specified with the \f[C]\-branch\f[] parameter:
.IP
.nf
\f[C]
\-\-\-
:cachedir:\ \[aq]/tmp/g10k\[aq]

sources:
\ \ example:
\ \ \ \ remote:\ \[aq]https://github.com/xorpaul/g10k\-environment.git\[aq]
\ \ \ \ basedir:\ \[aq]/tmp/example/\[aq]
\ \ \ \ warn_if_branch_is_missing:\ true
\f[]
.fi
.PP
If you then call g10k with this config file and the following parameter
\f[C]\-branch\ nonExistingBranch\f[].
You should get:
.IP
.nf
\f[C]
WARNING:\ Couldn\[aq]t\ find\ specified\ branch\ \[aq]nonExistingBranch\[aq]\ anywhere\ in\ source\ \[aq]example\[aq]\ (https://github.com/xorpaul/g10k\-environment.git)
\f[]
.fi
.PP
This can be helpful if you use a dedicated hiera repository/g10k source
and you want to ensure that you always have a matching branch, see
https://github.com/xorpaul/g10k/issues/45
.IP \[bu] 2
By default g10k fails if one of your Puppet environments could not be
completely populated (e.g.\ if one of your Puppet Git module branches
doesn't exist anymore).
You can change this by setting \f[C]ignore_unreachable_modules\f[] to
true in your g10k config:
.IP
.nf
\f[C]
\-\-\-
:cachedir:\ \[aq]/tmp/g10k\[aq]
ignore_unreachable_modules:\ true

sources:
\ \ example:
\ \ \ \ remote:\ \[aq]https://github.com/xorpaul/g10k\-failing\-env.git\[aq]
\ \ \ \ basedir:\ \[aq]/tmp/failing/\[aq]
\f[]
.fi
.PP
If you then call g10k with this config file and \f[C]debug\f[] verbosity
level, you should get:
.IP
.nf
\f[C]
DEBUG:\ Failed\ to\ populate\ module\ /tmp/failing/master/modules//sensu/\ but\ ignore\-unreachable\ is\ set.\ Continuing...
\f[]
.fi
.PP
See https://github.com/xorpaul/g10k/issues/57 for details.
.IP \[bu] 2
abort g10k run if source repository is unreachable
.IP
.nf
\f[C]
\-\-\-
:cachedir:\ \[aq]/tmp/g10k\[aq]

sources:
\ \ example:
\ \ \ \ remote:\ \[aq]git://github.com/xorpaul/g10k\-environment\-unavailable.git\[aq]
\ \ \ \ basedir:\ \[aq]/tmp/example/\[aq]
\ \ \ \ exit_if_unreachable:\ true
\f[]
.fi
.PP
If you then call g10k with this config file.
You should get:
.IP
.nf
\f[C]
WARN:\ git\ repository\ git://github.com/xorpaul/g10k\-environment\-unavailable.git\ does\ not\ exist\ or\ is\ unreachable\ at\ this\ moment!
WARNING:\ Could\ not\ resolve\ git\ repository\ in\ source\ \[aq]example\[aq]\ (git://github.com/xorpaul/g10k\-environment\-unavailable.git)
\f[]
.fi
.PP
with an exit code 1
.IP \[bu] 2
g10k can use the cached version of Forge and git modules if their
sources are currently not available:
.IP
.nf
\f[C]
\-\-\-
:cachedir:\ \[aq]/tmp/g10k\[aq]
use_cache_fallback:\ true

sources:
\ \ example:
\ \ \ \ remote:\ \[aq]git://github.com/xorpaul/g10k\-environment\-unavailable.git\[aq]
\ \ \ \ basedir:\ \[aq]/tmp/example/\[aq]
\f[]
.fi
.PP
If you then call g10k with this config file and your github.com
repository is unavailable your g10k run tries to find a suitable cached
version of your modules:
.IP
.nf
\f[C]
WARN:\ git\ repository\ https://github.com/puppetlabs/puppetlabs\-firewall.git\ does\ not\ exist\ or\ is\ unreachable\ at\ this\ moment!
WARN:\ Trying\ to\ use\ cache\ for\ https://github.com/puppetlabs/puppetlabs\-firewall.git\ git\ repository
\f[]
.fi
.PP
if your g10k did manage to at least once cache this git repository.
.PP
If there is no useable cache available your g10k run still fails.
.IP \[bu] 2
You can let g10k retry to git clone or update the local repository if it
failed before and was left in a corrupted state:
.IP
.nf
\f[C]
\-\-\-
:cachedir:\ \[aq]/tmp/g10k\[aq]
retry_git_commands:\ true

sources:
\ \ example:
\ \ \ \ remote:\ \[aq]https://github.com/xorpaul/g10k\-environment.git\[aq]
\ \ \ \ basedir:\ \[aq]/tmp/example/\[aq]
\f[]
.fi
.PP
If you then call g10k with this config file and have a corrupted local
Git repository, g10k deletes the local cache and retries the Git clone
command once:
.IP
.nf
\f[C]
WARN:\ git\ command\ failed:\ git\ \-\-git\-dir\ /tmp/g10k/modules/https\-__github.com_puppetlabs_puppetlabs\-firewall.git\ remote\ update\ \-\-prune\ deleting\ local\ cached\ repository\ and\ retrying...
\f[]
.fi
.PP
See https://github.com/xorpaul/g10k/issues/76 for details.
.IP \[bu] 2
Autocorrecting Puppet environment names
.PP
Like in r10k
(https://github.com/puppetlabs/r10k/blob/master/doc/dynamic\-environments/git\-environments.mkd#invalid_branches)
for each source in your g10k config you can set the attribute
\f[C]invalid_branches\f[] with the following values:
.IP \[bu] 2
\f[C]correct_and_warn\f[]: Non\-word characters will be replaced with
underscores and a warning will be emitted.
.IP \[bu] 2
\f[C]correct\f[]: Non\-word characters will silently be replaced with
underscores.
.IP \[bu] 2
\f[C]error\f[]: Branches with non\-word characters will be ignored and
an error will be emitted.
.PP
The default value is to leave the environment unchanged, which differs
from the r10k default!
.PP
Example:
.IP
.nf
\f[C]
\-\-\-
:cachedir:\ \[aq]/tmp/g10k\[aq]

sources:
\ \ example:
\ \ \ \ remote:\ \[aq]https://github.com/xorpaul/g10k\-environment.git\[aq]
\ \ \ \ basedir:\ \[aq]/tmp/example/\[aq]
\ \ \ \ invalid_branches:\ \[aq]correct\[aq]
\f[]
.fi
.PP
If you then call g10k with this config file and have a branch named
something like \f[C]single_autocorrect\-%\-fooo\f[] it will be renamed
to \f[C]single_autocorrect___fooo\f[]
.PP
See https://github.com/xorpaul/g10k/issues/81 for details.
.SH COPYRIGHT
.PP
Copyright (c) 2019 Jack Henschel
.SH AUTHOR
.PP
This manual page is based on the g10k documentation.
It was created by Jack Henschel <jackdev@mailbox.org> for the Debian
GNU/Linux system, but may be used by others.
.SH SEE ALSO
.PP
\f[B]r10k(1)\f[]