Note: Please go to docs.rightscale.com to access the current RightScale documentation set. Also, feel free to Chat with us!
Home > Guides > Chef Cookbooks Developer Guide > Developer > Cookbook Development Resources > Chef Resources

Chef Resources

Table of Contents
  1. Quick Reference
  2. Complete Reference
    1. Cookbook File
      1. Actions
      2. Attributes
      3. Examples
        1. Create a directory
    2. Cron
      1. Actions
      2. Attributes
      3. Examples
        1. Run a program on the fifth hour of the day
        2. Run an entry if the folder exists
    3. Deploy
      1. Actions
      2. Attributes
      3. Examples
        1. Basic usage
        2. Backwards Compatible API
        3. Customizing the application layout
        4. Deploy without Symlinking to Shared
        5. Use embedded recipes for callbacks
    4. Directory
      1. Actions
      2. Attributes
      3. Examples
        1. Create a directory
        2. Create a group of directories
        3. Delete a directory and its contents
    5. Env
      1. Actions
      2. Attributes
      3. Examples
        1. Set an environment variable
    6. Erlang Call
      1. Actions
      2. Attributes
      3. Examples
        1. Run a command on an erlang node
    7. Execute
      1. Actions
      2. Attributes
      3. Examples
        1. Execute a command, with environment variable
        2. Execute a command only on notification
    8. Executable Schedule
      1. Actions
      2. Attributes
      3. Examples
    9. File
      1. Actions
      2. Attributes
      3. Examples
        1. Create a file
        2. Remove a file
        3. File Modes
    10. Git
    11. Group
      1. Actions
      2. Attributes
      3. Examples
        1. Random user
    12. HTTP Request
      1. Actions
      2. Attributes
      3. Examples
        1. Send a GET request
        2. Send a POST request, with JSON message body and basic authentication
    13. Ifconfig
      1. Actions
      2. Attributes
      3. Examples
        1. Configures a network interface
    14. Link
      1. Actions
      2. Attributes
      3. Examples
        1. Create a symbolic link
        2. Create a hard link
        3. Delete a link
    15. Log
      1. Actions
      2. Attributes
      3. Examples
        1. info log level
        2. debug log level
    16. Mdadm
      1. Actions
      2. Attributes
      3. Examples
        1. Create and Assemble a RAID 1 Array from two disks with a 64k chunk size
    17. Mount
      1. Actions
      2. Attributes
      3. Examples
        1. Mount a local block device
        2. Mount a remote filesystem
        3. Mount a remote windows folder on local drive letter T:
        4. Un-mount remote windows D-drive attached as local drive letter T:
        5. Mount a remote filesystem & add to fstab
        6. Mounted a labeled filesystem
        7. Mount a non-block filesystem
    18. Ohai
      1. Actions
      2. Attributes
      3. Examples
        1. Reload ohai
        2. Reload ohai configuration after new user
    19. Package
      1. Actions
      2. Attributes
      3. Examples
        1. Install Package
        2. Install Specific Package Version
        3. Install Package with options
        4. Upgrade Package
        5. Remove Package
        6. Purge Package
        7. Install Package using specific provider
        8. Install Yum package with specified architecture
        9. Install a gem file from the local filesystem
        10. Install a package with a response_file
        11. Purge Package
      4. Gem Package Options
      5. Specifying Options With a Hash
        1. Installing a Gem with a Hash of Options
      6. Specifying Options With a String
        1. Installing a Gem with an Options String
    20. PowerShell Script
      1. Actions
      2. Attributes
      3. Examples
        1. Write out to an interpolated path
        2. Use the change working directory attribute
        3. cwd to a winodws env variable
        4. Pass an env var to script
    21. Reboot, Stop or Terminate an Instance
      1. Actions
      2. Attributes
      3. Examples
        1. Reboot an instance
    22. Remote File
      1. Actions
      2. Attributes
      3. Deprecated Attributes
      4. Examples
        1. Transfer a file from some URL
        2. Transfer a file only if the remote source has changed (uses http_request resource)
    23. Remote Directory
      1. Attributes
      2. Examples
        1. Recursively transfer a directory from a remote location
    24. RemoteRecipe
      1. Actions
      2. Attributes
      3. Examples
        1. Run a remote recipe
    25. RightLinkTag
      1. Actions
      2. Examples
        1. Publish a machine tag
        2. Remove a machine tag
    26. Route
      1. Actions
      2. Attributes
      3. Examples
        1. Add a host route
        2. Delete a network route
    27. Ruby Block
      1. Actions
      2. Attributes
      3. Examples
        1. Reread Chef client config in a run
    28. SCM Resources
      1. Actions
      2. Attributes
      3. Examples
        1. Grab CouchDB from SVN
        2. Grab CouchDB from Git Mirror
        3. Use different branches in git
    29. Script
      1. Actions
      2. Attributes
      3. Examples
        1. Reread Chef client config in a run
        2. Use bash provider/interpreter to run the same script
    30. Server Collection
      1. Actions
      2. Attributes
      3. Examples
        1. Load tag information for active master database servers
    31. Service
      1. Actions
      2. Attributes
      3. Examples
        1. Starts the service if it is not running
        2. Basic example, starts the service if it's not running and enables it to start at system boot time
        3. Manage the ssh service, named depending on the node's platform
        4. Change Provider for service depending on the node's platform
        5. Process table has a different value than the name of the service script
    32. Template
      1. Actions
      2. Attributes
      3. Examples
        1. Config file from a template
        2. Config file from a local template
        3. Config file from a template with variable map
    33. User
      1. Actions
      2. Attributes
      3. Examples
        1. Random user
        2. System user
        3. Config file from a template with variable map

The following reference section documents the Chef resources that are available for use in Chef recipes if you are launching a server with a RightImage v5.8 and above or an equivalent machine image with RightLink v5.8 installed. Note: The v12.11 LTS/Infinity ServerTemplate release use v5.8 RightImages that support Chef v0.10.10


Quick Reference

Note: Defaults are highlighted in bold.

Cookbook File

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
cookbook_file create
create_if_missing
delete

backup
group
mode
rights
inherits
owner
path
source
cookbook

integer
string or id
integer
string
boolean
string
string
string
string

5



true

name
basename of path
current cookbook

v5.7+

v5.8+; rights, inherits

Linux, Windows

Cron

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
cron create
delete

minute
hour
day
month
weekday
command
user
mailto
path
home
shell

integer
integer
integer
integer
integer
string
string
string
string
string
string
*
*
*
*
*

root



 

v5.7+

Linux

Deploy

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
deploy deploy
force_deploy
rollback

deploy_to
repository
repo
revision
branch
user
group
svn_username
svn_password
svn_arguments
shallow_clone
enable_submodules
remote
ssh_wrapper
git_ssh_wrapper
scm_provider
repository_cache
environment
purge_before_symlink
create_dirs_before_symlink
symlinks


symlink_before_migrate

migrate
migrate_command
restart_command
rollback_on_error
before_migrate
before_symlink
before_restart
after_restart

string
string
string
string
string
string
string
string
string
string
string
boolean
string
string
string
string
string
hash
string or array
string
hash


hash

boolean
string
string
boolean
string
string
string
string



HEAD

nil
nil



nil
false
origin


Chef::Provider::Git
cached-copy

%w{log tmp/pids public/system}
%w{tmp public config}
{"system" => "public/system", "pids" => "tmp/pids", "log" => "log"}
{"config/database.yml" => "config/database.yml"}

false

nil
false
deploy/before_migrate.rb
deploy/before_symlink.rb
deploy/before_restart.rb
deploy/after_restart.rb

v5.7+

v5.8+; rollback_on_error

Linux

Directory

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
directory create
delete

group
mode
rights
inherits
owner
path
recursive

string or id
string
string
boolean
string
string
boolean



