cookbook 'chef-sugar', '= 3.3.0'
The chef-sugar cookbook has been deprecated
Author provided reason for deprecation:
The chef-sugar cookbook has been deprecated and is no longer being maintained by its authors. Use of the chef-sugar cookbook is no longer recommended.
chef-sugar
(39) Versions
3.3.0
-
Follow44
Installs chef-sugar. Please see the chef-sugar Ruby gem for more information.
cookbook 'chef-sugar', '= 3.3.0', :supermarket
knife supermarket install chef-sugar
knife supermarket download chef-sugar
Chef Sugar
Chef Sugar is a Gem & Chef Recipe that includes series of helpful sugar of the Chef core and other resources to make a cleaner, more lean recipe DSL, enforce DRY principles, and make writing Chef recipes an awesome experience!
Installation
If you want to develop/hack on chef-sugar, please see the Contributing.md.
If you are using Berkshelf, add chef-sugar
to your Berksfile
:
cookbook 'chef-sugar'
Otherwise, you can use knife
or download the tarball directly from the community site:
knife cookbook site install chef-sugar
Usage
In order to use Chef Sugar in your Chef Recipes, you'll first need to include it:
include_recipe 'chef-sugar::default'
Alternatively you can put it in a base role or recipe and it will be included subsequently.
Requiring the Chef Sugar Gem will automatically extend the Recipe DSL, Chef::Resource
, and Chef::Provider
with helpful convenience methods.
Module Method
If you are working outside of the Recipe DSL, you can use the module methods instead of the Recipe DSL. In general, the module methods have the same name as their Recipe-DSL counterparts, but require the node object as a parameter. For example:
In a Recipe:
# cookbook/recipes/default.rb do_something if windows?
In a Library as a singleton:
# cookbook/libraries/default.rb def only_on_windows(&block) yield if Chef::Sugar::PlatformFamily.windows?(@node) end
In a Library as a Mixin:
# cookbook/libraries/default.rb include Chef::Sugar::PlatformFamily def only_on_windows(&block) yield if windows?(@node) end
API
Note: For the most extensive API documentation, please see the YARD documentation.
Architecture
Note: Some of the architecture commands begin with an underscore (_
) because Ruby does not permit methods to start with a numeric.
_64_bit?
_32_bit?
intel?
sparc?
ppc64?
ppc64le?
powerpc?
Examples
execute 'build[my binary]' do command '...' not_if { _64_bit? } end
Cloud
azure?
cloud?
digitalocean?
ec2?
eucalyptus?
gce?
linode?
openstack?
cloudstack?
rackspace?
Examples
template '/tmp/config' do variables( # See also: best_ip_for ipaddress: cloud? ? node['local_ipv4'] : node['public_ipv4'] ) end
Core Extensions
Note: Core extensions are not included by default. You must require the chef/sugar/core_extensions
module manually to gain access to these APIs:
require 'chef/sugar/core_extensions'
String#satisfies?
String#satisfied_by?
Array#satisfied_by?
Object#blank?
Examples
# Checking version constraints '1.0.0'.satisfies?('~> 1.0') #=> true '~> 1.0'.satisfied_by?('1.0') #=> true
# Check for an object's presence ''.blank? #=> true ['hello'].blank? #=> false
Data Bag
-
encrypted_data_bag_item
- a handy DSL method for loading encrypted data bag items the same way you load a regular data bag item; this requiresChef::Config[:encrypted_data_bag_secret]
is set! -
encrypted_data_bag_item_for_environment
- find the encrypted data bag entry for the current node's Chef environment. -
data_bag_item_for_environment
- find the data bag entry for the current node's Chef environment.
Examples
encrypted_data_bag_item('accounts', 'hipchat')
encrypted_data_bag_item_for_environment('accounts', 'github')
data_bag_item_for_environment('accounts', 'github')
Docker
Chef Sugar looks for hints to see if the node being converged is a Docker container. When Ohai supports checking other nodes, Chef Sugar will automatically pick up the information.
docker?
Examples
template '/runme' do only_if { docker?(node) } end
Attributes
Chef Sugar adds more Chef-like DSL to attribute definitions. Instead of using the Ruby hash syntax, you can define attributes using nested namespaces. This DSL may be more friendly to non-Ruby developers. It can safely be mixed-and-matched with the standard syntax.
# This is functionally the same as default['apache2']['config']['root'] = '/var/www' namespace 'apache2' do namespace 'config' do root '/var/www' end end
# Specify multiple keys instead of nesting namespaces namespace 'apache2', 'config' do root '/var/www' end
# Specify different nested precedence levels namespace 'apache2', precedence: normal do namespace 'config', precedence: override do root '/var/www' #=> override['apache2']['config']['root'] = '/var/www' end end
Constraints
-
constraints
- create a new constraint (or requirement) that can be used to test version validations. -
chef_version
- (DSL only) a wrapper forversion(Chef::VERSION)
-
version
- create a new version that can be used to test constraint validation.
Examples
# Check if a version is satisfied by a constraint version('1.2.3').satisfies?('~> 1.2.0')
# Check if a constraint is satisfied by a version constraint('~> 1.2.0').satisfied_by?('1.2.3')
# Support multiple constraints version('1.2.3').satisfies?('> 1.2', '< 2.0') constraint('> 1.2', '< 2.0').satisfied_by?('1.2.3')
# Only perform an operation if Chef is at a certain version package 'apache2' do not_if { chef_version.satisfies?('~> 11.0') } # Ignore Chef 11 end
Kernel
-
require_chef_gem
- "safely" require a gem. Loading a gem with Chef is sometimes difficult and confusing. The errors that Chef produces are also sometimes not very intuitive. In the event you require a gem to exist on the system, you can userequire_chef_gem
, which will attempt to require the gem and then produce helpful output if the gem is not installed:Chef could not load the gem `#{name}'! You may need to install the gem manually with `gem install #{name}', or include a recipe before you can use this resource. Please consult the documentation for this cookbook for proper usage.
Examples
# LWRP require_chef_gem 'pry'
class Chef class Provider class MyProvider > Provider require_chef_gem 'pry' end end end
Init
-
systemd?
- detect if init system is systemd -
upstart?
- detect if init system is upstart -
runit?
- detect if init system is runit
Examples
systemd_service 'my-service' do description 'My Service' install do wanted_by 'multi-user.target' end service do exec_start '/usr/bin/myserviced' end action [:create, :enable, :start] only_if { systemd? } end cookbook_file '/etc/init/my-service.conf' do source 'my-service.conf' only_if { upstart? } end
IP
-
best_ip_for
- determine the best IP address for the given "other" node, preferring local IP addresses over public ones.
Examples
redis = search('node', 'role:redis').first template '/tmp/config' do variables( ipaddress: best_ip_for(redis) ) end
Node
Additional methods for the node
object
-
deep_fetch
- safely fetch a nested attribute. -
deep_fetch!
- fetch a nested attribute, raising a more semantic error if the key does not exist. -
in?
- determine if the node is in the given Chef environment.
Examples
credentials = if node.in?('production') Chef::EncryptedDataBag.new('...') else data_bag('...') end
node.deep_fetch('apache2', 'config', 'root') => node['apache2']['config']['root']
Platform
amazon_linux?
centos?
linux_mint?
oracle_linux?
redhat_enterprise_linux?
scientific_linux?
ubuntu?
solaris2?
aix?
smartos?
omnios?
raspbian?
nexus?
ios_xr?
There are also a series of dynamically defined matchers that map named operating system release versions and comparison operators in the form "#{platform}_#{operator}_#{name}?". For example:
debian_after_squeeze?
linuxmint_after_or_at_olivia?
mac_os_x_lion?
ubuntu_before_lucid?
ubuntu_before_or_at_maverick?
solaris_10?
solaris_11?
To get a full list, run the following in IRB:
require 'chef/sugar' puts Chef::Sugar::Platform.instance_methods
Examples
if ubuntu? execute 'apt-get update' end
Platform Family
arch_linux?
debian?
fedora?
freebsd?
gentoo?
linux?
mac_os_x?
openbsd?
rhel?
slackware?
suse?
windows?
wrlinux?
Examples
node['attribute'] = if windows? 'C:\Foo\BarDrive' else '/foo/bar_drive' end
Ruby
Note: The applies to the Ruby found at node['languages']['ruby']
.
ruby_20?
ruby_19?
Examples
log 'This has been known to fail on Ruby 2.0' if ruby_20?
Run Context
-
includes_recipe?
- determines if the current run context includes the recipe
if includes_recipe?('apache2::default') apache_module 'my_module' do # ... end end
Shell
which
dev_null
installed?
installed_at_version?
version_for
Examples
log "Using `mongo` at `#{which('mongo')}`" if installed?('apt') execute 'apt-get update' end execute 'install[thing]' do command "... 2>&1 #{dev_null}" not_if { installed_at_version?('thing', node['thing']['version']) } end log "Skipping git install, version is at #{version_for('mongo', '-v')}"
Vagrant
vagrant?
Examples
http_request 'http://...' do not_if { vagrant? } end
Virtualization
kvm?
lxc?
virtualbox?
vmware?
openvz?
Examples
service 'ntpd' do action [:enable, :start] not_if { lxc? } end
Filters
-
at_compile_time
- accepts a block of resources to run at compile time -
before
- insert resource in the collection before the given resource -
after
- insert resource in the collection after the given resource
Examples
at_compile_time do package 'apache2' end # This is equivalent to package 'apache2' do action :nothing end.run_action(:install)
before 'service[apache2]' do log 'I am before the apache 2 service fires!' end
after 'service[apache2]' do log 'I am after the apache 2 service fires!' end
License & Authors
- Author: Seth Vargo (sethvargo@gmail.com)
Copyright 2013-2015 Seth Vargo 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.
Dependent cookbooks
This cookbook has no specified dependencies.
Contingent cookbooks
Chef Sugar Changelog
This file is used to list changes made in each version of the chef-sugar cookbook and gem.
v3.3.0 (2016-01-11)
Improvements
- Break up
Chef::Sugar::Constraints
into a class and a dsl file - Add
platform_version
method with full constraints comparison support
v3.2.0 (2015-12-10)
Improvements
- Add platform matchers for
debian
andfedora
- Add
openvz
support under virtualization - Add init system detection support
- Add support for
nexus
,ios_xr
platforms andwrlinux
platform_family - Add additional
aix
helpers
Bug Fixes
- Properly expose
Architecture#i386?
in the DSL
v3.1.1 (2015-06-23)
Improvements
- Update Intel CPU types based on existing Fauxhai data
- Update SPARC logic and 32/64-bit logic for x86 and i386
Bug Fixes
- Fix 32-bit logic
- Fix default behavior to include chef-sugar at compile time
- Fix Chef 12.1.0 warnings for chef_gem compile time install
- Fix
redhat_enterprise_linux?
matcher
v3.0.2 (2015-03-26)
Improvements
- Add helpers for
ppc64
andppc64le
architecture
Bug Fixes
- Adjustments to error message
v3.0.1 (2015-03-20)
Breaking Changes
- Rename
compile_time
to at_compile_time
- if your recipes are affected by this breaking change, your Chef Client run will produce a verbose error message with details on how to fix the error.
v3.0.0 (2015-03-17)
Breaking Changes
- Drop support for Ruby 1.9 (it might still work, but it is no longer officially supported)
Improvements
- Remove accidentially committed gem source
- Bump development dependencies
- Add
digitalocean?
matcher - Expose the
rhel
platform asel
- Add
ppc64le
platform - Add helper for determining if architecture is SPARC
- Add helper for determining if architecture is Intel
- Add dynamic platform/version matchers for Solaris
Bug Fixes
- Reset namespace_options when reaching top-level resources
v2.5.0 (2015-01-05)
Improvements
- Add
data_bag_item_for_environment
function - Add
kvm?
matcher - Add
virtualbox?
matcher
Bug Fixes
- Use
.key?
to check for hash key presence, raising anAttributeDoesNotExist
error sooner
v2.4.1 (2014-10-12)
- No changes from v2.4.0 - forced a new version upload to the Chef Supermarket
v2.4.0 (2014-10-12)
Improvements
- Add
docker?
matcher
v2.3.2 (2014-10-07)
Big Fixues
- Include
amd64
in_64_bit?
check
v2.3.1 (2014-10-07)
Improvements
- Check all 64-bit architectures that may be reported by Ohai
Bug Fixes
- Be more tolerant of
nil
values return from sub functions - Check to make sure
node['domain']
is notnil
before calling#include?
v2.3.0 (2014-09-24)
Improvements
- Add
vmware?
matcher - Allow the attribute DSL to access parent attributes
Bug Fixes
- Return
true
orfalse
from all Boolean methods (instead ofnil
or truthy values)
v2.2.0 (2014-08-20)
Improvements
- Add
smartos?
matcher - Add
omnios?
matcher
v2.1.0 (2014-06-26)
Improvements
- Add
solaris2?
matcher - Add
aix?
matcher - Add 'lxc?' matcher
Bug Fixes
- Fix a bug in namespace memoization during attribute initialization
v2.0.0 (2014-06-16)
Breaking
- Remove
not_linux?
method - Remove
not_windows?
method
Improvements
- Miscellaneous spelling fixes
- Update a failing unit test for
installed?
- Add Mac OS X to the list of platforms (Yosemite)
- Upgrade to RSpec 3
- Fix
which
(andinstalled?
andinstalled_at_version?
) when given an absolute path - Fix
linux?
check to only return true on real linuxes
v1.3.0 (2014-05-05)
- Check both
$stdout
and$stderr
inversion_for
- Add additional platform versions
- Make
includes_recipe?
a top-level API (instead of just Node) - Match on the highest version number instead of direct equality checking on platform versions
- Define
Object#blank?
as a core extension - Define
String#flush
as a core extension - Remove Stove
v1.2.6 (2014-03-16)
- Fix a bug in
vagrant?
returning false on newer Vagrant versions - Remove Coveralls
v1.2.4 (2014-03-13)
- See (1.2.2), but I botched the release
v1.2.2 (2014-03-13)
- Fix a critical bug with
encrypted_data_bag_item
using the wrong key
v1.2.0 (2014-03-09)
- Add
namespace
functionality for specifying attributes in a DSL - Add constraints helpers for comparing version strings
- Add
require_chef_gem
to safely require and degrade if a gem is not installed - Add
deep_fetch
anddeep_fetch!
to fetch deeply nested keys - Accept an optional secret key in
encrypted_data_bag_item
helper and raise a helpful error if one is not set (NOTE: this changes the airity of the method, but it's backward-compatible because Ruby is magic) - Add Stove for releasing
- Updated copyrights for 2014
v1.1.0 (2013-12-10)
- Add
cloudstack?
helper - Add data bag helpers
- Remove foodcritic checks
- Upgrade development gem versions
- Randomize spec order
v1.0.1 (2013-10-15)
- Add development recipe
- Add
compile_time
,before
, andafter
filters
v1.0.0 (2013-10-15)
- First public release
Foodcritic Metric
3.3.0 passed this metric
3.3.0 passed this metric