Forge Home


Manipulate existing or new YAML files.


168,666 latest version

3.8 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 0.1.0 (latest)
released Jun 17th 2016
This version is compatible with:
  • Puppet Enterprise >= 3.3.0
  • Puppet >= 3.3.0 < 5.0.0

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'cataphract-yaml_settings', '0.1.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add cataphract-yaml_settings
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install cataphract-yaml_settings --version 0.1.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.



cataphract/yaml_settings — version 0.1.0 Jun 17th 2016


Table of Contents

  1. Description
  2. Setup - The basics of getting started with yaml_settings
  3. Usage - Configuration options and additional functionality
  4. Creating files with only the keys specified
  5. Reference
  6. Limitations - OS compatibility, etc.
  7. Development - Guide for contributing to the module


This module introduces a native type (yaml_settings) that allows for modifying yaml files. It is similar to reidmv/yamlfile, with the following improvements:

  • forward slashes are allowed in key names,
  • portions of the key can be symbols,
  • it is possible to use a separate file as a template.


The setting pluginsync needs to be enabled for at least one run so that the ruby files of the native type are synced to the agents.

Note that pluginsync is deprecated in Puppet 4, which defaults to enabling pluginsync when applying a non-cached catalog. See PUP-5708.


This modules provides only one resource type: yaml_settings. Example usage:

yaml_settings { '/tmp/foo.yaml':
    values => {
        'uuu/vvv/www' => { 'yyy' => 'zzz' },

This will create the file /tmp/foo.yaml (or modify it, if it already exists, to add/change the value of uuu/vvv/www):

        yyy: zzz

If a key (portion) should include a /, then you must quote that key with a single quote ('). If you need then a single quote, then you must double it. If you prepend a colon (:) to the opening single quote, you will be referring to a symbol key. Example:

yaml_settings { '/tmp/foo.yaml':
    values => {
        "uuu/'a''b'/:'www'" => { 'yyy' => 'zzz' },

Will result in:

      !ruby/sym www: 
        yyy: zzz

Beware that Puppet 4 behaves differently with respect to number literals. While Puppet 3 converts these to strings, Puppet 4 will not. So in Puppet 3, this example:

yaml_settings { '/tmp/foo.yaml':
    values => { 'a' => 1 }

will create

  a: "1"

while in Puppet 4:

a: 1

Because the Puppet 4 behavior makes more sense (notice that other types like booleans and the undef symbol are also not converted under Puppet 3), this module doesn't attempt to have Puppet 4 behave like Puppet 3 by converting the numbers to strings.

Creating files with only the keys specified

This is not the main use case for this module, as this can be achieved without dependencies by using inline_template:

$values = {
    'uuu' => { 'vvv' => { 'www' => 'yyy' } },
file { '/tmp/foo.yaml':
    content => inline_template('<%= require "yaml"; @values.to_yaml %>'),

will result in:

      www: yyy

Nevertheless, you can still use this module, if you provide an empty file as a template:

yaml_settings { '/tmp/foo.yaml':
    source => '/dev/null',
    values => { 'a' => 'b', }


This is the full list of parameters:

yaml_settings { 'my settings':
  target           => '/tmp/foo.yaml', # defaults to title
  source           => '/tmp/source.yaml',
  allow_new_values => true,
  allow_new_file   => true,
  user             => 'root', # user used to read/write file,
                              # doesn't change ownership like 'file'!

It autorequires a file resource with a title (not path!) equal to the source parameter, if present in the catalog.

For more information, see the type file source file.


There is no support yet for removing keys, though you can set them to nil.


Make sure that you run rubocop and rake test before committing.