r10k 2.3.1 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e63992636be8dd543768f160bad72b447b3fd892
-  data.tar.gz: 8929577087203a2d4a72a63b0ff6d5da96ff1312
+  metadata.gz: 6a09bf6960068b3be8375f1f66009b753ef64644
+  data.tar.gz: b9ed03e076ea4e74cbc77e25d913dfc9765f7877
 SHA512:
-  metadata.gz: 32f6becccbae5df50626fd9133cb6f210a2d95fffce5ad69a5d534c19eceb59bee6b936f4783f4be0c3451adf3613557a4eca608255f5bff61e2c55f34282817
-  data.tar.gz: 67885326574423b9d78386e4f3045f87ba922efcf284bd2959d49a4c89ae01ba3d884055fdcbd0b121c14f1f387d2b53b49899c7ff7a609ec8206b5a47a64de7
+  metadata.gz: 88988343617f2f811b66dd58b4580d3e05c8167545635d6ba78ccfbc965d70a64a736485f75380e2f8e0bb0d1f63fcff5a72a3b3dec55e78786fe60d4e52062a
+  data.tar.gz: c8363914b46a62567f1571c6575ab2094664c849787f57ece270083f8729babda5422fcc614fc02b497f1d0c45a56505df54373f64b4c1f426549b26db5e83e7

data/.gitignore

@@ -4,3 +4,4 @@ Gemfile.lock
 .bundle
 bundle
 coverage
+locales/r10k.pot

data/CHANGELOG.mkd

@@ -1,24 +1,51 @@
 CHANGELOG
 =========
 
-2.3.1
+2.4.0
 -----
 
-2016/11/30
+2016/08/10
 
