Adoptable Cookbooks List

Looking for a cookbook to adopt? You can now see a list of cookbooks available for adoption!
List of Adoptable Cookbooks

Supermarket Belongs to the Community

Supermarket belongs to the community. While Chef has the responsibility to keep it running and be stewards of its functionality, what it does and how it works is driven by the community. The chef/supermarket repository will continue to be where development of the Supermarket application takes place. Come be part of shaping the direction of Supermarket by opening issues and pull requests or by joining us on the Chef Mailing List.

Select Badges

Select Supported Platforms

RSS

resource_masher (2) Versions 0.10.0

Extend Resources (and LWRPs) with greater ability to export their attributes, including validation, merged default values, and formatting.

Berkshelf/Librarian
Policyfile
Knife
cookbook 'resource_masher', '~> 0.10.0'
cookbook 'resource_masher', '~> 0.10.0', :supermarket
knife cookbook site install resource_masher
knife cookbook site download resource_masher
README
Dependencies
Quality

Resource Masher - Chef Cookbook

This cookbook provides a library which extends Chef Resource objects with new abilities to export their attribute values, including default values, and with the added functionality of a Mash wrapper.

There are no sepcial requirements, it extends all resources generically.

Overview

Limitations of Chef default functionality

By default Chef provides a .to_hash method on Resources, which exports a Hash of its attributes; but its implimentation is counter-intuitive.

If an LWRP supplies default values, and they are not overwritten, those keys/values are not included in Chef's .to_hash export. By design the Hash behaves more like a serialization.

Usage

This cookbook adds the methods .attribute_mash and .attribute_mash_formatted to Chef resources.

The following example illustrates its usage in an LWRP provider. Please note:

  • You do not need to be within a provider to invoke these functions.
  • Only your cookbook needs to depend on the resource_masher, target resources require no modifications.

LWRP Example

Given the following sample LWRP resource describing a plugin:

actions :install, :remove
default_action :install

attribute :plugin_name, :name_attribute => true
attribute :vendor, :required => true
attribute :branch, :default => 'stable'
attribute :install_path, :default => '/opt/%{vendor}/%{plugin_name}'

And the following invocation from a recipie:

my_plugin_lwrp "sample_plugin" do
  action :install
  vendor "doe.corp"
end

Let's look at how the resource_masher helps in the provider:

action :install do

   #
   # Let's export the new_resource a few different ways.
   # Perhaps for use with a Template's variables.
   #

   # Export to Hash using Chef's default method.
   exp_chef     = new_resource.to_hash

   # Export to Mash using 'attribute_mash'.
   exp_mash     = new_resource.attribute_mash

   # Export to Mash using 'attribute_mash_formatted'.
   exp_mash_fmt = new_resource.attribute_mash_formatted

   # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   # PROBLEM: Chef's Hash is incomplete.
   #
   # exp_chef is equal {
   #   :plugin_name => "sample_plugin",
   #   :vendor => "doe.corp"
   # }
   #
   # !!! It's missing :branch and :install_path, which were defaults. !!!

   # INCONVENIENCE: Chef's Hash is just a Hash
   #
   # You can only do this:
   #   exp_chef[:plugin_name]
   #
   # Not:
   #   exp_chef["plugin_name"]
   #   exp_chef.plugin_name

   # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   # SOLUTION Part-1: Complete output (optionally formatted)
   #
   # exp_mash is equal {
   #  :plugin_name => "sample_plugin",
   #  :vendor => "doe.corp",
   #  :branch => "stable",
   #  :install_path => "/opt/%{vendor}/%{plugin_name}"
   # }
   #
   # With the formatted version, the :install_path is different...
   #   exp_mash_fmt[:install_path] is equal "/opt/doe.corp/sample_plugin"
   #
   # !!! The string formatters were automatically back-filled !!!

   # SOLUTION Part-2: Our Mash, is a Mash, of course, of course
   #
   # You can do all of these now:
   #   exp_mash[:plugin_name]
   #   exp_mash["plugin_name"]
   #   exp_mash.plugin_name
   #   exp_mash.symbolize_keys  # returns normal (complete) Hash