true

name
false

v5.7+

v5.8+; rights, inherits

Linux, Windows

Env

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
env create
delete
modify

key_name
value
delim

string
string
string
name

 
v5.7+ Windows

Erlang Call

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
erl_call run
nothing

code
cookie
distributed
name_type
node_name

string
string
string
string
string

q().

false
sname
chef@localhost
v5.7+ Linux

Execute

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
execute run
nothing

command
creates
cwd
environment
group
path
returns
timeout
user
unmask

string
string
string
string
string or id
string
integer
integer
string
string
name
nil
nil
nil
nil
nil
0
3600
nil
nil
v5.7+ Linux, Windows

Executable Schedule

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
executable_schedule 
(RightScale)
create
delete

name
minute
hour
day
month
weekday
recipe
recipe_id
right_script
right_script_id

string
integer
integer
integer
integer
integer
string
integer
string
integer



 
v5.7+ Linux, Windows

File

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
file create
create_if_missing
delete
touch

path
backup
group
mode
rights
inherits
owner
content

string
integer or boolean
string or id
integer
string
boolean
string
string
name
5



true

nil

v5.7+

v5.8+; rights, inherits

Linux, Windows

Git

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
git  

 

    v5.7+  

Group

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
group create
remove
modify
manage

group_name
gid
members
append
system

string or id
integer
string
boolean
boolean

name
nil
nil
false
nil

v5.7+

v5.8+; system

Linux

HTTP Request

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
http_request get
put
post
delete
head
options

url
message
headers

string
string
hash
nil
name
{}
v5.7+ Linux

IfConfig

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
ifconfig add
delete
enable
disable

target
device
hwaddr
inet_addr
bcast
mask
mtu
metric
onboot
network
bootproto
onparent

string
string
string
string
string
string
integer
string
string
string
string
string

name
nil
nil
nil
nil
nil
nil
nil
nil
nil
nil
nil

v5.7+ Linux

Link

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
link create
delete

target_file
to
link_type
owner
group

string
string
symbol
string
string
name

:symbolic

 
v5.7+ Linux

Log

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
log write

level

string :info v5.7+ Linux, Windows

Mdadm

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
mdadm create
assemble
stop

raid_device
devices
level
chunk

string
array
integer
integer
name

1
16
v5.7+ Linux

Mount

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
mount mount
unmount
remount
enable
disable

mount_point
device
device_type
fstype
options
dump
pass

string
string
string
string
string or array
integer
integer
name
nil
:device
nil
defaults
0
2
v5.7+ Linux

Ohai

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
ohai reload

plugin

string nil v5.7+ Linux, Windows

Package

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
package install
upgrade
remove
purge

package_name
version
response_file
source
options
gem_binary
arch
flush_cache

allow_downgrade

string
string
string
string
string
string
string
string

boolean
name
nil
nil

nil
nil (API)
nil
{ :before => false, :after => false }
false

v5.7+

v5.8+; flush_cache, allow_downgrade

Linux

PowerShell Script

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
powershell run

command
code
interpreter
flags

string
string
string
string

name
nil
nil
nil

v5.7+ Windows

Reboot, Stop or Terminate an Instance

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
rs_shutdown 
(RightScale)
reboot
stop
terminate

immediately

    v5.7+ Linux, Windows

Remote Directory

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
remote_directory  

cookbook
files_backup
files_owner
files_group
files_mode
rights
inherits
path
source
purge
overwrite

string
integer
string
string
string
string
boolean
string
string
boolean
boolean
nil
5
nil
nil
0644

true
name

false
true

v5.7+

v5.8+; rights, inherits

Linux, Windows

Remote File

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
remote_file create
create_if_missing

path
backup
group
mode
rights
inherits
owner
source
checksum

string
integer
string or integer
string
string
boolean
string
string
hash

name
5



true

basename of path attr
nil

v5.5+

v5.8+; rights, inherits

Linux, Windows

Remote Recipe

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
remote_recipe (RightScale) run

recipe
recipients
recipients_tags
scope

string
hash
string or array
string



:all
v5.7+ Linux, Windows

RightLinkTag

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
right_link_tag (RightScale) publish
remove

 

    v5.7+ Linux, Windows

Route

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
route add
delete

target
netmask
gateway
device

string
integer
string
string
name


 
v5.7+ Linux

Ruby Block

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
ruby_block create

block

string nil v5.7+ Linux, Windows

SCM

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
SCM sync
checkout
export
force_export

destination
repository
revision
reference
user
group
svn_username
svn_password
svn_arguments
svn_info_args
depth
enable_submodules
remote
additional_remotes
ssh_wrapper

string
string
string
string
string
string
string
string
string
string
integer
boolean
string
string
string


HEAD

nil
nil




nil
false
origin

 

v5.7+

v5.8+; additional_remotes

Linux, Windows

Script

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
script run

command
code
interpreter
flags

string
string
string
string
name
nil
nil
nil
v5.7+ Linux

Server Collection

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
server_collection
(RightScale)
load

tags
agent_ids

string
integer or array
nil
nil
v5.7+ Linux, Windows

Service

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
service enable
disable
nothing
start
stop
restart
reload

service_name
pattern
start_command
stop_command
status_command
restart_command
reload_command
supports

string
string
string
string
string
string
string
boolean
name
service_name
nil
nil
nil
nil
nil
false
v5.7+ Linux, Windows

Subversion

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
Subversion  

 

    v5.7+ Linux

Template

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
template create
create_if_missing

cookbook
path
source
group
mode
rights
inherits
owner
variables
local

string
string
string
string or id
string
string
boolean
string
string or array
string

nil
name
nil



true


false

v5.7+

v5.8+; rights, inherits

Linux, Windows

User

Resource Actions Attributes Attr Type Attr Default RightLink OS Support
user create
remove
modify
manage
lock
unlock

username
comment
uid
gid
home
shell
password
system
supports

string
string
integer
integer
string
string
hash
string
string or array
name
nil
nil
nil
nil
nil
nil
nil
{:manage_home => false, :non_unique => false }
v5.7+ Linux

Complete Reference

Cookbook File

Cookbook File transfers files from the files/ directory of a cookbook to a specified path on the host running chef-client or solo.

The file in the cookbook is selected according to file specificity, which allows you to use a different source file based on hostname, host platform (OS or distro, as appropriate), or specific platform version. Files under COOKBOOK_NAME/files/default will be used if a more specific version is not available.

Actions

Action Description Default
create Create this file Yes
create_if_missing Create this file if it does not exist  
delete Delete this file  

Attributes

Attribute Description Default Value
backup The number of backups of this file to keep. Set to 'false' if you do not want any backups stored. 5
group The group ownder of the file (string or id)  
mode

The octal mode of the file.  (e.g. 0755)

When specifying the mode, the value can be a quoted string. (e.g. "644") To specify a numeric value without quotes, it should be 5 digits so that Ruby can parse the string correctly. ( e.g. 00644) 

 
rights (Windows only) The user permissions. e.g. 'rights <permissions>, <principal>, <options>'. Supported in RightLink v5.8+.  
inherits (Windows only) The file inherits rights from parent. Supported in RightLink v5.8+. true
owner The owner of the file  
path Name attribute: The path to the file name
source The basename of the source file The basename of the path (destination)
cookbook The cookbook that this file is stored in The current cookbook

Examples

Create a directory
cookbook_file "/tmp/testfile" do
  source "testfile" # this is the value that would be inferred from the path parameter
  mode "0644"
end

 

back to top


Cron

Manage a cron entry. Attributes for a schedule will default to a wildcard (e.g. *) if not provided. You should only specify the schedule attributes that are applicable to your cron entry.

Create will update an entry if it shares the same name. The delete action will delete an entry with a matching name. Both notes only apply on a per-user basis.

