Configuring purge levels
The purge_levels setting, within the deploy parameter, controls which unmanaged content r10k purges after a deployment.
The purge_levels setting accepts an array of strings
specifying what content r10k purges during code
deployments. You can specify one or more of deployment,
environment, puppetfile, and
purge_allowlist.
For example:
deploy: purge_levels: [ 'deployment', 'environment', 'puppetfile' ]
The default setting is [ 'deployment', 'puppetfile' ].
Each purge level option is explained below.
deployment
After each deployment, in the configured basedir, r10k recursively removes content that is not managed by any of the sources
declared in the remote or sources parameters.
deployment from purge_levels allows the number of deployed environments to
grow without bound, because deleting branches from a control repo would no longer cause
the matching environment to be purged automatically.environment
After a given environment is deployed, r10k recursively removes content that is:
- Not committed to the control repo branch that maps to that environment.
- Not declared in a Puppetfile committed to that branch.
With the environment purge level, r10k loads and parses the Puppetfile for the environment, even if the
--modules flag is not set, so that r10k can check whether content is declared in the Puppetfile. However, r10k doesn't actually deploy Puppetfile content unless the
environment is new or the --modules flag is set.
If r10k encounters an error while evaluating the Puppetfile or deploying its contents, no environment-level content is purged.
puppetfile
After Puppetfile content for a given environment is deployed, r10k recursively removes content in any directory managed by the Puppetfile, if that content is not declared in the Puppetfile.
Directories managed by a Puppetfile include
the configured moduledir (which defaults to modules), as well as any alternate directories specified as an
install_path option to any Puppetfile content declarations.
purge_allowlist
The purge_allowlist setting exempts the specified filename patterns
from being purged. This setting affects only environment purging. The
value for this setting must be a list of shell-style filename patterns formatted as
strings.
See the Ruby documentation about the fnmatch method
for information on valid patterns. Both the FNM_PATHNAME and
FNM_DOTMATCH flags are in effect when r10k considers the allowlist.
Patterns are relative to the root of the environment being purged and, by default, do
not match recursively. For example, an allowlist value of
*myfile* preserves only matching files at the root of the
environment. To preserve matching files throughout the deployed environment, you need to
use a recursive pattern such as **/*myfile*.
Files matching an allowlist pattern might still get removed if they exist in a folder that is otherwise subject to purging. In this case, use an additional allowlist rule to preserve the containing folder, for example:
deploy: purge_allowlist: [ 'custom.json', '**/*.xpp' ]
