diff options
author | Tim Smith <tsmith@chef.io> | 2021-08-13 17:33:53 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-08-13 17:33:53 -0700 |
commit | 744927fba3eba8a6141eba19ecede825a38f802b (patch) | |
tree | 2344530c42132adebba0802acd6aba876a639063 | |
parent | 76c8a4589f4491d38778eec2df1546eca1cdcc4e (diff) | |
parent | 75385528acc7969205fd185e11481bf61b121499 (diff) | |
download | chef-744927fba3eba8a6141eba19ecede825a38f802b.tar.gz |
Merge pull request #11922 from chef/docs
Add more descriptions to actions for documentation
-rw-r--r-- | lib/chef/provider/subversion.rb | 8 | ||||
-rw-r--r-- | lib/chef/provider/systemd_unit.rb | 33 | ||||
-rw-r--r-- | lib/chef/provider/yum_repository.rb | 6 | ||||
-rw-r--r-- | lib/chef/provider/zypper_repository.rb | 6 | ||||
-rw-r--r-- | lib/chef/resource/ruby_block.rb | 100 | ||||
-rw-r--r-- | lib/chef/resource/scm/subversion.rb | 2 | ||||
-rw-r--r-- | lib/chef/resource/sysctl.rb | 4 | ||||
-rw-r--r-- | lib/chef/resource/systemd_unit.rb | 4 | ||||
-rw-r--r-- | lib/chef/resource/yum_package.rb | 6 |
9 files changed, 133 insertions, 36 deletions
diff --git a/lib/chef/provider/subversion.rb b/lib/chef/provider/subversion.rb index 7f49e2139f..e60b684bce 100644 --- a/lib/chef/provider/subversion.rb +++ b/lib/chef/provider/subversion.rb @@ -55,7 +55,7 @@ class Chef end end - action :checkout do + action :checkout, description: "Clone or check out the source. When a checkout is available, this provider does nothing." do if target_dir_non_existent_or_empty? converge_by("perform checkout of #{new_resource.repository} into #{new_resource.destination}") do shell_out!(checkout_command, run_options) @@ -65,7 +65,7 @@ class Chef end end - action :export do + action :export, description: "Export the source, excluding or removing any version control artifacts." do if target_dir_non_existent_or_empty? action_force_export else @@ -73,13 +73,13 @@ class Chef end end - action :force_export do + action :force_export, description: "Export the source, excluding or removing any version control artifacts and force an export of the source that is overwriting the existing copy (if it exists)." do converge_by("export #{new_resource.repository} into #{new_resource.destination}") do shell_out!(export_command, run_options) end end - action :sync do + action :sync, description: "Update the source to the specified version, or get a new clone or checkout. This action causes a hard reset of the index and working tree, discarding any uncommitted changes." do assert_target_directory_valid! if ::File.exist?(::File.join(new_resource.destination, ".svn")) current_rev = find_current_revision diff --git a/lib/chef/provider/systemd_unit.rb b/lib/chef/provider/systemd_unit.rb index 26a20814f5..c0e0aee93c 100644 --- a/lib/chef/provider/systemd_unit.rb +++ b/lib/chef/provider/systemd_unit.rb @@ -22,6 +22,7 @@ require_relative "../resource/file" require_relative "../resource/file/verification/systemd_unit" require "iniparse" require "shellwords" unless defined?(Shellwords) +require "chef-utils/dist" unless defined?(ChefUtils::Dist) class Chef class Provider @@ -75,7 +76,7 @@ class Chef end end - action :create do + action :create, description: "Create a systemd unit file, if it does not already exist." do if current_resource.content != new_resource.to_ini converge_by("creating unit: #{new_resource.unit_name}") do manage_unit_file(:create) @@ -84,7 +85,7 @@ class Chef end end - action :delete do + action :delete, description: "Delete a systemd unit file, if it exists." do if ::File.exist?(unit_path) converge_by("deleting unit: #{new_resource.unit_name}") do manage_unit_file(:delete) @@ -93,19 +94,19 @@ class Chef end end - action :preset do + action :preset, description: "Restore the preset '`enable`/`disable`' configuration for a systemd unit. *New in #{ChefUtils::Dist::Infra::PRODUCT} 14.0.*" do converge_by("restoring enable/disable preset configuration for unit: #{new_resource.unit_name}") do systemctl_execute!(:preset, new_resource.unit_name) end end - action :revert do + action :revert, description: "Revert to a vendor's version of a systemd unit file. *New in #{ChefUtils::Dist::Infra::PRODUCT} 14.0.*" do converge_by("reverting to vendor version of unit: #{new_resource.unit_name}") do systemctl_execute!(:revert, new_resource.unit_name) end end - action :enable do + action :enable, description: "Ensure the unit will be started after the next system boot." do if current_resource.static logger.debug("#{new_resource.unit_name} is a static unit, enabling is a NOP.") end @@ -121,7 +122,7 @@ class Chef end end - action :disable do + action :disable, description: "Ensure the unit will not be started after the next system boot." do if current_resource.static logger.debug("#{new_resource.unit_name} is a static unit, disabling is a NOP.") end @@ -138,14 +139,14 @@ class Chef end end - action :reenable do + action :reenable, description: "Reenable a unit file. *New in #{ChefUtils::Dist::Infra::PRODUCT} 14.0.*" do converge_by("reenabling unit: #{new_resource.unit_name}") do systemctl_execute!(:reenable, new_resource.unit_name) logger.info("#{new_resource} reenabled") end end - action :mask do + action :mask, description: "Ensure the unit will not start, even to satisfy dependencies." do unless current_resource.masked converge_by("masking unit: #{new_resource.unit_name}") do systemctl_execute!(:mask, new_resource.unit_name) @@ -154,7 +155,7 @@ class Chef end end - action :unmask do + action :unmask, description: "Stop the unit from being masked and cause it to start as specified." do if current_resource.masked converge_by("unmasking unit: #{new_resource.unit_name}") do systemctl_execute!(:unmask, new_resource.unit_name) @@ -163,7 +164,7 @@ class Chef end end - action :start do + action :start, description: "Start a systemd unit." do unless current_resource.active converge_by("starting unit: #{new_resource.unit_name}") do systemctl_execute!(:start, new_resource.unit_name, default_env: false) @@ -172,7 +173,7 @@ class Chef end end - action :stop do + action :stop, description: "Stop a running systemd unit." do if current_resource.active converge_by("stopping unit: #{new_resource.unit_name}") do systemctl_execute!(:stop, new_resource.unit_name, default_env: false) @@ -181,14 +182,14 @@ class Chef end end - action :restart do + action :restart, description: "Restart a systemd unit." do converge_by("restarting unit: #{new_resource.unit_name}") do systemctl_execute!(:restart, new_resource.unit_name, default_env: false) logger.info("#{new_resource} restarted") end end - action :reload do + action :reload, description: "Reload the configuration file for a systemd unit." do if current_resource.active converge_by("reloading unit: #{new_resource.unit_name}") do systemctl_execute!(:reload, new_resource.unit_name, default_env: false) @@ -199,21 +200,21 @@ class Chef end end - action :try_restart do + action :try_restart, description: "Try to restart a systemd unit if the unit is running." do converge_by("try-restarting unit: #{new_resource.unit_name}") do systemctl_execute!("try-restart", new_resource.unit_name, default_env: false) logger.info("#{new_resource} try-restarted") end end - action :reload_or_restart do + action :reload_or_restart, description: "For systemd units that are services, this action reloads the configuration of the service without restarting, if possible; otherwise, it will restart the service so the new configuration is applied." do converge_by("reload-or-restarting unit: #{new_resource.unit_name}") do systemctl_execute!("reload-or-restart", new_resource.unit_name, default_env: false) logger.info("#{new_resource} reload-or-restarted") end end - action :reload_or_try_restart do + action :reload_or_try_restart, description: "For systemd units that are services, this action reloads the configuration of the service without restarting, if possible; otherwise, it will try to restart the service so the new configuration is applied." do converge_by("reload-or-try-restarting unit: #{new_resource.unit_name}") do systemctl_execute!("reload-or-try-restart", new_resource.unit_name, default_env: false) logger.info("#{new_resource} reload-or-try-restarted") diff --git a/lib/chef/provider/yum_repository.rb b/lib/chef/provider/yum_repository.rb index 8269487bbd..a3d19e95d3 100644 --- a/lib/chef/provider/yum_repository.rb +++ b/lib/chef/provider/yum_repository.rb @@ -31,7 +31,7 @@ class Chef def load_current_resource; end - action :create do + action :create, description: "Create a repository based on the properties." do template ::File.join(new_resource.reposdir, "#{new_resource.repositoryid}.repo") do if template_available?(new_resource.source) source new_resource.source @@ -69,7 +69,7 @@ class Chef end end - action :delete do + action :delete, description: "Remove a repository." do # clean the repo cache first execute "yum clean all #{new_resource.repositoryid}" do command "yum clean all --disablerepo=* --enablerepo=#{new_resource.repositoryid}" @@ -86,7 +86,7 @@ class Chef end end - action :makecache do + action :makecache, description: "Force the creation of the repository cache. This is also done automatically when a repository is updated." do execute "yum-makecache-#{new_resource.repositoryid}" do command "yum -q -y makecache --disablerepo=* --enablerepo=#{new_resource.repositoryid}" action :run diff --git a/lib/chef/provider/zypper_repository.rb b/lib/chef/provider/zypper_repository.rb index c1c863e20e..08e254b6b8 100644 --- a/lib/chef/provider/zypper_repository.rb +++ b/lib/chef/provider/zypper_repository.rb @@ -29,7 +29,7 @@ class Chef def load_current_resource; end - action :create do + action :create, description: "Add a new Zypper repository." do if new_resource.gpgautoimportkeys install_gpg_keys(new_resource.gpgkey) else @@ -50,13 +50,13 @@ class Chef end end - action :delete do + action :delete, description: "Remove a Zypper repository." do execute "zypper --quiet --non-interactive removerepo #{escaped_repo_name}" do only_if "zypper --quiet lr #{escaped_repo_name}" end end - action :refresh do + action :refresh, description: "Refresh Zypper repository." do execute "zypper --quiet --non-interactive refresh --force #{escaped_repo_name}" do only_if "zypper --quiet lr #{escaped_repo_name}" end diff --git a/lib/chef/resource/ruby_block.rb b/lib/chef/resource/ruby_block.rb index 2d7d2fe8b6..b0ab19002f 100644 --- a/lib/chef/resource/ruby_block.rb +++ b/lib/chef/resource/ruby_block.rb @@ -29,6 +29,106 @@ class Chef provides :ruby_block, target_mode: true description "Use the **ruby_block** resource to execute Ruby code during a #{ChefUtils::Dist::Infra::PRODUCT} run. Ruby code in the `ruby_block` resource is evaluated with other resources during convergence, whereas Ruby code outside of a `ruby_block` resource is evaluated before other resources, as the recipe is compiled." + examples <<~'DOC' + **Reload Chef Infra Client configuration data** + + ```ruby + ruby_block 'reload_client_config' do + block do + Chef::Config.from_file('/etc/chef/client.rb') + end + action :run + end + ``` + + **Run a block on a particular platform** + + The following example shows how an if statement can be used with the `windows?` method in the Chef Infra Language to run code specific to Microsoft Windows. The code is defined using the ruby_block resource: + + ```ruby + if windows? + ruby_block 'copy libmysql.dll into ruby path' do + block do + require 'fileutils' + FileUtils.cp "#{node['mysql']['client']['lib_dir']}\\libmysql.dll", + node['mysql']['client']['ruby_dir'] + end + not_if { ::File.exist?("#{node['mysql']['client']['ruby_dir']}\\libmysql.dll") } + end + end + ``` + + **Stash a file in a data bag** + + The following example shows how to use the ruby_block resource to stash a BitTorrent file in a data bag so that it can be distributed to nodes in the organization. + + ```ruby + ruby_block 'share the torrent file' do + block do + f = File.open(node['bittorrent']['torrent'],'rb') + #read the .torrent file and base64 encode it + enc = Base64.encode64(f.read) + data = { + 'id'=>bittorrent_item_id(node['bittorrent']['file']), + 'seed'=>node.ipaddress, + 'torrent'=>enc + } + item = Chef::DataBagItem.new + item.data_bag('bittorrent') + item.raw_data = data + item.save + end + action :nothing + subscribes :create, "bittorrent_torrent[#{node['bittorrent']['torrent']}]", :immediately + end + ``` + + **Update the /etc/hosts file** + + The following example shows how the ruby_block resource can be used to update the /etc/hosts file: + + ```ruby + ruby_block 'edit etc hosts' do + block do + rc = Chef::Util::FileEdit.new('/etc/hosts') + rc.search_file_replace_line(/^127\.0\.0\.1 localhost$/, + '127.0.0.1 #{new_fqdn} #{new_hostname} localhost') + rc.write_file + end + end + ``` + + **Set environment variables** + + The following example shows how to use variables within a Ruby block to set environment variables using rbenv. + + ```ruby + node.override[:rbenv][:root] = rbenv_root + node.override[:ruby_build][:bin_path] = rbenv_binary_path + + ruby_block 'initialize' do + block do + ENV['RBENV_ROOT'] = node[:rbenv][:root] + ENV['PATH'] = "#{node[:rbenv][:root]}/bin:#{node[:ruby_build][:bin_path]}:#{ENV['PATH']}" + end + end + ``` + + **Call methods in a gem** + + The following example shows how to call methods in gems not shipped in Chef Infra Client + + ```ruby + chef_gem 'mongodb' + + ruby_block 'config_replicaset' do + block do + MongoDB.configure_replicaset(node, replicaset_name, rs_nodes) + end + action :run + end + ``` + DOC default_action :run allowed_actions :create, :run diff --git a/lib/chef/resource/scm/subversion.rb b/lib/chef/resource/scm/subversion.rb index db20787aa5..7216aa53dd 100644 --- a/lib/chef/resource/scm/subversion.rb +++ b/lib/chef/resource/scm/subversion.rb @@ -28,7 +28,7 @@ class Chef provides :subversion - description "Use the **subversion** resource to manage source control resources that exist in a Subversion repository." + description "Use the **subversion** resource to manage source control resources that exist in a Subversion repository. Warning: The subversion resource has known bugs and may not work as expected. For more information see Chef GitHub issues, particularly [#4050](https://github.com/chef/chef/issues/4050) and [#4257](https://github.com/chef/chef/issues/4257)." examples <<~DOC **Get the latest version of an application** diff --git a/lib/chef/resource/sysctl.rb b/lib/chef/resource/sysctl.rb index 9c36206e14..8604590d46 100644 --- a/lib/chef/resource/sysctl.rb +++ b/lib/chef/resource/sysctl.rb @@ -131,7 +131,7 @@ class Chef end - action :apply, description: "Apply a sysctl value." do + action :apply, description: "Set the kernel parameter and update the `sysctl` settings." do converge_if_changed do # set it temporarily set_sysctl_param(new_resource.key, new_resource.value) @@ -150,7 +150,7 @@ class Chef end end - action :remove, description: "Remove a sysctl value." do + action :remove, description: "Remove the kernel parameter and update the `sysctl` settings." do # only converge the resource if the file actually exists to delete if ::File.exist?("#{new_resource.conf_dir}/99-chef-#{new_resource.key.tr("/", ".")}.conf") converge_by "removing sysctl config at #{new_resource.conf_dir}/99-chef-#{new_resource.key.tr("/", ".")}.conf" do diff --git a/lib/chef/resource/systemd_unit.rb b/lib/chef/resource/systemd_unit.rb index a100f29add..61294d833d 100644 --- a/lib/chef/resource/systemd_unit.rb +++ b/lib/chef/resource/systemd_unit.rb @@ -34,7 +34,7 @@ class Chef ```ruby systemd_unit 'etcd.service' do - content(Unit: { + content({ Unit: { Description: 'Etcd', Documentation: ['https://coreos.com/etcd', 'man:etcd(1)'], After: 'network.target', @@ -46,7 +46,7 @@ class Chef }, Install: { WantedBy: 'multi-user.target', - }) + } }) action [:create, :enable] end ``` diff --git a/lib/chef/resource/yum_package.rb b/lib/chef/resource/yum_package.rb index 53e02bf609..c8446bf9b0 100644 --- a/lib/chef/resource/yum_package.rb +++ b/lib/chef/resource/yum_package.rb @@ -27,11 +27,7 @@ class Chef provides :yum_package provides :package, platform_family: "fedora_derived" - description "Use the **yum_package** resource to install, upgrade, and remove packages with Yum"\ - " for the Red Hat and CentOS platforms. The yum_package resource is able to resolve"\ - " `provides` data for packages much like Yum can do when it is run from the command line."\ - " This allows a variety of options for installing packages, like minimum versions,"\ - " virtual provides, and library names." + description "Use the **yum_package** resource to install, upgrade, and remove packages with Yum for the Red Hat and CentOS platforms. The yum_package resource is able to resolve `provides` data for packages much like Yum can do when it is run from the command line. This allows a variety of options for installing packages, like minimum versions, virtual provides, and library names. Note: Support for using file names to install packages (as in `yum_package '/bin/sh'`) is not available because the volume of data required to parse for this is excessive." examples <<~DOC **Install an exact version**: |