Requires that a package providing crontab program is installed (typically cron).

Actions

Action Description Default
create

Create the crontab entry.

If a crontab file already exists with the same name, it will update (overwrite) the entry. (Applies on a per user basis.)

Yes
delete

Delete the crontab entry.

The delete action will delete an entry with a matching name. (Applies on a per user basis.)

 

Attributes

Attribute Description Default Value
minute The minute this entry should run (0 - 59) *
hour The hour this entry should run (0 - 23) *
day The day of month this entry should run (1 - 31) *
month The month this entry should run (1 - 12) *
weekday The weekday this entry should run (0 - 6) (Sunday=0) *
command The command to run  
user The user to run command as. Note: If you change the crontab user then the original user will still have the same crontab running until you explicity delete that crontab root
mailto Set the MAILTO environment variable  
path Set the PATH environment variable  
home Set the HOME environment variable  
shell Set the SHELL environment variable  

Examples

Run a program on the fifth hour of the day
cron "noop" do
  hour "5"
  minute "0"
  command "/bin/true"
end
Run an entry if the folder exists
cron "ganglia_tomcat_thread_max" do
  command "/usr/bin/gmetric -n 'tomcat threads max' -t uint32 -v `/usr/local/bin/tomcat-stat --thread-max`"
  only_if do File.exist?("/home/jboss") end
end

 

back to top


Deploy

A resource to help you manage and control your deployments. 

Actions

Action Description Default
deploy Deploy the application Yes
force_deploy For the revision deploy strategy, this removes any existing release of the same code version and re-deploys in its place  
rollback Rollback the application to the previous release  

Attributes

Attribute Description Default Value
deploy_to The "meta root" for your application.  
repository URI of the repository  
repo alias for repository  
revision revision to checkout. can be symbolic, like "HEAD" or an SCM specific revision id  HEAD
branch alias for revision  
user System user to run the deploy as nil (user chef runs as)
group System group to run the deploy as nil (group chef runs as)
svn_username (Subversion only) Username for Subversion operations  
svn_password (Subversion only) Password for Subversion operations  
svn_arguments (Subversion only) Extra arguments passed to the subversion command  
shallow_clone (Git only) boolean, true sets clone depth to 5 nil (full clone)
enable_submodules (Git only) performs a submodule init and submodule update false
remote (Git only) remote repository to use for syncing an existing clone origin
ssh_wrapper (Git only) path to a wrapper script for running SSH with git. GIT_SSH environment variable is set to this.  
git_ssh_wrapper alias for ssh_wrapper  
scm_provider SCM Provider to use. Chef::Provider::Git
repository_cache Name of the subdirectory where the pristine copy of your app's source is kept cached-copy
environment A hash of the form {"ENV_VARIABLE"=>"VALUE"}  
purge_before_symlink An array of paths, relative to app root, to be removed from a checkout before symlinking %w{log tmp/pids public/system}
create_dirs_before_symlink Directories to create before symlinking. Runs after purge_before_symlink %w{tmp public config}
symlinks A hash that maps files in the shared directory to their paths in the current release {"system" => "public/system", "pids" => "tmp/pids", "log" => "log"}
symlink_before_migrate A hash that maps files in the shared directory into the current release. Runs before migration {"config/database.yml" => "config/database.yml"}
migrate Should the migration command be executed? (true or false) false
migrate_command A string containing a shell command to execute to run the migration  
restart_command A code block to evaluate or a string containing a shell command  nil
rollback_on_error Boolean value that controls whether to rollback on error. When 'true', the deploy resource will rollback to the previously deployed release if an error occurs when deploying the new release. Supported in RightLink v5.8+. false
before_migrate A block or path to a file containing chef code to run before migrating deploy/before_migrate.rb
before_symlink A block or path to a file containing chef code to run before symlinking deploy/before_symlink.rb
before_restart A block or path to a file containing chef code to run before restarting deploy/before_restart.rb
after_restart A block or path to a file containing chef code to run after restarting deploy/after_restart.rb

Examples

Basic usage
deploy "/my/deploy/dir" do
  repo "git@github.com/whoami/project"
  revision "abc123" # or "HEAD" or "TAG_for_1.0" or (subversion) "1234"
  user "deploy_ninja"
  enable_submodules true
  migrate true
  migration_command "rake db:migrate"
  environment "RAILS_ENV" => "production", "OTHER_ENV" => "foo"
  shallow_clone true
  action :deploy # or :rollback
  restart_command "touch tmp/restart.txt"
  git_ssh_wrapper "wrap-ssh4git.sh"
  scm_provider Chef::Provider::Git # is the default, for svn: Chef::Provider::Subversion
end
Backwards Compatible API
deploy "/srv/#{appname}" do
  repo "git://github.com/radiant/radiant.git"
  revision "HEAD"
  user "railsdev"
  enable_submodules false
  migrate true
  migration_command "rake db:migrate"
  # Giving a string for environment sets RAILS_ENV, MERB_ENV, RACK_ENV
  environment "production"
  shallow_clone true
  action :deploy
  restart_command "touch tmp/restart.txt"
end
Customizing the application layout
deploy "/my/apps/dir/deploy" do
  # Use a local repo if you prefer
  repo "/path/to/gitrepo/typo/"
  environment "RAILS_ENV" => "production"
  revision "HEAD"
  action :deploy
  migration_command "rake db:migrate --trace"
  migrate true
  restart_command "touch tmp/restart.txt"
  create_dirs_before_symlink  %w{tmp public config deploy}
 
  # You can use this to customize if your app has extra configuration files 
  # such as amqp.yml or app_config.yml
  symlink_before_migrate  "config/database.yml" => "config/database.yml"
   
  # If your app has extra files in the shared folder, specify them here
  symlinks  "system" => "public/system", "pids" => "tmp/pids", "log" => "log",
            "deploy/before_migrate.rb" => "deploy/before_migrate.rb",
            "deploy/before_symlink.rb" => "deploy/before_symlink.rb",
            "deploy/before_restart.rb" => "deploy/before_restart.rb",
            "deploy/after_restart.rb" => "deploy/after_restart.rb"
end
Deploy without Symlinking to Shared
deploy "/my/apps/dir/deploy" do
  # OTHER PARAMETERS
  # ...
 
  # THIS DOESN'T WORK, the {} gets parsed as a code block:
  symlinks {}
  # Instead, use parentheses:
  symlinks({})
  # Or create your hash by calling new instead of using a literal:
  symlinks Hash.new
end
Use embedded recipes for callbacks
deploy "#{node[:tmpdir]}/deploy" do
  repo "#{node[:tmpdir]}/gitrepo/typo/"
  environment "RAILS_ENV" => "production"
  revision "HEAD"
  action :deploy
  migration_command "rake db:migrate --trace"
  migrate true
   
  # Callback awesomeness:
  before_migrate do
    current_release = release_path
     
    directory "#{current_release}/deploy" do
      mode "0755"
    end
     
    # creates a callback for before_symlink
    template "#{current_release}/deploy/before_symlink_callback.rb" do
      source "embedded_recipe_before_symlink.rb.erb"
      mode "0644"
    end
     
  end
   
  # This file can contain Chef recipe code, plain ruby also works
  before_symlink "deploy/before_symlink_callback.rb"
   
  restart do
    current_release = release_path
    file "#{release_path}/tmp/restart.txt" do
      mode "0644"
    end
  end
   
end

 

back to top


Directory

Manage a directory.

Actions

Action Description Default
create Create this directory Yes
delete Delete this directory  

Attributes