end

Formatting

The .attribute_mash_formatted method replaces any tokens in String values with matching values defined on the resource.

From the above example:

:install_path => "/opt/%{vendor}/%{plugin_name}" becomes /opt/doe.corp/sample_plugin

When using the formatting feature, please note the following:

  • The tokens use percent signs, not hash-marks. This is standard Ruby syntax for such operations. See here for more info
  • If the replacement requires recursion, there is a depth limit of three(3) to safe-guard infinate loops.
  • An undefined token will generate an exception, but you can supply extra data to avoid this.

You can supply additional data to inject with the formatting. This data acts as additional defaults, any matching attributes on the resource itself will override the provided data.

extra_data = { :alpha => 'AAA', :beta => 'BBB' }
export = new_resource.attribute_mash_formatted(extra_data)

Validation

The ResourceMash returned has an added .validate method which incorporates the standard Chef validation tools for ease of use. Additionally the values returned from the validation replace any existing values in the Mash (if different) ... permitting the use of the :default validation option as well.

An ideal use case is when generic super-class resources are distilled into more specific sub-classes. Such as how the stock 'remote_file' resource is an extension of the 'file' resource. The ResourceMash validation method can be a quick way to transform/validate the resource data as needed.

For more information on the validation syntax, see the Chef docs linked here.

Example usage:

export = new_resource.attribute_mash
export.validate({
  :alpha   => { :equal_to => 'AAA' },
  :beta    => { :kind_of => String },
  :charlie => { :default => 'CCC' }
})

Bugs / Docs / Updates

Please see: code.binbab.org

Versioning

The cookbook uses semantic versioning. Releases will be numbered in the following format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

  • Breaking backward compatibility bumps the major (and resets the minor and patch)
  • New additions without breaking backward compatibility bumps the minor (and resets the patch)
  • Bug fixes and misc changes bumps the patch

For more information on SemVer, visit http://semver.org/.

Authors and License

  • Author:: BinaryBabel OSS (projects@binarybabel.org)
  • Copyright:: 2013 sha1(OWNER) = df334a7237f10846a0ca302bd323e35ee1463931
  • License:: Apache License, Version 2.0

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Collaborator Number Metric
            

0.10.0 failed this metric

Failure: Cookbook has 0 collaborators. A cookbook must have at least 2 collaborators to pass this metric.

Contributing File Metric
            

0.10.0 failed this metric

Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a CONTRIBUTING.md file

Foodcritic Metric
            

0.10.0 failed this metric

FC064: Ensure issues_url is set in metadata: resource_masher/metadata.rb:1
FC065: Ensure source_url is set in metadata: resource_masher/metadata.rb:1
FC066: Ensure chef_version is set in metadata: resource_masher/metadata.rb:1
FC067: Ensure at least one platform supported in metadata: resource_masher/metadata.rb:1
FC069: Ensure standardized license defined in metadata: resource_masher/metadata.rb:1
Run with Foodcritic Version 11.1.0 with tags metadata,correctness ~FC031 ~FC045 and failure tags any

License Metric
            

0.10.0 failed this metric

resource_masher does not have a valid open source license.
Acceptable licenses include Apache-2.0, apachev2, Apache 2.0, MIT, mit, GPL-2.0, gplv2, GNU Public License 2.0, GPL-3.0, gplv3, GNU Public License 3.0.

No Binaries Metric
            

0.10.0 passed this metric

Publish Metric
            

0.10.0 passed this metric

Supported Platforms Metric
            

0.10.0 failed this metric

resource_masher should declare what platform(s) it supports.

Testing File Metric
            

0.10.0 failed this metric

Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a TESTING.md file

Version Tag Metric
            

0.10.0 failed this metric

Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must include a tag that matches this cookbook version number