diff options
-rw-r--r-- | lib/chef/provider/cron.rb | 4 | ||||
-rw-r--r-- | lib/chef/provider/directory.rb | 4 | ||||
-rw-r--r-- | lib/chef/provider/ifconfig.rb | 8 | ||||
-rw-r--r-- | lib/chef/provider/package.rb | 8 | ||||
-rw-r--r-- | lib/chef/resource/apt_package.rb | 4 | ||||
-rw-r--r-- | lib/chef/resource/chocolatey_package.rb | 6 | ||||
-rw-r--r-- | lib/chef/resource/cron/cron.rb | 77 | ||||
-rw-r--r-- | lib/chef/resource/cron/cron_d.rb | 3 | ||||
-rw-r--r-- | lib/chef/resource/windows_task.rb | 35 |
9 files changed, 120 insertions, 29 deletions
diff --git a/lib/chef/provider/cron.rb b/lib/chef/provider/cron.rb index 694f7ba4b8..29ecd4dd2a 100644 --- a/lib/chef/provider/cron.rb +++ b/lib/chef/provider/cron.rb @@ -92,7 +92,7 @@ class Chef end end - action :create do + action :create, description: "Create an entry in a cron table file (crontab). If an entry already exists (but does not match), update that entry to match." do crontab = "" newcron = "" cron_found = false @@ -149,7 +149,7 @@ class Chef end end - action :delete do + action :delete, description: "Delete an entry from a cron table file (crontab)." do if @cron_exists crontab = "" cron_found = false diff --git a/lib/chef/provider/directory.rb b/lib/chef/provider/directory.rb index 6a20556ccd..3e4107980c 100644 --- a/lib/chef/provider/directory.rb +++ b/lib/chef/provider/directory.rb @@ -121,7 +121,7 @@ class Chef end end - action :create do + action :create, description: "Create a directory. If a directory already exists (but does not match), update that directory to match." do unless ::File.exist?(new_resource.path) converge_by("create new directory #{new_resource.path}") do if new_resource.recursive == true @@ -137,7 +137,7 @@ class Chef load_resource_attributes_from_file(new_resource) unless Chef::Config[:why_run] end - action :delete do + action :delete, description: "Delete a directory." do if ::File.exist?(new_resource.path) converge_by("delete existing directory #{new_resource.path}") do if new_resource.recursive == true diff --git a/lib/chef/provider/ifconfig.rb b/lib/chef/provider/ifconfig.rb index 69d95b260c..63aa126c2e 100644 --- a/lib/chef/provider/ifconfig.rb +++ b/lib/chef/provider/ifconfig.rb @@ -168,7 +168,7 @@ class Chef end end - action :add do + action :add, description: "Run ifconfig to configure a network interface and (on some platforms) write a configuration file for that network interface." do # check to see if load_current_resource found interface in ifconfig unless current_resource.inet_addr unless new_resource.device == loopback_device @@ -183,7 +183,7 @@ class Chef generate_config end - action :enable do + action :enable, description: "Run ifconfig to enable a network interface." do # check to see if load_current_resource found ifconfig # enables, but does not manage config files return if current_resource.inet_addr @@ -196,7 +196,7 @@ class Chef end end - action :delete do + action :delete, description: "Run ifconfig to disable a network interface and (on some platforms) delete that network interface’s configuration file." do # check to see if load_current_resource found the interface if current_resource.device command = delete_command @@ -210,7 +210,7 @@ class Chef delete_config end - action :disable do + action :disable, description: "Run ifconfig to disable a network interface." do # check to see if load_current_resource found the interface # disables, but leaves config files in place. if current_resource.device diff --git a/lib/chef/provider/package.rb b/lib/chef/provider/package.rb index 82d7ed00cf..daf46c502e 100644 --- a/lib/chef/provider/package.rb +++ b/lib/chef/provider/package.rb @@ -107,7 +107,7 @@ class Chef end end - action :install do + action :install, description: "Install a package. If a version is specified, install the specified version of the package." do unless target_version_array.any? logger.debug("#{new_resource} is already installed - nothing to do") return @@ -136,7 +136,7 @@ class Chef private :install_description - action :upgrade do + action :upgrade, description: "Install a package and ensure that a package is the latest version." do unless target_version_array.any? logger.debug("#{new_resource} no versions to upgrade - nothing to do") return @@ -167,7 +167,7 @@ class Chef private :upgrade_description - action :remove do + action :remove, description: "Remove a package." do if removing_package? description = new_resource.version ? "version #{new_resource.version} of " : "" converge_by("remove #{description}package #{current_resource.package_name}") do @@ -202,7 +202,7 @@ class Chef end end - action :purge do + action :purge, description: "Purge a package. This action typically removes the configuration files as well as the package." do if removing_package? description = new_resource.version ? "version #{new_resource.version} of" : "" converge_by("purge #{description} package #{current_resource.package_name}") do diff --git a/lib/chef/resource/apt_package.rb b/lib/chef/resource/apt_package.rb index 331d411373..448ebce4e5 100644 --- a/lib/chef/resource/apt_package.rb +++ b/lib/chef/resource/apt_package.rb @@ -43,7 +43,7 @@ class Chef **Install multiple packages at once**: ```ruby - apt_package %(package1 package2 package3) + apt_package %w(package1 package2 package3) ``` **Install without using recommend packages as a dependency**: @@ -55,7 +55,7 @@ class Chef ``` DOC - description "Use the **apt_package** resource to manage packages on Debian and Ubuntu platforms." + description "Use the **apt_package** resource to manage packages on Debian, Ubuntu, and other platforms that use the APT package system." property :default_release, String, description: "The default release. For example: `stable`.", diff --git a/lib/chef/resource/chocolatey_package.rb b/lib/chef/resource/chocolatey_package.rb index e0568e586a..f7f221c025 100644 --- a/lib/chef/resource/chocolatey_package.rb +++ b/lib/chef/resource/chocolatey_package.rb @@ -25,7 +25,7 @@ class Chef provides :chocolatey_package - description "Use the **chocolatey_package** resource to manage packages using Chocolatey on the Microsoft Windows platform. Note: The Chocolatey package manager is not installed on Windows by default. You will need to install it prior to using this resource by adding the [Chocolatey cookbook](https://supermarket.chef.io/cookbooks/chocolatey/) to your node's run list." + description "Use the **chocolatey_package** resource to manage packages using the Chocolatey package manager on the Microsoft Windows platform. Note: The Chocolatey package manager is not installed on Windows by default. You will need to install it prior to using this resource by adding the [chocolatey cookbook](https://supermarket.chef.io/cookbooks/chocolatey/) to your node's run list. Warning: The **chocolatey_package** resource must be specified as `chocolatey_package` and cannot be shortened to `package` in a recipe." introduced "12.7" examples <<~DOC **Install a Chocolatey package**: @@ -73,9 +73,9 @@ class Chef coerce: proc { |x| [x].flatten } # In the choco if we have the feature useEnhancedExitCodes turned on, then choco will provide enhanced exit codes(2: no results). - # Choco exit codes https://chocolatey.org/docs/commandsinfo#exit-codes + # Choco exit codes https://docs.chocolatey.org/en-us/choco/commands/info#exit-codes property :returns, [Integer, Array], - description: "The exit code(s) returned a chocolatey package that indicate success.", + description: "The exit code(s) returned by the `choco` command that indicate a successful action. See [Chocolatey Exit Codes](https://docs.chocolatey.org/en-us/choco/commands/info#exit-codes) for a complete list of exit codes used by Chocolatey.", default: [ 0, 2 ], desired_state: false, introduced: "12.18" end diff --git a/lib/chef/resource/cron/cron.rb b/lib/chef/resource/cron/cron.rb index 31d6efcfde..1565cf9025 100644 --- a/lib/chef/resource/cron/cron.rb +++ b/lib/chef/resource/cron/cron.rb @@ -20,6 +20,7 @@ require_relative "../../resource" require_relative "../helpers/cron_validations" require_relative "../../provider/cron" # do not remove. we actually need this below +require "chef-utils/dist" unless defined?(ChefUtils::Dist) class Chef class Resource @@ -30,7 +31,81 @@ class Chef provides :cron - description "Use the **cron** resource to manage cron entries for time-based job scheduling. Properties for a schedule will default to * if not provided. The cron resource requires access to a crontab program, typically cron." + description "Use the **cron** resource to manage cron entries for time-based job scheduling. Properties for a schedule will default to * if not provided. The cron resource requires access to a crontab program, typically cron. Warning: The cron resource should only be used to modify an entry in a crontab file. The `cron_d` resource directly manages `cron.d` files. This resource ships in #{ChefUtils::Dist::Infra::PRODUCT} 14.4 or later and can also be found in the [cron](https://github.com/chef-cookbooks/cron) cookbook) for previous #{ChefUtils::Dist::Infra::PRODUCT} releases." + + examples <<~'DOC' + **Run a program at a specified interval** + + ```ruby + cron 'noop' do + hour '5' + minute '0' + command '/bin/true' + end + ``` + + **Run an entry if a folder exists** + + ```ruby + 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 { ::File.exist?('/home/jboss') } + end + ``` + + **Run every Saturday, 8:00 AM** + + The following example shows a schedule that will run every hour at 8:00 each Saturday morning, and will then send an email to “admin@example.com” after each run. + + ```ruby + cron 'name_of_cron_entry' do + minute '0' + hour '8' + weekday '6' + mailto 'admin@example.com' + action :create + end + ``` + + **Run once a week** + + ```ruby + cron 'cookbooks_report' do + minute '0' + hour '0' + weekday '1' + user 'chefio' + mailto 'sysadmin@example.com' + home '/srv/supermarket/shared/system' + command %W{ + cd /srv/supermarket/current && + env RUBYLIB="/srv/supermarket/current/lib" + RAILS_ASSET_ID=`git rev-parse HEAD` RAILS_ENV="#{rails_env}" + bundle exec rake cookbooks_report + }.join(' ') + action :create + end + ``` + + **Run only in November** + + The following example shows a schedule that will run at 8:00 PM, every weekday (Monday through Friday), but only in November: + + ```ruby + cron 'name_of_cron_entry' do + minute '0' + hour '20' + day '*' + month '11' + weekday '1-5' + action :create + end + ``` + DOC + state_attrs :minute, :hour, :day, :month, :weekday, :user diff --git a/lib/chef/resource/cron/cron_d.rb b/lib/chef/resource/cron/cron_d.rb index 2806f55415..dffe46bcec 100644 --- a/lib/chef/resource/cron/cron_d.rb +++ b/lib/chef/resource/cron/cron_d.rb @@ -18,6 +18,7 @@ require_relative "../../resource" require_relative "../helpers/cron_validations" require "shellwords" unless defined?(Shellwords) +require "chef-utils/dist" unless defined?(ChefUtils::Dist) class Chef class Resource @@ -29,7 +30,7 @@ class Chef provides :cron_d introduced "14.4" - description "Use the **cron_d** resource to manage cron job files in the `/etc/cron.d` directory. This is similar to the 'cron' resource, but it does not use the monolithic /etc/crontab file." + description "Use the **cron_d** resource to manage cron job files in the `/etc/cron.d` directory. Warning: #{ChefUtils::Dist::Infra::PRODUCT} also ships with the **cron** resource for managing the monolithic `/etc/crontab` file on platforms that lack cron.d support. See the [cron resource](/resources/cron/) for information on using that resource." examples <<~DOC **Run a program on the fifth hour of the day** diff --git a/lib/chef/resource/windows_task.rb b/lib/chef/resource/windows_task.rb index b1154a1f08..224e59204b 100644 --- a/lib/chef/resource/windows_task.rb +++ b/lib/chef/resource/windows_task.rb @@ -149,7 +149,6 @@ class Chef DOC allowed_actions :create, :delete, :run, :end, :enable, :disable, :change - default_action :create property :task_name, String, regex: [%r{\A[^/\:\*\?\<\>\|]+\z}], description: "An optional property to set the task name if it differs from the resource block's name. Example: `Task Name` or `/Task Name`", @@ -182,10 +181,19 @@ class Chef default: false property :frequency_modifier, [Integer, String], - default: 1 + default: 1, + description: <<~DOCS + * For frequency `:minute` valid values are 1 to 1439 + * For frequency `:hourly` valid values are 1 to 23 + * For frequency `:daily` valid values are 1 to 365 + * For frequency `:weekly` valid values are 1 to 52 + * For frequency `:monthly` valid values are `('FIRST', 'SECOND', 'THIRD', 'FOURTH', 'LAST')` OR `1-12`. + * e.g. If user want to run the task on `second week of the month` use `frequency_modifier` value as `SECOND`. Multiple values for weeks of the month should be comma separated e.g. `"FIRST, THIRD, LAST"`. + * To run task every (n) months use values 1 to 12. + DOCS property :frequency, Symbol, equal_to: %i{minute hourly daily weekly monthly once on_logon onstart on_idle none}, - description: "The frequency with which to run the task." + description: "The frequency with which to run the task. Note: This property is required in Chef Infra Client 14.1 or later. Note: The `:once` value requires the `start_time` property to be set." property :start_day, String, description: "Specifies the first date on which the task runs in **MM/DD/YYYY** format.", @@ -195,7 +203,14 @@ class Chef description: "Specifies the start time to run the task, in **HH:mm** format." property :day, [String, Integer], - description: "The day(s) on which the task runs." + description: <<~DOCS + The day(s) on which the task runs. + * Use this property when setting `frequency` to `:monthly` or `:weekly`. + * Valid values with frequency `:weekly` are `MON`-`SUN` or `*`. + * Valid values with frequency `:monthly` are `1-31`, `MON`-`SUN`, and `LASTDAY`. + * Use `MON`-`SUN` or `LASTDAY` if you are setting `frequency_modifier` as "FIRST, SECOND, THIRD etc." else use 1-31. + * Multiple days should be comma separated. e.g `1, 2, 3` or `MON, WED, FRI`. + DOCS property :months, String, description: "The Months of the year on which the task runs, such as: `JAN, FEB` or `*`. Multiple months should be comma delimited. e.g. `Jan, Feb, Mar, Dec`." @@ -961,7 +976,7 @@ class Chef end end - action :create do + action :create, description: "Creates a scheduled task, or updates an existing task if any property has changed." do set_command_and_arguments if new_resource.command if current_resource.exists @@ -998,7 +1013,7 @@ class Chef end end - action :run do + action :run, description: "Runs a scheduled task." do if current_resource.exists logger.trace "#{new_resource} task exists" if current_resource.task.status == "running" @@ -1013,7 +1028,7 @@ class Chef end end - action :delete do + action :delete, description: "Deletes a scheduled task." do if current_resource.exists logger.trace "#{new_resource} task exists" converge_by("delete scheduled task #{new_resource}") do @@ -1026,7 +1041,7 @@ class Chef end end - action :end do + action :end, description: "Ends a scheduled task." do if current_resource.exists logger.trace "#{new_resource} task exists" if current_resource.task.status != "running" @@ -1041,7 +1056,7 @@ class Chef end end - action :enable do + action :enable, description: "Enables a scheduled task." do if current_resource.exists logger.trace "#{new_resource} task exists" if current_resource.task.status == "not scheduled" @@ -1058,7 +1073,7 @@ class Chef end end - action :disable do + action :disable, description: "Disables a scheduled task." do if current_resource.exists logger.info "#{new_resource} task exists" if %w{ready running}.include?(current_resource.task.status) |