Attribute Description Default Value
group The group owner of the directory (string or id)  
mode The octal mode of the directory, e.g. '0755' default varies  
rights (Windows only) The user permissions. e.g. 'rights <permissions>, <principal>, <options>'. Supported in RightLink v5.8+.  
inherits (Windows only) The directory inherits rights from parent. Supported in RightLink v5.8+. true
owner The owner for the directory  
path Name attribute: The path to the directory name
recursive When deleting the directory, delete it recursively. When creating the directory, create recursively (ie, mkdir -p). Note: owner/group/mode only applies to the leaf directory, regardless of the value of this attribute. false

Examples

Create a directory
directory "/tmp/something" do
  owner "root"
  group "root"
  mode "0755"
  action :create
end
Create a group of directories
%w{dir1 dir2 dir3}.each do |dir|
   directory "/tmp/mydirs/#{dir}" do
      mode "0775"
      owner "root"
      group "root"
      action :create
      recursive true
   end
end
Delete a directory and its contents
directory "/tmp/something" do
  recursive true
  action :delete
end

 

back to top


Env

Manages environment keys. Currently, this is a windows-only resource.

On Unix Systems, the best way to manipulate the environment is via Ruby's ENV variable; however, manipulating this variable will not have the same "permanent" effect as using the env resource on Windows.

Actions

Action Description Default
create Create a new environment variable Yes
delete Delete an environment variable  
modify Modify an existing environment variable. This will append the given value to the existing value, delimited by delim.  

Attributes

Attribute Description Default Value
key_name The name of the key to create, delete, or modify name
value The value to set key_name to.  
delim The delimiter that separates multiple values for a single key.   

Examples

Set an environment variable
env "ComSpec" do
    value "C:\\Windows\\system32\\cmd.exe"
end

 

back to top


Erlang Call

Connects to a distributed erlang node and makes a call. See the documentation for erl_call in the OTP documentation for more information.

Like the Execute and Script resources, Erlang Call resources are not idempotent. Use the not_if and only_if meta parameters to guard the resource for idempotence.

Additionally, the erl_call command needs to be on the path for this resource to work properly.

Actions

Action Description Default
run Run this erlang call Yes
nothing Do not run this command  

Attributes

Attribute Description Default Value
code The erlang code to execute on the distributed node q().
cookie The cookie of erlang node you connect to  
distributed Starts a distributed erlang node if neccessary false
name_type Whether the node_name is an sname or name sname
node_name The node hostname to connect to chef@localhost

Examples

Run a command on an erlang node
erl_call "list names" do
  code "net_adm:names()."
  distributed true
  node_name "chef@latte"
end

 

back to top


Execute

Execute a command. Use Script resources to execute a script with a specific interpreter.

By their nature, Execute resources are not idempotent, as they are completely up to the user's imagination. Use the not_if or only_if meta parameters to guard the resource for idempotence.

Actions

Action Description Default
run Run this command Yes
nothing Do not run this command  

Attributes

Attribute Description Default Value
command Name attribute: The command to execute name
creates A file this command creates - if the file exists, the command will not be run. nil
cwd Current working directory to run the command from. nil
environment A hash of environment variables to set before running this command. nil
group A group name or group ID that we should change to before running this command. nil
path An array of paths to use when searching for the command. Note that these are not added to the command's environment $PATH. nil, uses system path
returns The return value of the command (may be an array of accepted values) - this resource raises an exception if the return value(s) do not match. 0
timeout How many seconds to let the command run before timing it out. 3600
user A user name or user ID that we should change to before running this command. nil
unmask Umask for files created by the command nil

Examples

Execute a command, with environment variable
execute "slapadd" do
  command "slapadd < /tmp/something.ldif"
  creates "/var/lib/slapd/uid.bdb"
  action :run
  environment ({'HOME' => '/home/myhome'})
end
Execute a command only on notification
execute "slapadd" do
  command "slapadd < /tmp/something.ldif"
  creates "/var/lib/slapd/uid.bdb"
  action :nothing
end
 
template "/tmp/something.ldif" do
  source "something.ldif"
  notifies :run, resources(:execute => "slapadd")
end

 

back to top


Executable Schedule

Define a schedule (cron) for a RightScript or a Chef recipe to be executed.

Actions

Action Description Default
create Create a schedule for a RightScript or Chef Recipe to be executed Yes
delete Delete a schedule  

Attributes

Attribute Description Default Value
name Schedule name  
minute Schedule minute  
hour Schedule hour  
day Schedule day  
month Schedule month  
weekday Schedule weekday  
recipe Chef recipe name for the schedule  
recipe_id Chef recipe id for the schedule  
right_script RightScript's name for the schedule  
right_script_id RightScript's id for the schedule  

Examples

 

back to top


File

Manage files and optionally set the content. See also CookbookFile, Template, and Remote File.

If you want to copy a file from a cookbook, you probably want to use CookbookFile instead. This resource is for working with files already on your node.

Actions

Action Description Default
create Create this file Yes
create_if_missing Create this file only if it does not exist. If it exists, do nothing.  
delete Delete this file  
touch Touch this file (update the mtime/atime)  

Attributes

Attribute Description Default Value
path Name attribute: The path to the file name
backup The number of backups of this file to keep. Set to 'false' if you do not want any backups stored. 5
group The group owner of the file (string or id)  
mode

The octal mode of the file. (e.g. 0755)

When specifying the mode, the value can be a quoted string. (e.g. "644") To specify a numeric value without quotes, it should be 5 digits so that Ruby can parse the string correctly. ( e.g. 00644) 

 
rights (Windows Only) The user permissions. e.g. 'rights <permissions>, <principal>, <options>'. Supported in RightLink v5.8+.  
inherits (Windows Only) The file inherits rights from parent. Supported in RightLink v5.8+. true
owner The owner for the file  
content A string to write to the file. This will replace any previous content if set nil (do not manage content)

Examples

Create a file
file "/tmp/something" do
  owner "root"
  group "root"
  mode "0755"
  action :create
end
Remove a file
file "/tmp/something" do
  action :delete
end
File Modes
# These are both equivalent.
file "/tmp/something" do
  mode "644"
end
 
file "/tmp/something" do
  mode 00644
end

 

back to top


Git

Git is a provider for the SCM resource. Since Git is closely linked with doing application code deployment, it is documented along with the Deploy resource.

back to top


Group

Manage a local group.

Actions

Action Description Default
create Create a group Yes
remove Remove a group  
modify Modify an existing group, raising an exception if the group does not exist.  
manage Manage an existing group. This will take no action if the group does not exist.  

Attributes

Attribute Description Default Value
group_name Name attribute: Name of the group. name
gid Group ID nil
members Include users in a group nil
append

true - Add these members to the group

false - These are the definitive group members

false
system

true - This is a system group, where the system is dependent on a low numbered range of GIDs.

false - This is not a system group

nil

Examples

Random user
group "admin" do
  gid 999
  members ['paco', 'vicente']
end

 

back to top


HTTP Request

Send an HTTP request with an arbitrary message. Handy for implementing your own callbacks!

Actions

Action Description Default
get Send a GET request Yes
put Send a PUT request  
post Send a POST request  
delete Send a DELETE request  
head Send a HEAD request  
options Send an OPTIONS request  

Attributes

Attribute Description Default Value
url The URL to send the request to nil
message Name attribute: The message to be sent to the URL (as the message parameter) name
headers Hash of custom headers {}

Examples

Send a GET request
# Sends "http://example.com/check_in?message=Send a GET request"
http_request "some message" do
  url "http://example.com/check_in"
end
Send a POST request, with JSON message body and basic authentication
http_request "posting data" do
  action :post
  url "http://example.com/check_in"
  message :some => "data"
  headers({"AUTHORIZATION" => "Basic #{Base64.encode64("username:password")}"})
end

 

back to top


Ifconfig

Manage interfaces with the ifconfig resource. This resource is still under development.

