diff options
author | Tim Smith <tsmith@chef.io> | 2020-10-28 16:49:44 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-10-28 16:49:44 -0700 |
commit | c7e3f36fb9ddd861e77c9300c7f61512e51e2b16 (patch) | |
tree | b8b928ccccf5841b218ef2973698eac5013abb3e | |
parent | cf5bd6fafd36240294976f653790d230b24d7fd4 (diff) | |
parent | e219b5c5d52db3bde5d5c939263cf50026d28540 (diff) | |
download | chef-c7e3f36fb9ddd861e77c9300c7f61512e51e2b16.tar.gz |
Merge pull request #10570 from chef/resource_docs
Signed-off-by: Tim Smith <tsmith@chef.io>
-rw-r--r-- | lib/chef/resource/scm/_scm.rb | 3 | ||||
-rw-r--r-- | lib/chef/resource/scm/git.rb | 83 | ||||
-rw-r--r-- | lib/chef/resource/scm/subversion.rb | 12 | ||||
-rw-r--r-- | lib/chef/resource/systemd_unit.rb | 41 | ||||
-rw-r--r-- | lib/chef/resource/windows_service.rb | 108 | ||||
-rw-r--r-- | lib/chef/resource/windows_task.rb | 3 |
6 files changed, 247 insertions, 3 deletions
diff --git a/lib/chef/resource/scm/_scm.rb b/lib/chef/resource/scm/_scm.rb index c939246ba1..573d8b9b94 100644 --- a/lib/chef/resource/scm/_scm.rb +++ b/lib/chef/resource/scm/_scm.rb @@ -33,7 +33,8 @@ property :revision, String, default: "HEAD" property :user, [String, Integer], - description: "The system user that will own the checked-out code." + description: "The system user that will own the checked-out code.", + default_description: "`HOME` environment variable of the user running #{ChefUtils::Dist::Infra::CLIENT}" property :group, [String, Integer], description: "The system group that will own the checked-out code." diff --git a/lib/chef/resource/scm/git.rb b/lib/chef/resource/scm/git.rb index b8c8f06347..53f1a1f44a 100644 --- a/lib/chef/resource/scm/git.rb +++ b/lib/chef/resource/scm/git.rb @@ -28,6 +28,87 @@ class Chef provides :git description "Use the **git** resource to manage source control resources that exist in a git repository. git version 1.6.5 (or higher) is required to use all of the functionality in the git resource." + examples <<~DOC + **Use the git mirror** + + ```ruby + git '/opt/mysources/couch' do + repository 'git://git.apache.org/couchdb.git' + revision 'master' + action :sync + end + ``` + + **Use different branches** + + To use different branches, depending on the environment of the node: + + ```ruby + branch_name = if node.chef_environment == 'QA' + 'staging' + else + 'master' + end + + git '/home/user/deployment' do + repository 'git@github.com:gitsite/deployment.git' + revision branch_name + action :sync + user 'user' + group 'test' + end + ``` + + Where the `branch_name` variable is set to staging or master, depending on the environment of the node. Once this is determined, the `branch_name` variable is used to set the revision for the repository. If the git status command is used after running the example above, it will return the branch name as `deploy`, as this is the default value. Run Chef Infra Client in debug mode to verify that the correct branches are being checked out: + + ``` + sudo chef-client -l debug + ``` + + **Install an application from git using bash** + + The following example shows how Bash can be used to install a plug-in for rbenv named ruby-build, which is located in git version source control. First, the application is synchronized, and then Bash changes its working directory to the location in which ruby-build is located, and then runs a command. + + ```ruby + git "#{Chef::Config[:file_cache_path]}/ruby-build" do + repository 'git://github.com/sstephenson/ruby-build.git' + revision 'master' + action :sync + end + + bash 'install_ruby_build' do + cwd "#{Chef::Config[:file_cache_path]}/ruby-build" + user 'rbenv' + group 'rbenv' + code <<-EOH + ./install.sh + EOH + environment 'PREFIX' => '/usr/local' + end + ``` + + **Notify a resource post-checkout** + + ```ruby + git "#{Chef::Config[:file_cache_path]}/libvpx" do + repository node[:libvpx][:git_repository] + revision node[:libvpx][:git_revision] + action :sync + notifies :run, 'bash[compile_libvpx]', :immediately + end + ``` + + **Pass in environment variables** + + ```ruby + git '/opt/mysources/couch' do + repository 'git://git.apache.org/couchdb.git' + revision 'master' + environment 'VAR' => 'whatever' + action :sync + end + ``` + DOC property :additional_remotes, Hash, description: "A Hash of additional remotes that are added to the git repository configuration.", @@ -41,7 +122,7 @@ class Chef default: false property :enable_checkout, [TrueClass, FalseClass], - description: "Check out a repo from master. Set to false when using the checkout_branch attribute to prevent the git resource from attempting to check out master from master.", + description: "Check out a repo from master. Set to `false` when using the `checkout_branch` attribute to prevent the git resource from attempting to check out `master` from `master`.", default: true property :remote, String, diff --git a/lib/chef/resource/scm/subversion.rb b/lib/chef/resource/scm/subversion.rb index f5637b04ad..8399225fdf 100644 --- a/lib/chef/resource/scm/subversion.rb +++ b/lib/chef/resource/scm/subversion.rb @@ -29,6 +29,18 @@ class Chef provides :subversion description "Use the **subversion** resource to manage source control resources that exist in a Subversion repository." + examples <<~DOC + **Get the latest version of an application** + + ```ruby + subversion 'CouchDB Edge' do + repository 'http://svn.apache.org/repos/asf/couchdb/trunk' + revision 'HEAD' + destination '/opt/mysources/couch' + action :sync + end + ``` + DOC allowed_actions :force_export diff --git a/lib/chef/resource/systemd_unit.rb b/lib/chef/resource/systemd_unit.rb index fc9aa4d40f..b028214441 100644 --- a/lib/chef/resource/systemd_unit.rb +++ b/lib/chef/resource/systemd_unit.rb @@ -29,6 +29,47 @@ class Chef description "Use the **systemd_unit** resource to create, manage, and run [systemd units](https://www.freedesktop.org/software/systemd/man/systemd.html#Concepts)." introduced "12.11" + examples <<~DOC + **Create systemd service unit file from a Hash** + + ```ruby + systemd_unit 'etcd.service' do + content({Unit: { + Description: 'Etcd', + Documentation: ['https://coreos.com/etcd', 'man:etcd(1)'], + After: 'network.target', + }, + Service: { + Type: 'notify', + ExecStart: '/usr/local/etcd', + Restart: 'always', + }, + Install: { + WantedBy: 'multi-user.target', + }}) + action [:create, :enable] + end + ``` + + **Create systemd service unit file from a String** + + ```ruby + systemd_unit 'sysstat-collect.timer' do + content <<~EOU + [Unit] + Description=Run system activity accounting tool every 10 minutes + + [Timer] + OnCalendar=*:00/10 + + [Install] + WantedBy=sysstat.service + EOU + + action [:create, :enable] + end + ``` + DOC default_action :nothing allowed_actions :create, :delete, diff --git a/lib/chef/resource/windows_service.rb b/lib/chef/resource/windows_service.rb index 0fa007497b..5920f61011 100644 --- a/lib/chef/resource/windows_service.rb +++ b/lib/chef/resource/windows_service.rb @@ -39,6 +39,114 @@ class Chef description "Use the **windows_service** resource to create, delete, or manage a service on the Microsoft Windows platform." introduced "12.0" + examples <<~DOC + **Starting Services** + + Start a service with a `manual` startup type: + + ```ruby + windows_service 'BITS' do + action :configure_startup + startup_type :manual + end + ``` + + **Creating Services** + + Create a service named chef-client: + + ```ruby + windows_service 'chef-client' do + action :create + binary_path_name "C:\\opscode\\chef\\bin" + end + ``` + + Create a service with `service_name` and `display_name`: + + ```ruby + windows_service 'Setup chef-client as a service' do + action :create + display_name 'CHEF-CLIENT' + service_name 'chef-client' + binary_path_name "C:\\opscode\\chef\\bin" + end + ``` + + Create a service with the `manual` startup type: + + ```ruby + windows_service 'chef-client' do + action :create + binary_path_name "C:\\opscode\\chef\\bin" + startup_type :manual + end + ``` + + Create a service with the `disabled` startup type: + + ```ruby + windows_service 'chef-client' do + action :create + binary_path_name "C:\\opscode\\chef\\bin" + startup_type :disabled + end + ``` + + Create a service with the `automatic` startup type and delayed start enabled: + + ```ruby + windows_service 'chef-client' do + action :create + binary_path_name "C:\\opscode\\chef\\bin" + startup_type :automatic + delayed_start true + end + ``` + + Create a service with a description: + + ```ruby + windows_service 'chef-client' do + action :create + binary_path_name "C:\\opscode\\chef\\bin" + startup_type :automatic + description "Chef client as service" + end + ``` + + **Deleting Services** + + Delete a service named chef-client: + + ```ruby + windows_service 'chef-client' do + action :delete + end + ``` + + Delete a service with the `service_name` property: + + ```ruby + windows_service 'Delete chef client' do + action :delete + service_name 'chef-client' + end + ``` + + **Configuring Services** + + Change an existing service from automatic to manual startup: + + ```ruby + windows_service 'chef-client' do + action :configure + binary_path_name "C:\\opscode\\chef\\bin" + startup_type :manual + end + ``` + DOC + allowed_actions :configure_startup, :create, :delete, :configure diff --git a/lib/chef/resource/windows_task.rb b/lib/chef/resource/windows_task.rb index cc2c80d4c6..29bade29ce 100644 --- a/lib/chef/resource/windows_task.rb +++ b/lib/chef/resource/windows_task.rb @@ -75,7 +75,7 @@ class Chef command 'chef-client' run_level :highest frequency :once - start_time "16:10" + start_time '16:10' end ``` @@ -115,6 +115,7 @@ class Chef ``` **Create a scheduled task to run when computer is idle with idle duration 20 min**: + ```ruby windows_task 'chef-client' do command 'chef-client' |