-(RK-78) Use :prune option for #fetch in Rugged::BareRepository
+### New Features
+
+(RK-222) New "install\_path" option for Git/SVN content.
+
+This feature allows you to specify where inside an environment each item from the
+Puppetfile should be installed to. See the [Puppetfile documentation](https://github.com/puppetlabs/r10k/blob/master/doc/puppetfile.mkd#per-item-install-path) for details.
+
+(RK-246) New "environment" level purging and configurable purge levels.
+
+You can now configure how r10k purges unmanaged content after a deployment. The
+default behavior should be unchanged but there is a new "purge\_levels" configuration
+option that can be used to enable new behavior or de-activate certain existing 
+behaviors. See the relevant [configration documentation](https://github.com/puppetlabs/r10k/blob/master/doc/dynamic-environments/configuration.mkd#purge_levels) for more details.
+
+(RK-223) Ability to track control repo branch from content declarations.
+
+Puppetfile content sourced from Git can now be configured to attempt to track the branch
+name of the control repo branch being deployed. For example, if r10k is deploying
+the 'production' branch of your control repo, it will try to also deploy the
+'production' branch of a given Puppetfile content repo. See the [documentation](https://github.com/puppetlabs/r10k/blob/master/doc/puppetfile.mkd#control-repo-branch-tracking)
+for more details.
+
+### Internationalization
+
+All user-facing strings generated by r10k have been externalized to enable future
+iternationalization (i18n) and localization work.
+
+### Changed
+
+(RK-258) Symlinks inside of Forge modules will no longer cause r10k to exit non-zero.
+This situation used to raise an error but will now generate a WARN level log message
+instead.
+
+### Bug Fixes
 
-Versions of the "rugged" gem prior to 0.24.0 lacked the ability to automatically
-"prune" branches from a local repo that no longer existed in the matching remote
-repo after a fetch. To work around this issue, r10k included code that would
-manually remove/recreate branches during a fetch. Since "rugged" 0.24.0 is now
-widely available, r10k has been updated to use the built-in "prune" option
-during a fetch and the workaround code has been removed.
+(#616) Ensure that Forge module version strings are valid semantic versions. (Special
+thanks to Patrick Robinson (patrobinson) for the fix.)
 
-NOTE: If you use the "rugged" gem with r10k, you will need to manually upgrade
-it to a version >= 0.24.0 to take advantage of the new functionality. If you
-are using a "rugged" version less than 0.24.0, r10k will now issue a warning
-every time it fetches from a remote git repository.
+(#622) Fix typos in workflow docs. (Special thanks to Yury Frolov (mrdracon) for the
+fix.)
 
 2.3.0
 -----

data/Gemfile

@@ -1,5 +1,4 @@
-source 'https://rubygems.org'
-
+source ENV['GEM_SOURCE'] || 'https://rubygems.org'
 gemspec
 
 group :extra do

data/README.mkd

@@ -85,6 +85,22 @@ information see the topic specific documentation:
 
 For more general questions, see the [FAQ](doc/faq.mkd).
 
+Development
+-----------
+
+### i18n
+
+R10k has now had all user-facing strings in error messages and log messages
+externalized. When adding new error or log messages please follow the
+instructions for [writing translatable code](https://github.com/puppetlabs/gettext-setup-gem#writing-translatable-code).
+
+### l10n
+
+When localizing the strings found in R10k, follow the prescribed
+[translation workflow](https://github.com/puppetlabs/gettext-setup-gem#translation-workflow).
+The workflow describes the rake tasks provided to generate the .po files for
+each locale.
+
 Getting help
 ------------
 
@@ -103,3 +119,12 @@ Contributors
 ------------
 
 Please see the CHANGELOG for a listing of the (very awesome) contributors.
+
+## Maintenance
+
+Maintainers:
+
+* Jesse Scott, jesse@puppet.com
+* Anderson Mills, anderson@puppet.com
+
+Tickets: File at https://tickets.puppet.com/browse/RK

data/Rakefile

@@ -0,0 +1,3 @@
+spec = Gem::Specification.find_by_name 'gettext-setup'
+load "#{spec.gem_dir}/lib/tasks/gettext.rake"
+GettextSetup.initialize(File.absolute_path('locales', File.dirname(__FILE__)))

data/doc/dynamic-environments/configuration.mkd

@@ -200,12 +200,92 @@ sources:
 
 ### deploy
 
-The `deploy` setting is a new top level setting for controlling how r10k deploys
+The `deploy` setting is a top level setting for controlling how r10k deploys
 behave. At this point only new settings are included under this setting, but in
 the long term the current top level deploy settings will be moved under
 `deploy`.
 
-#### write_lock
+#### purge\_levels
+
+The `purge_levels` setting controls how aggressively r10k will purge unmanaged
+content during a deployment. Given value must be a list of strings indicating at
+what levels unmanaged content should be purged. The valid string options for the
+list are 'deployment', 'environment', and 'puppetfile'.
+
+```yaml
+---
+deploy:
+  purge_levels: [ 'deployment', 'environment', 'puppetfile' ]
+```
+
+This setting currently only impacts the "deploy environment" action.
+
+The default value is `['deployment', 'puppetfile']` to maintain parity with
+existing behavior before this setting was added.
+
+The effect of enabling the various purge levels is as follows:
+
+##### deployment
+
+After each deploy, in the configured basedir, r10k will recursively remove any
+content found which is not managed by one of the sources declared in the r10k.yaml
+configuration. Note that disabling this level of purging may cause the number of
+deployed environments to grow without bound; deleting branches from a control
+repo would no longer cause the matching environment to be purged.
+
+##### environment
+
+After a given environment is deployed, r10k will recursively remove any content
+found which is neither committed to the control repo branch that maps to that
+environment, nor declared in a Puppetfile committed to that branch.
+
+Enabling this purge level will cause r10k to load and parse the Puppetfile for
+the environment even without the `--puppetfile` flag being set. However,
+Puppetfile content will still only be deployed if the environment is new or
+the `--puppetfile` flag is set. Additionally, no environment-level content
+will be purged if a Puppetfile content deploy was triggered but an error was
+encountered.
+
+Note that the .r10k-deploy.json file is exempt from this purging.
+
+##### puppetfile
+
+After Puppetfile content for a given environment is deployed, r10k will
+recursively remove any content found in a directory managed by the Puppetfile
+which is not also declared in that Puppetfile. Directories considered to be
+managed by a Puppetfile include the configured `moduledir` (which defaults to
+"modules") as well as alternate directories specified as an `install\_path`
+option to any Puppetfile content declarations.
+
+#### purge\_whitelist
+
+The `purge_whitelist` setting exempts the specified filename patterns from
+being purged. This setting is currently only considered during `environment`
+level purging. (See above.) Given value must be a list of shell style filename
+patterns in string format.
+
+See the Ruby [documentation for the `fnmatch` method](http://ruby-doc.org/core-2.2.0/File.html#method-c-fnmatch)
+for more details on valid patterns. Note that the `FNM_PATHNAME` and
+`FNM_DOTMATCH` flags are in effect when r10k considers the whitelist.
+
+Patterns are relative to the root of the environment being purged and *do
+not match recursively* by default. For example, a whitelist value of
+`*myfile*` would only preserve a matching file at the root of the
+environment. To preserve the file throughout the deployed environment,
+a recursive pattern such as `**/*myfile*` would be required.
+
+Files matching a whitelist pattern may still be removed if they exist in
+a folder that is otherwise subject to purging. In this case, an additional
+whitelist rule to preserve the containing folder is required.
+
+```yaml
+---
+deploy:
+  purge_whitelist: [ 'custom.json', '**/*.xpp' ]
+```
+
+
+#### write\_lock
 
 The `write_lock` setting allows administrators to temporarily disallow r10k code
 deploys without having to remove the r10k configuration entirely. This can be
@@ -214,10 +294,8 @@ with a common set of code that may be touched by multiple r10k configurations.
 
 ```yaml
 ---
-
 deploy:
   write_lock: "Deploying code is disallowed until the next maintenance window (2038-01-19)"
-
 ```
 
 Source options
@@ -353,16 +431,15 @@ must override the `prefix` so environment folders line up in both directories:
 
 ```yaml
 ---
-  sources:
-    main:
-      app1_data:
-        remote: 'git://git-server.site/my-org/app1-hieradata'
-        basedir: '/etc/puppet/hieradata'
-        prefix: "app1"
-      app1_modules:
-        remote: 'git://git-server.site/my-org/app1-puppet-modules'
-        basedir: '/etc/puppet/environments'
-        prefix: "app1"
+sources:
+  app1_data:
+    remote: 'git://git-server.site/my-org/app1-hieradata'
+    basedir: '/etc/puppet/hieradata'
+    prefix: "app1"
+  app1_modules:
+    remote: 'git://git-server.site/my-org/app1-puppet-modules'
+    basedir: '/etc/puppet/environments'
+    prefix: "app1"
 ```
 
 

data/doc/dynamic-environments/workflow-guide.mkd

@@ -213,13 +213,13 @@ git merge feature
 git push origin master
 ```
 
-In the Control repo, check out master. Do NOT merge the feature branch as it
+In the Control repo, check out production. Do NOT merge the feature branch as it
 now references the incorrect branch for each git repo, and no other changes
 were made (unlike a new module, where a new repo is referenced).
 
 ```
 # Control repo
-git checkout master
+git checkout production
 ```
 
 ### Cleanup feature branches
@@ -234,7 +234,7 @@ git branch -D repo
 git push origin :repo
 ```
 
-Redeploy with r10k on the master and ensure there are no errors. The *feature*
+Redeploy with r10k on your Puppet Master and ensure there are no errors. The *feature*
 dynamic environment should no longer exist at `$environmentpath/feature`.
 
 ```r10k deploy environment -p```

data/doc/puppetfile.mkd

@@ -52,8 +52,7 @@ handles modules.
 
 The `forge` setting specifies which server that Forge based modules are fetched
 from. This is currently a noop and is provided for compatibility with
-librarian-puppet, but will be made functional in a future version. See
-[GH-106](https://github.com/adrienthebo/r10k/issues/106) for more information.
+librarian-puppet.
 
 ### moduledir
 
@@ -88,7 +87,25 @@ Module types
 ------------
 
 r10k can install Puppet modules from a number of different sources. Right now
-modules can be installed via Git, SVN, and from the Puppet Forge.
+modules can be installed from the Puppet Forge, Git, or SVN.
+
+### Puppet Forge
+
+Modules can be installed from the Puppet Forge.
+
+If no version is specified the latest version available at the time will be
+installed, and will be kept at that version.
+
+    mod 'puppetlabs/apache'
+
+If a version is specified then that version will be installed.
+
+    mod 'puppetlabs/apache', '0.10.0'
+
+If the version is set to :latest then the module will be always updated to the
+latest version available.
+
+    mod 'puppetlabs/apache', :latest
 
 ### Git
 
@@ -105,52 +122,68 @@ given object is a tag or commit and can do some optimizations around fetching
 the object. If the tag or commit is already available r10k will skip network
 operations when updating the repo, which can speed up install times.
 
-Module versions can also be specified using `:branch`. This behaves similarly to
-`:ref`, and is mainly useful for clarity.
+Module versions can also be specified using `:branch` to track a specific
+branch reference.
 
 #### Examples
 
-    # Install puppetlabs/apache and keep it up to date with 'master'
-    mod 'apache',
-      :git => 'https://github.com/puppetlabs/puppetlabs-apache'
-
-    # Install puppetlabs/apache and track the 'docs_experiment' branch
-    mod 'apache',
-      :git => 'https://github.com/puppetlabs/puppetlabs-apache',
-      :ref => 'docs_experiment'
-
-    # Install puppetlabs/apache and pin to the '0.9.0' tag
-    mod 'apache',
-      :git => 'https://github.com/puppetlabs/puppetlabs-apache',
-      :tag => '0.9.0'
-
-    # Install puppetlabs/apache and pin to the '83401079' commit
-    mod 'apache',
-      :git    => 'https://github.com/puppetlabs/puppetlabs-apache',
-      :commit => '83401079053dca11d61945bd9beef9ecf7576cbf'
-
-    # Install puppetlabs/apache and track the 'docs_experiment' branch
-    mod 'apache',
-      :git    => 'https://github.com/puppetlabs/puppetlabs-apache',
-      :branch => 'docs_experiment'
+```ruby
+# Install puppetlabs/apache and keep it up to date with 'master'
+mod 'apache',
+  :git => 'https://github.com/puppetlabs/puppetlabs-apache'
+
+# Install puppetlabs/apache and track the 'docs_experiment' branch
+mod 'apache',
+  :git => 'https://github.com/puppetlabs/puppetlabs-apache',
+  :ref => 'docs_experiment'
+
+# Install puppetlabs/apache and pin to the '0.9.0' tag
+mod 'apache',
+  :git => 'https://github.com/puppetlabs/puppetlabs-apache',
+  :tag => '0.9.0'
+
+# Install puppetlabs/apache and pin to the '83401079' commit
+mod 'apache',
+  :git    => 'https://github.com/puppetlabs/puppetlabs-apache',
+  :commit => '83401079053dca11d61945bd9beef9ecf7576cbf'
+
+# Install puppetlabs/apache and track the 'docs_experiment' branch
+mod 'apache',
+  :git    => 'https://github.com/puppetlabs/puppetlabs-apache',
+  :branch => 'docs_experiment'
+```
 
-### Forge
+#### Control Repo Branch Tracking
 
-Modules can be installed using the Puppet module tool.
+Since r10k 2.4.0, the `:branch` option can be set to the special value
+`:control_branch` to indicate that the content should track a branch
+reference matching the containing control repo branch. For example, if a
+Puppetfile containing a Git content declaration is in the "testing" branch
+of a control repo, a setting of `:control_branch` will attempt to deploy that
+content from a "testing" branch of the content repo.
 
-If no version is specified the latest version available at the time will be
-installed, and will be kept at that version.
+Additionally, you can specify a `:default_branch` option which is the branch
+reference that content will be deployed from if the the given `:ref`, `:tag`,
+`:commit`, or `:branch` option cannot be resolved and deployed. If the desired
+content cannot be resolved and no default branch is given, or if the default
+branch can also not be resolved, an error will be logged and the content will
+not be deployed or updated.
 
-    mod 'puppetlabs/apache'
-
-If a version is specified then that version will be installed.
-
-    mod 'puppetlabs/apache', '0.10.0'
+#### :control\_branch Examples
 
-If the version is set to :latest then the module will be always updated to the
-latest version available.
+```ruby
+# Deploy content from branch matching control repo branch.
+mod 'hieradata',
+  :git => 'git@git.example.com:organization/hieradata.git',
+  :branch => :control_branch
+
+# Track control branch and fall-back to master if no matching branch.
+mod 'hieradata',
+  :git => 'git@git.example.com:organization/hieradata.git',
+  :branch => :control_branch,
+  :default_branch => 'master'
+```
 
-    mod 'puppetlabs/apache', :latest
 
 ### SVN
 
@@ -257,6 +290,22 @@ module.
 For more information see the [FAQ entry](faq.mkd#how-do-i-prevent-r10k-from-removing-modules-in-the-modules-directory-of-my-git-repository)
 on managing internal and external modules in the same directory.
 
+### Per-Item Install Path
+
+Git and SVN content types support installing into an alternate path without changing
+the value of moduledir by specifying an 'install\_path' option:
+
+```
+# This will install the 'apache' module into 'external/apache'.
+mod 'apache',
+  :git => 'git@github.com:puppetlabs/puppetlabs-apache.git',
+  :install_path => 'external'
+```
+
+The given 'install\_path' can be an absolute path or a path relative to the base of
+the environment. Note that r10k will exit with an error if you attempt to set the
+'path' option to a directory outside of the environment.
+
 ## Environment variables
 
 It is possible to set an alternate name/location for your `Puppetfile` and