Note: Currently, the default provider only writes out a start-up configuration file for the interface on Red Hat-based platforms (it writes to /etc/sysconfig/network-scripts/ifcfg-#{device_name}).

Actions

Action Description Default
add Run ifconfig to configure the network interface and, on some platforms, write a configuration file for the network interface. Yes
delete Run ifconfig to bring the network interface down and, on some platforms delete the network interface's configuration file.  
enable Run ifconfig to configure the network interface.  
disable Run ifconfig to bring the network interface down.  

Attributes

Attribute Description Default Value
target The address you would like to assign to the interface. name
device The network interface to be configured. nil
hwaddr   nil
inet_addr   nil
bcast Broadcast address. Note this is not set with ifconfig but is added to the interface's startup configuration file on select platforms. nil
mask The netmask. nil
mtu The maximum transmission unit(mtu) of the network interface. nil
metric The routing metric of the interface. nil
onboot Determines whether interface should be brought up on boot. Set to "yes" to bring interface up on boot. nil
network The network address. nil
bootproto Boot protocol, such as "dhcp" nil
onparent Determines whether the interface should be brought up when parent interface is brought up. Set to "yes" to bring up interface when parent interface brought up. nil

Examples

Configures a network interface
ifconfig "192.186.0.1" do
  device "eth0"
end

 

back to top


Link

Create symbolic hard links.

Actions

Action Description Default
create Create a link Yes
delete Delete a link  

Attributes

Attribute Description Default Value
target_file Name Attribute: The file name of the link name
to The real file you want to link to  
link_type Either :symbolic or :hard. :symbolic
owner The owner of the symlink  
group The group of the symlink  

Examples

Create a symbolic link
# ln -s /etc/passwd /tmp/passwd
link "/tmp/passwd" do
  to "/etc/passwd"
end
Create a hard link
# ln /etc/passwd /tmp/passwd
link "/tmp/passwd" do
  to "/etc/passwd"
  link_type :hard
end
Delete a link
link "/tmp/mylink" do
  action :delete
  only_if "test -L /tmp/mylink"
end

 

back to top


Log

Adds log entries from your recipes.

Actions

Action Description Default
write Write to log Yes

Attributes

Attribute Description Default Value
level :info, :warn, :debug, :error, or :fatal :info

Examples

info log level
log "your string to log"
debug log level
log("a debug string") { level :debug }

 

back to top


Mdadm

Manage mdadm software RAID devices.

Actions

Action Description Default
create Create a new array with per-device superblocks Yes
assemble Assemble a previously created array into an active array  
stop Stop an active array  

Attributes

Attribute Description Default Value
raid_device Name attribute:The RAID device name (/dev/md0) name
devices An array of devices to include in the RAID array  
level The RAID level 1
chunk The chunk size 16

Examples

Create and Assemble a RAID 1 Array from two disks with a 64k chunk size
mdadm "/dev/md0" do
  devices [ "/dev/sda", "/dev/sdb" ]
  level 1
  chunk 64
  action [ :create, :assemble ]
end

 

back to top


Mount

Manage a mounted filesystem.

Actions

Action Description Default
mount Mount the device Yes
unmount Unmount the device  
remount Remount the device  
enable Add entry to fstab  
disable Remove entry from fstab  

Attributes

Attribute Description Default Value
mount_point Name attribute:The directory/path where the device should be mounted name
device The special block device or remote node, a label or an uuid to mount. nil
device_type The type of the device specified. Can be :device, :label or :uuid :device
fstype The filesystem type of the device. nil
options Array or string containing mount options. defaults
dump Dump frequency in days, for fstab entry. 0
pass Pass number for fsck, for fstab entry. 2

Examples

Mount a local block device
mount "/mnt/local" do
  device "/dev/sdb1"
  fstype "ext3"
end
Mount a remote filesystem
mount "/export/www" do
  device "nas1prod:/export/web_sites"
  fstype "nfs"
  options "rw"
end
Mount a remote windows folder on local drive letter T:
mount "T:" do
  action :mount
  device "\\\\hostname.example.com\\folder"
end
Un-mount remote windows D-drive attached as local drive letter T:
mount "T:" do
  action :umount
  device "\\\\hostname.example.com\\D$"
end
Mount a remote filesystem & add to fstab
mount "/export/www" do
  device "nas1prod:/export/web_sites"
  fstype "nfs"
  options "rw"
  action [:mount, :enable]
end
Mounted a labeled filesystem
mount "/mnt/volume1" do
  device "volume1"
  device_type :label
  fstype "xfs"
  options "rw"
end
Mount a non-block filesystem
mount "/mount/tmp" do
  pass     0
  fstype   "tmpfs"
  device   "/dev/null"
  options  "nr_inodes=999k,mode=755,size=500m"
  action   [:mount, :enable]
end

 

back to top


Ohai

Reload node's ohai configuration. This allows recipes that change system attributes (e.g. add a user) to refer to those attributes later in the recipe.

Actions

Action Description Default
reload Reload the node's ohai configuration Yes

Attributes

Attribute Description Default Value
plugin Optionally restrict reload to a particular ohai plugin nil

Examples

Reload ohai
ohai "reload" do
  action :reload
end
Reload ohai configuration after new user
ohai "reload_passwd" do
  action :nothing
  plugin "passwd"
end
 
user "daemonuser" do
  home "/dev/null"
  shell "/sbin/nologin"
  system true
  notifies :reload, resources(:ohai => "reload_passwd"), :immediately
end
 
template "/tmp/somefile" do
  source "somefile.erb"
  variables( :uid => node[:etc][:passwd][:daemonuser][:uid],
             :gid => node[:etc][:passwd][:daemonuser][:gid]
           )
end

 

back to top


Package

Manages packages.

Actions

Action Description Default
install Install a package - if version is provided, install that specific version Yes
upgrade Upgrade a package to the latest version  
remove Remove a package  
purge Purge a package (this usually entails removing configuration files as well as the package itself)  

Attributes

Attribute Description Default Value
package_name Name attribute: The name of the package to install name
version The version of the package to install/upgrade nil
response_file An optional response file - used to pre-seed packages (note: the file is fetched by Cookbook File) nil
source Used to provide an optional package source for providers that use a local file (rubygems, dpkg, yum and rpm)  
options Add additional options to the underlying package command nil
gem_binary A gem_package attribute to specify a gem binary. Useful for installing ruby 1.9 gems while running chef in ruby 1.8 nil (API)
arch The architecture of the package to install/upgrade (yum_package only) nil
flush_cache Flush the internal YumCache before/after install/upgrade (yum_package only). Supported in RightLink v5.8+. { :before => false, :after => false }
allow_downgrade Allow yum to downgrade a package to satisfy a requested version (yum_package only). Supported in RightLink v5.8+. false

Examples

Install Package
package "tar" do
  action :install
end
Install Specific Package Version
package "tar" do
  version "1.16.1-1"
  action :install
end
Install Package with options
package "debian-archive-keyring" do
  action :install
  options "--force-yes"
end
Upgrade Package
package "tar" do
  action :upgrade
end
Remove Package
package "tar" do
  action :remove
end
Purge Package
package "tar" do
  action :purge
end
Install Package using specific provider
package "tar" do
  action :install
  source "/tmp/tar-1.16.1-1.rpm"
  provider Chef::Provider::Package::Rpm
end
Install Yum package with specified architecture
yum_package "glibc-devel" do
  arch "i386"
end
Install a gem file from the local filesystem
 gem_package "right_aws" do
  source "/tmp/right_aws-1.11.0.gem"
  action :install
end
Install a package with a response_file

The use of a response file is only supported on Debian and Ubuntu at this time. Providers need to be written to support use of a response_file. On Debian and Ubuntu, the file contains debconf answers to questions normally asked by the package manager on installation. Put the file in files/default of the cookbook where the package is specified and Chef will use the Cookbook File resource to retrieve it.

package "sun-java6-jdk" do
  response_file "java.seed"
end
Purge Package
package "tar" do
  action :purge
end

Gem Package Options

As of Chef 0.9.0, the RubyGems package provider attempts to install gems using RubyGems' ruby api without spawning a new gem process, but falls back to spawning a gem command to install when necessary under the following conditions:

  1. If you specify a gem_binary, the provider will run that gem command to examine its environment settings, and again to install the gem.
  2. If you specify install options as a String, the provider will spawn a gem command with those options when installing the gem.

Specifying Options With a Hash

If you're not using an explicit gem_binary parameter to the gem_package resource, it is preferable to provide install options as a Hash. This allows the provider to install the gem without needing to spawn an external gem process. The following options are available (options are passed to rubygems' DependencyInstaller):

table

Installing a Gem with a Hash of Options
gem_package("bundler") do
  options(:prerelease => true, :format_executable => false)
end

Specifying Options With a String

When using an explicit gem_binary, you must pass in the options as a String. When not using an explicit gem_binary, you may still pass the options as a String, but this forces chef to spawn a gem process to install the gem, using more system resources. String options are passed verbatim to the gem command, so you specify them just as you would on the command line (i.e., "--prerelease" for prerelease gems).

Installing a Gem with an Options String
gem_package("nokogiri") do
  gem_binary("/opt/ree/bin/gem")
  options("--prerelease --no-format-executable")
end

 

back to top


PowerShell Script

Execute a script using the PowerShell interpreter.

Includes actions/attributes available to Execute resources: creates, cwd, environment, group, path, timeout, user. A temporary file is created and executed like other script resources, rather than run inline. This resource is used just like the regular Script resource (and providers for bash, csh, perl, python and ruby) with some small tweaks under the covers for the Windows platform and PowerShell interpreter.

By their nature, Script resources are not idempotent, as they are completely up to the user's imagination. Use the not_if or only_if meta parameters to guard the resource for idempotence.

Actions

Action Description Default
run Run the script Yes

Attributes

Attribute Description Default Value
command Name attribute: Name of the command to execute. name
code Quoted script of code to execute. nil
interpreter Script interpreter to use for code execution. nil
flags Command line flags to pass to the interpreter when invoking. nil

Examples

Write out to an interpolated path
powershell "write-to-interpolated-path" do
  code <<-EOH
  $stream = [System.IO.StreamWriter] "#{Chef::Config[:file_cache_path]}/powershell-test.txt"
  $stream.WriteLine("In #{Chef::Config[:file_cache_path]}...word.")
  $stream.close()
  EOH
end
Use the change working directory attribute
powershell "cwd-then-write" do
  cwd Chef::Config[:file_cache_path]
  code <<-EOH
  $stream = [System.IO.StreamWriter] "C:/powershell-test2.txt"
  $pwd = pwd
  $stream.WriteLine("This is the contents of: $pwd")
  $dirs = dir
  foreach ($dir in $dirs) {
    $stream.WriteLine($dir.fullname)
  }
  $stream.close()
  EOH
end
cwd to a winodws env variable
powershell "cwd-to-win-env-var" do
  cwd "%TEMP%"
  code <<-EOH
  $stream = [System.IO.StreamWriter] "./temp-write-from-chef.txt"
  $stream.WriteLine("chef on windows rox yo!")
  $stream.close()
  EOH
end
Pass an env var to script
powershell "read-env-var" do
  cwd Chef::Config[:file_cache_path]
  environment ({'foo' => 'BAZ'})
  code <<-EOH
  $stream = [System.IO.StreamWriter] "./test-read-env-var.txt"
  $stream.WriteLine("FOO is $foo")
  $stream.close()
  EOH
end

 

back to top


Reboot, Stop or Terminate an Instance

(RightScale Chef Resource - Available in RightLink v5.7 and above.)

Use rs_shutdown to reboot (-r or --reboot), stop (-s or --stop) or terminate (-t or --terminate) your instance from a recipe without any ambiguity about whether subsequent recipes will continue running. The two modes of rs_shutdown determine whether the current bundle will be interrupted (-i or --immediately) or allowed to finish before a shutdown is scheduled (-d or --deferred) (default). If a ServerTemplate has decommission recipes, then these will be scheduled to run prior to initiating the shutdown phase. rs_shutdown behaves the same for both Linux and Windows and uses the same audited functionality as the RightSite UI for requesting instance shutdown. The stop option is only valid for images which use persistent boot volumes.

If rs_shutdown is invoked more than once during bundle execution (by the same recipe or deferred from multiple recipes) then the effect is to escalate the request from reboot -> stop -> terminate and from deferred -> immediate. For example, if recipe A requests deferred reboot, recipe B requests deferred stop and recipe C requests immediate termination then the result is immediate termination before recipe D is allowed to run.

Actions

Action Description Default
reboot Reboots the instance. Yes
stop Stops the instance (preserves the boot volume). No
terminate Terminates the instance (discards the boot volume). No

Attributes

Attribute Description Default Value
immediately Boolean value indicating whether shutdown is immediate (true) or deferred (false). false

Examples

Reboot an instance
rs_shutdown "Tests rebooting the system immediately" do
  only_if do
    if node[:test][:testing_reboot][:has_rebooted]
      Chef::Log.info "Already rebooted"
      false
    else
      Chef::Log.info "Rebooting instance immediately"
      node[:test][:testing_reboot][:has_rebooted] = true
      true
    end
  end
  action :reboot
  immediately true
end

 

back to top


Remote File

(Deprecated Behavior: Use Cookbook File instead)

Note: In Chef 0.8.x and earlier, Remote File is also used to fetch files from the files/ directory in a cookbook. This behavior is now provided by Cookbook File, and use of Remote File for this purpose is deprecated (though still valid) in Chef 0.9.0 and later.

Transfer a file from a remote source. Remote File includes the attributes and actions of File. Name variable is still path.

Actions

Action Description Default
create Synchronize the file from the remote source to the filesystem. Yes
create_if_missing Create the file locally by fetching from the remote source only if the file doesn't yet exist.  

Attributes

Attribute Description Default Value
path Name attribute: The path to the file name
backup How many backups of this file to keep. Set to false if you want no backups. 5
group (optional) The group owner of the file (string or id)  
mode (optional) The octal mode of the file - e.g. '0755' default varies  
owner (optional) The owner for the file  
source The source URL the basename of the path attribute (see deprecated attributes)
checksum (optional) the SHA-256 checksum of the file--if the local file matches the checksum, Chef will not download it nil

Deprecated Attributes

Attribute Description Default Value
cookbook Specify the cookbook where the file is located, default is current cookbook nil
source The source file in files/ directory last path component of name

Examples

Transfer a file from some URL
remote_file "/tmp/testfile" do
  source "http://www.example.com/tempfiles/testfile"
  mode "0644"
  checksum "08da002l" # A SHA256 (or portion thereof) of the file.
end
Transfer a file only if the remote source has changed (uses http_request resource)
remote_file "/tmp/couch.png" do
  source "http://couchdb.apache.org/img/sketch.png"
  action :nothing
end
 
http_request "HEAD #{http://couchdb.apache.org/img/sketch.png}" do
  message ""
  url http://couchdb.apache.org/img/sketch.png
  action :head
  if File.exists?("/tmp/couch.png")
    headers "If-Modified-Since" => File.mtime("/tmp/couch.png").httpdate
  end
  notifies :create, resources(:remote_file => "/tmp/couch.png"), :immediately
end

 

back to top


Remote Directory

Recursively transfer a directory from the cookbook's files/default directory.

Remote directories obey file specificity so the directory you wish to copy should be located under COOKBOOK_NAME/files/default/REMOTE_DIRECTORY or a host- or distribution-specific path if desired.

Remote directory includes the attributes and actions of the Directory resource. Name variable is still path.

Attributes

Attribute Description Default Value
cookbook Specify the cookbook where the directory is located, default is current cookbook nil
files_backup Number of backup copies to keep for files in the directory 5
files_owner The owner for files in the directory. nil
files_group The group for files in the directory. nil
files_mode

The octal mode for files in the directory - 0755.

When specifying the mode, the value can be a quoted string. (e.g. "644") To specify a numeric value without quotes, it should be 5 digits so that Ruby can parse the string correctly. ( e.g. 00644) 

0644

<<Is this correct? Shouldn't it be "0755" (with quotes)? 

path Name attribute: Path to the directory. name
source From the cookbook's files/ directory.  
purge Purge any extra files found in the target directory false
overwrite Overwrite files if different from the source false

Examples

Recursively transfer a directory from a remote location
# create up to 10 backups of the files, set the files owner different from the directory.
remote_directory "/tmp/remote_something" do
  source "something"
  files_backup 10
  files_owner "root"
  files_group "root"
  files_mode "0644"
  owner "nobody"
  group "nobody"
  mode "0755"
end

 

back to top


RemoteRecipe

(RightScale Chef Resource - Available in RightLink v5.7 and above.)

A Chef recipe that should be run on a different instance living in the same deployment and running RightLink. A request to run a recipe on a different instance can be routed in two ways:

  • Using tags: The recipient_tags attribute identifies which instance(s) should run the recipe: instances that contain all tags listed in the attribute.
  • Using Server UUIDs: upon running a recipe that was requested by a different instance, the Server UUID of the requester is made available to the instance running the recipe. This instance can keep that ID to run recipes back on the requester (as in a ping/pong scenario).


Upon execution, the following two attributes are automatically initialized:

  • remote_recipe/tags
  • remote_recipe/from

Actions

Action Description Default
run Run a Chef recipe on a different server. Yes

Attributes

Attribute Description Default Value
remote_recipe/tags Array of tags used to route the remote recipe request.  
remote_recipe/from Server UUID of the requester, which can be used to route further remote executions back to the requester.  
recipe Name of recipe that should be run remotely.  
attributes A Hash of override attributes that should be used to run the remote recipe.  
recipients List of Server UUIDs of instances that should run the recipe. These IDs should have been retrieved using the remote/from attribute that was initialized when a remote recipe was previously run on the instance. All the corresponding instances must live in the same deployment.  
recipients_tags String or Array of tags used to route the request. Only instances that expose all of the tags in this list will run the recipe.  
scope

This attribute only applies when routing the request to run the recipe using tags. In this case, the scope specifies whether all (default) or a single instance with matching tags should run the recipe.

The value should be set to :all for running on all matching instances or :single for running on a single instance (picked randomly if more than one instance expose matching tags). 

 

Examples

Run a remote recipe
remote_recipe "wind up all golden monkeys" do
  recipe "monkey_cookbook::wind"
  attributes { turns => "10", from => @node[:rightscale][:instance_uuid] }
  recipients_tags ["provides:monkey_type=wind_up", "provides:monkey_type=golden"]
end

 

back to top


RightLinkTag

(RightScale Chef Resource - Available in RightLink v5.7 and above.)

Publish or remove a machine tag to/from the instance running the recipe.

Actions

Action Description Default
publish Publish a machine tag. Yes
remove Remove a machine tag.  

Examples

Publish a machine tag
right_link_tag "provides:monkey=golden"
Remove a machine tag
right_link_tag "provides:monkey=newbie" do
 action :remove
end

 

back to top


Route

Manage the system routing table.

Actions

Action Description Default
add Add a route Yes
delete Delete a route  

Attributes

Attribute Description Default Value
target Name attribute: The address of the target route name
netmask The decimal representation of the network mask eg 255.255.255.0  
gateway The gateway for the route  
device Network interface to apply this route to  

Examples

Add a host route
route "10.0.1.10/32" do
  gateway "10.0.0.20"
   device "eth1"
end
Delete a network route
route "10.1.1.0/24" do
  gateway "10.0.0.20"
   action :delete
end

 

back to top


Ruby Block

The ruby_block resource can be used to execute a bit of Ruby code during a run. Ruby code in ruby_block resources is evaluated with other resources during convergence, whereas Ruby code outside ruby_block resources is evaluated before other resources, during recipe evaluation (compilation).

(See Evaluate and Run Resources at Compile Time for examples, and Anatomy of a Chef Run for more detail on code evaluation within a chef-client run.)

Actions

Action Description Default
create Create the Ruby Block Yes

Attributes

Attribute Description Default Value
block A block of Ruby code nil

Examples

Reread Chef client config in a run
ruby_block "reload_client_config" do
  block do
    Chef::Config.from_file("/etc/chef/client.rb")
  end
  action :create
end

 

back to top


SCM Resources

Source Control Management (SCM) Resources, which may be used within the Deploy resource, or independently.

Actions

Action Description Default
sync Update the source to the specified revision or get a new clone/checkout. Yes
checkout Clone or checkout the source. Does nothing if a checkout is available.  
export Export the source, excluding or removing any version control artifacts.  
force_export (Subversion only) Force an export of the source overwriting the existing copy if it exists, excluding or removing any version control artifacts.  

Attributes

Attribute Description Default Value
destination Name attribute Path to clone/checkout/export the source to.  
repository URI of the repository  
revision revision to checkout. can be symbolic, like "HEAD" or an SCM specific revision id HEAD
reference (Git only) alias for revision  
user System user to own the checked out code nil (user chef runs as)
group System group to own the checked out code nil (user chef runs as)
svn_username (Subversion only) Username for Subversion operations  
svn_password (Subversion only) Password for Subversion operations  
svn_arguments (Subversion only) Extra arguments passed to the subversion command  
svn_info_args (Subversion only) svn_arguments are not used when chef calls "svn info". If you need arguments to be passed to "svn info", put them in svn_info_args  
depth (Git only) Number of past revisions to include in Git shallow clone nil (full clone)
enable_submodules (Git only) performs a submodule init and submodule update false
remote (Git only) remote repository to use for syncing an existing clone origin
additional_remotes (Git only) Array of additional remotes to add to the repositories configuration  
ssh_wrapper (Git only) path to a wrapper script for running SSH with git. GIT_SSH environment variable is set to this.  

Examples

Grab CouchDB from SVN
subversion "CouchDB Edge" do
  repository "http://svn.apache.org/repos/asf/couchdb/trunk"
  revision "HEAD"
  destination "/opt/mysources/couch"
  action :sync
end
Grab CouchDB from Git Mirror
git "/opt/mysources/couch" do
  repository "git://git.apache.org/couchdb.git"
  reference "master"
  action :sync
end
Use different branches in git
git "/opt/mysources/couch" do
  repository "git://git.apache.org/couchdb.git"
  reference "master"
  action :sync
end

In the above example, the branch_name variable is being set to "staging" or "master" depending on the environment of the node. Once that is determined, it uses the branch_name variable to set the revision for the repository.

Keep in mind that if you use the command "git status" after running this recipe it will return the branch name as "deploy" regardless, as this is a default value. You should be able to see it checking out the correct branch when you run chef-client with debugging on:

sudo chef-client -l debug

 

back to top


Script

Execute a script using the specified interpreter. Includes all actions/attributes available to Execute resources. Predefined available script interpreters are bash, csh, perl, python and ruby.

The ruby script resource is different than the ruby_block resource described above, as it is created as a temporary file and executed like other script resources, rather than run inline.

By their nature, Script resources are not idempotent, as they are completely up to the user's imagination. Use the not_if or only_if meta parameters to guard the resource for idempotence.

Actions

Action Description Default
run Run the script Yes

Attributes

Attribute Description Default Value
command Name attribute: Name of the command to execute. name
code Quoted script of code to execute. nil
interpreter Script interpreter to use for code execution. nil
flags command line flags to pass to the interpreter when invoking nil

Examples

Reread Chef client config in a run
script "install_something" do
  interpreter "bash"
  user "root"
  cwd "/tmp"
  code <<-EOH
  wget http://www.example.com/tarball.tar.gz
  tar -zxf tarball.tar.gz
  cd tarball
  ./configure
  make
  make install
  EOH
end
Use bash provider/interpreter to run the same script
bash "install_something" do
  user "root"
  cwd "/tmp"
  code <<-EOH
  wget http://www.example.com/tarball.tar.gz
  tar -zxf tarball.tar.gz
  cd tarball
  ./configure
  make
  make install
  EOH
end

 

back to top


Server Collection

(RightScale Chef Resource - Available in RightLink v5.7 and above.)

This resource allows locating multiple instances running in the same deployment using tags or their Server UUID. It initializes the node with attributes named after the Server UUID of the instances and containing the list of all their tags. The Server UUIDs can be used to then run remote recipes on the instances. Note that all of the tags contained in the matching instances are returned, not just the tags specified to locate them. This means that the ServerCollection resource can help retrieve information that is contained in tags on different instances needed to configure the local instance. In other words, while some tags may be "well known" and used to locate instances, other tags may contain information that the ServerCollection resource will make available to the local instance for configuration purposes.

Actions

Action Description Default
load

Load hash of instances' RightScale IDs to tags into the Chef node.

The attributes are initialized under the name given to the collection: name/Server UUID.

The value is an array consisting of all tags contained in the instance with the given Server UUID.

Yes

Attributes

Attribute Description Default Value
tags List of potential tags that instances must contain in order to be selected. An instance containing any of the given tags is selected. The values can use machine tag wildcards. For more information about proper syntax for machine tags, see Tagging. nil
agent_ids List of RightLink IDs of instances living in the same deployment whose tags should be retrieved. nil

Examples

Load tag information for active master database servers

You can use semi-wildcards by substituting an asterisk (*) for the value part of the machine tag—for example, "db:master=*". You can also use a wildcard with a partial prefix match on the predicate. (e.g. "db:m*") Prefix match does not apply to matching tag values. ("db:master=a*")

server_collection "my_master_servers" do
  tags "db:master=active"
end

The sample code above will populate the node object as:

@node[:server_collection]["my_master_servers"]["0012E"] = [ "db:master=active", "db:backup_frequency=4" ]

Load tag information for all application servers.

server_collection "my_app_servers" do
    tags [ "app:" ]
end

The sample code above will populate the node object as:

@node[:server_collection]["my_app_servers"]["001XE"] = [ "app:active=true", "app:vhost=www" ]
@node[:server_collection]["my_app_servers"]["003XE"] = [ "app:active=true", "app:vhost=api" ]
@node[:server_collection]["my_app_servers"]["007XE"] = [ "app:active=false", "app:vhost=www" ]

 

back to top


Service

Manage a service.

Actions

Action Description Default
enable Enable this service  
disable Disable this service  
nothing Do not do anything with service Yes
start Start this service  
stop Stop this service  
restart Restart this service  
reload Reload the configuration for this service  

Attributes

Attribute Description Default Value
service_name Name attribute: Name of the service. name
pattern Pattern to look for in the process table. service_name
start_command Command used to start this service. nil
stop_command Command used to stop this service. nil
status_command Command used to check the service run status. nil
restart_command Command used to restart this service. nil
reload_command Command used to tell this service to reload its configuration. nil
supports

Features this service supports, ie :restart, :reload, :status.

The supports parameter attribute controls how the Chef Provider will attempt to manage the service.

  • :restart - the init script or other service provider can use a restart command. If this is not specified, Chef will attempt to stop then start the service.
  • :reload - the init script or other service provider can use a reload command.
  • :status - the init script or other service provider can use a status command to determine if the service is running. If this is not specified, Chef will attempt to match the service_name against the process table as a regular expression, unless pattern is specified as a parameter attribute.
false

Examples

Starts the service if it is not running
# typically this will run /etc/init.d/example_service start
service "example_service" do
  action :start
end
Basic example, starts the service if it's not running and enables it to start at system boot time
# runs /etc/init.d/example_service (start|stop|restart), etc.
service "example_service" do
  supports :status => true, :restart => true, :reload => true
  action [ :enable, :start ]
end
Manage the ssh service, named depending on the node's platform
service "example_service" do
  case node[:platform]
  when "CentOS","RedHat","Fedora"
    service_name "redhat_name"
  else
    service_name "other_name"
  end
  supports :restart => true
  action [ :enable, :start ]
end
Change Provider for service depending on the node's platform
service "example_service" do
    case node[:platform]
    when "ubuntu"
      if node[:platform_version].to_f >= 9.10
        provider Chef::Provider::Service::Upstart
      end
    end
    action [:enable, :start]
  end
Process table has a different value than the name of the service script
service "samba" do
  pattern "smbd"
  action [:enable, :start]
end

 

back to top


Template

Manage File contents with an embedded ruby (erb) template. Includes actions and attributes from File. path is the Name attribute. Read more about templates.

Templates follow the same File Specificity rules as remote_file and file resources.

Actions

Action Description Default
create Create the file Yes
create_if_missing Create only if it does not exist yet  

Attributes

Attribute Description Default Value
cookbook Specify the cookbook where the template is located, default is current cookbook nil
path Name attribute: The path to the file name
source Template source file. Found in templates/default for the cookbook. nil
group The group owner of the file (string or id)  
mode The octal mode of the file - e.g. '0755'  
rights (Windows only) The user permissions. e.g. 'rights <permissions>, <principal>, <options>'. Supported in RightLink v5.8+.  
inherits (Windows only) The file inherits rights from parent. Supported in RightLink v5.8+. true
owner The owner for the file  
variables Variables to use in the template.  
local

Is the template already present on the node?

false

Examples

Config file from a template
template "/tmp/config.conf" do
  source "config.conf.erb"
end
Config file from a local template
template "/tmp/config.conf" do
  local true
  source "/tmp/config.conf.erb"
end
Config file from a template with variable map
template "/tmp/config.conf" do
  source "config.conf.erb"
  variables(
    :config_var => node[:configs][:config_var]
  )
end

 

back to top


User

Manage a local user.

Actions

Action Description Default
create Create the user with given attributes. If the user exist, ensure that the resource is in the correct state. This implies manage. Yes
remove Remove the user.  
modify Modify an existing user, raising an exception if the user does not exist.  
manage Manage an existing user. This will take no action if the user does not exist.  
lock Lock the user's password.  
unlock Unlock the user's password.  

Attributes

Attribute Description Default Value
username Name attribute: Name of the user. name
comment Gecos/Comment field. nil
uid Numeric user id. nil
gid Primary group id. nil
home Home directory location nil
shell Login shell. nil
password Shadow hash of password. nil
system

Whether to create a system user.

nil
supports User features supported, eg :manage_home. {:manage_home => false, :non_unique => false }

Examples

Random user
user "random" do
  comment "Random User"
  uid 1000
  gid "users"
  home "/home/random"
  shell "/bin/zsh"
  password "$1$JJsvHslV$szsCjVEroftprNn4JHtDi."
end
System user
user "systemguy" do
  comment "system guy"
  system true
  shell "/bin/false"
end
Config file from a template with variable map
template "/tmp/config.conf" do
  source "config.conf.erb"
  variables(
    :config_var => node[:configs][:config_var]
  )
end

 

back to top


You must to post a comment.
Last modified
07:59, 30 May 2014

Tags

This page has no custom tags.

Classifications

This page has no classifications.

Announcements

None


© 2006-2014 RightScale, Inc. All rights reserved.
RightScale is a registered trademark of RightScale, Inc. All other products and services may be trademarks or servicemarks of their respective owners.