Class: Chef::Provider

Inherits:
Object
  • Object
show all
Extended by:
Mixin::Provides
Includes:
DSL::Core, Mixin::WhyRun
Defined in:
lib/chef/provider.rb,
lib/chef/provider/env.rb,
lib/chef/provider/git.rb,
lib/chef/provider/log.rb,
lib/chef/provider/cron.rb,
lib/chef/provider/file.rb,
lib/chef/provider/link.rb,
lib/chef/provider/noop.rb,
lib/chef/provider/ohai.rb,
lib/chef/provider/user.rb,
lib/chef/provider/batch.rb,
lib/chef/provider/group.rb,
lib/chef/provider/mdadm.rb,
lib/chef/provider/mount.rb,
lib/chef/provider/route.rb,
lib/chef/provider/deploy.rb,
lib/chef/provider/reboot.rb,
lib/chef/provider/script.rb,
lib/chef/provider/execute.rb,
lib/chef/provider/launchd.rb,
lib/chef/provider/package.rb,
lib/chef/provider/service.rb,
lib/chef/provider/user/pw.rb,
lib/chef/provider/cron/aix.rb,
lib/chef/provider/erl_call.rb,
lib/chef/provider/group/pw.rb,
lib/chef/provider/ifconfig.rb,
lib/chef/provider/template.rb,
lib/chef/provider/user/aix.rb,
lib/chef/provider/cron/unix.rb,
lib/chef/provider/directory.rb,
lib/chef/provider/group/aix.rb,
lib/chef/provider/lwrp_base.rb,
lib/chef/provider/mount/aix.rb,
lib/chef/provider/user/dscl.rb,
lib/chef/provider/apt_update.rb,
lib/chef/provider/dsc_script.rb,
lib/chef/provider/group/dscl.rb,
lib/chef/provider/group/suse.rb,
lib/chef/provider/ruby_block.rb,
lib/chef/provider/subversion.rb,
lib/chef/provider/user/linux.rb,
lib/chef/provider/env/windows.rb,
lib/chef/provider/mount/mount.rb,
lib/chef/provider/osx_profile.rb,
lib/chef/provider/package/aix.rb,
lib/chef/provider/package/apt.rb,
lib/chef/provider/package/cab.rb,
lib/chef/provider/package/dnf.rb,
lib/chef/provider/package/ips.rb,
lib/chef/provider/package/msu.rb,
lib/chef/provider/package/rpm.rb,
lib/chef/provider/package/yum.rb,
lib/chef/provider/remote_file.rb,
lib/chef/provider/service/aix.rb,
lib/chef/provider/dsc_resource.rb,
lib/chef/provider/file/content.rb,
lib/chef/provider/http_request.rb,
lib/chef/provider/ifconfig/aix.rb,
lib/chef/provider/package/dpkg.rb,
lib/chef/provider/registry_key.rb,
lib/chef/provider/service/init.rb,
lib/chef/provider/systemd_unit.rb,
lib/chef/provider/user/solaris.rb,
lib/chef/provider/user/useradd.rb,
lib/chef/provider/user/windows.rb,
lib/chef/provider/windows_task.rb,
lib/chef/provider/cookbook_file.rb,
lib/chef/provider/group/gpasswd.rb,
lib/chef/provider/group/usermod.rb,
lib/chef/provider/group/windows.rb,
lib/chef/provider/mount/solaris.rb,
lib/chef/provider/mount/windows.rb,
lib/chef/provider/apt_repository.rb,
lib/chef/provider/group/groupadd.rb,
lib/chef/provider/group/groupmod.rb,
lib/chef/provider/package/pacman.rb,
lib/chef/provider/package/zypper.rb,
lib/chef/provider/service/debian.rb,
lib/chef/provider/service/macosx.rb,
lib/chef/provider/service/redhat.rb,
lib/chef/provider/service/simple.rb,
lib/chef/provider/windows_script.rb,
lib/chef/provider/yum_repository.rb,
lib/chef/provider/deploy/revision.rb,
lib/chef/provider/ifconfig/debian.rb,
lib/chef/provider/ifconfig/redhat.rb,
lib/chef/provider/package/openbsd.rb,
lib/chef/provider/package/paludis.rb,
lib/chef/provider/package/portage.rb,
lib/chef/provider/package/smartos.rb,
lib/chef/provider/package/solaris.rb,
lib/chef/provider/package/windows.rb,
lib/chef/provider/remote_file/ftp.rb,
lib/chef/provider/resource_update.rb,
lib/chef/provider/service/aixinit.rb,
lib/chef/provider/service/freebsd.rb,
lib/chef/provider/service/insserv.rb,
lib/chef/provider/service/openbsd.rb,
lib/chef/provider/service/solaris.rb,
lib/chef/provider/service/upstart.rb,
lib/chef/provider/template_finder.rb,
lib/chef/provider/package/homebrew.rb,
lib/chef/provider/package/macports.rb,
lib/chef/provider/package/rubygems.rb,
lib/chef/provider/remote_directory.rb,
lib/chef/provider/remote_file/http.rb,
lib/chef/provider/remote_file/sftp.rb,
lib/chef/provider/template/content.rb,
lib/chef/provider/powershell_script.rb,
lib/chef/provider/service/invokercd.rb,
lib/chef/provider/deploy/timestamped.rb,
lib/chef/provider/package/chocolatey.rb,
lib/chef/provider/package/powershell.rb,
lib/chef/provider/package/dnf/version.rb,
lib/chef/provider/package/freebsd/pkg.rb,
lib/chef/provider/package/windows/exe.rb,
lib/chef/provider/package/windows/msi.rb,
lib/chef/provider/remote_file/content.rb,
lib/chef/provider/remote_file/fetcher.rb,
lib/chef/provider/package/freebsd/base.rb,
lib/chef/provider/package/freebsd/port.rb,
lib/chef/provider/cookbook_file/content.rb,
lib/chef/provider/package/freebsd/pkgng.rb,
lib/chef/provider/package/yum/rpm_utils.rb,
lib/chef/provider/package/yum/yum_cache.rb,
lib/chef/provider/remote_file/local_file.rb,
lib/chef/provider/whyrun_safe_ruby_block.rb,
lib/chef/provider/remote_file/network_file.rb,
lib/chef/provider/package/dnf/python_helper.rb,
lib/chef/provider/remote_file/cache_control_data.rb,
lib/chef/provider/package/windows/registry_uninstall_entry.rb

Defined Under Namespace

Classes: AptRepository, AptUpdate, Batch, CookbookFile, Cron, Deploy, Directory, DscResource, DscScript, Env, ErlCall, Execute, File, Git, Group, HttpRequest, Ifconfig, LWRPBase, Launchd, Link, Log, Mdadm, Mount, Noop, Ohai, OsxProfile, Package, PowershellScript, Reboot, RegistryKey, RemoteDirectory, RemoteFile, ResourceUpdate, Route, RubyBlock, Script, Service, Subversion, SystemdUnit, Template, TemplateFinder, User, WhyrunSafeRubyBlock, WindowsScript, WindowsTask, YumRepository

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Mixin::Provides

provided_as, provides, provides?

Methods included from Mixin::DescendantsTracker

#descendants, descendants, #direct_descendants, direct_descendants, #find_descendants_by_name, find_descendants_by_name, #inherited, store_inherited

Methods included from Mixin::LazyModuleInclude

#descendants, #include, #included

Methods included from Mixin::NotifyingBlock

#notifying_block, #subcontext_block

Methods included from DSL::DeclareResource

#build_resource, #declare_resource, #delete_resource, #delete_resource!, #edit_resource, #edit_resource!, #find_resource, #find_resource!, #with_run_context

Methods included from Mixin::ShellOut

#a_to_s, #clean_array, #shell_out, #shell_out!, #shell_out_compact, #shell_out_compact!, #shell_out_compact_timeout, #shell_out_compact_timeout!, #shell_out_with_systems_locale, #shell_out_with_systems_locale!

Methods included from Mixin::PathSanity

#enforce_path_sanity, #sanitized_path

Methods included from Mixin::PowershellOut

#powershell_out, #powershell_out!

Methods included from Mixin::WindowsArchitectureHelper

#assert_valid_windows_architecture!, #disable_wow64_file_redirection, #forced_32bit_override_required?, #is_i386_process_on_x86_64_windows?, #node_supports_windows_architecture?, #node_windows_architecture, #restore_wow64_file_redirection, #valid_windows_architecture?, #with_os_architecture, #wow64_architecture_override_required?, #wow64_directory

Methods included from DSL::PlatformIntrospection

#docker?, #platform?, #platform_family?, #value_for_platform, #value_for_platform_family

Constructor Details

#initialize(new_resource, run_context) ⇒ Provider

Returns a new instance of Provider.


87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/chef/provider.rb', line 87

def initialize(new_resource, run_context)
  @new_resource = new_resource
  @action = action
  @current_resource = nil
  @run_context = run_context
  @converge_actions = nil

  @recipe_name = nil
  @cookbook_name = nil
  self.class.include_resource_dsl_module(new_resource)
end

Instance Attribute Details

#action ⇒ Object

-- TODO: this should be a reader, and the action should be passed in the constructor; however, many/most subclasses override the constructor so changing the arity would be a breaking change. Change this at the next break, e.g., Chef 11.


85
86
87
 
# File 'lib/chef/provider.rb', line 85

def action
  @action
end

#cookbook_name ⇒ Object (readonly)

Returns the value of attribute cookbook_name


41
42
43
 
# File 'lib/chef/provider.rb', line 41

def cookbook_name
  @cookbook_name
end

#current_resource ⇒ Object

Returns the value of attribute current_resource


37
38
39
 
# File 'lib/chef/provider.rb', line 37

def current_resource
  @current_resource
end

#new_resource ⇒ Object

Returns the value of attribute new_resource


36
37
38
 
# File 'lib/chef/provider.rb', line 36

def new_resource
  @new_resource
end

#recipe_name ⇒ Object (readonly)

Returns the value of attribute recipe_name


40
41
42
 
# File 'lib/chef/provider.rb', line 40

def recipe_name
  @recipe_name
end

#run_context ⇒ Object

Returns the value of attribute run_context


38
39
40
 
# File 'lib/chef/provider.rb', line 38

def run_context
  @run_context
end

Class Method Details

.action(name, &block) ⇒ void

This method returns an undefined value.

Defines an action method on the provider, running the block to compile the resources, converging them, and then checking if any were updated (and updating new-resource if so)

Parameters:

  • name (String, Symbol) —

    Name of the action to define.

  • block (Proc) —

    Body of the action.

Since:

  • 13.0


62
63
64
65
66
67
68
69
70
 
# File 'lib/chef/provider.rb', line 62

def self.action(name, &block)
  # We need the block directly in a method so that `super` works.
  define_method("compile_action_#{name}", &block)
  class_eval <<-EOM
    def action_#{name}
      compile_and_converge_action { compile_action_#{name} }
    end
  EOM
end

.include_resource_dsl? ⇒ Boolean

Include attributes, public and protected methods from this Resource in the provider.

If this is set to true, delegate methods are included in the provider so that you can call (for example) attrname and it will call new_resource.attrname.

The actual include does not happen until the first time the Provider is instantiated (so that we don't have to worry about load order issues).

Parameters:

  • include_resource_dsl (Boolean) —

    Whether to include resource DSL or not (defaults to false).

Returns:

  • (Boolean) 

312
313
314
 
# File 'lib/chef/provider.rb', line 312

def self.include_resource_dsl?
  false
end

.include_resource_dsl_module(resource) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Create the resource DSL module that forwards resource methods to new_resource


319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
 
# File 'lib/chef/provider.rb', line 319

def self.include_resource_dsl_module(resource)
  if include_resource_dsl? && !defined?(@included_resource_dsl_module)
    provider_class = self
    @included_resource_dsl_module = Module.new do
      extend Forwardable
      define_singleton_method(:to_s) { "forwarder module for #{provider_class}" }
      define_singleton_method(:inspect) { to_s }
      # Add a delegator for each explicit property that will get the *current* value
      # of the property by default instead of the *actual* value.
      resource.class.properties.each do |name, property|
        class_eval(<<-EOM, __FILE__, __LINE__)
          def #{name}(*args, &block)
            # If no arguments were passed, we process "get" by defaulting
            # the value to current_resource, not new_resource. This helps
            # avoid issues where resources accidentally overwrite perfectly
            # valid stuff with default values.
            #
            # This magic is to make this kind of thing easy:
            #
            # FileUtils.chown new_resource.mode.nil? ? current_resource.mode : new_resource.mode, new_resource.path
            #
            # We do this in the file provider where we need to construct a new filesystem object and
            # when the new_resource is nil/default that means "preserve the current stuff" and does not
            # mean to ignore it which will wind up defaulting to changing the file to have a "root"
            # ownership if anything else changes.  Its kind of overly clever and magical, and most likely
            # gets the use case wrong where someone has a property that they really mean to default to
            # some value which /should/ get set if its left as the default and where the default is
            # meant to be declarative.  Instead of property_is_set? we should most likely be using
            # nil? but we're going to deprecate all of it anyway.  Just type out what you really mean longhand.
            #
            if args.empty? && !block
              if !new_resource.property_is_set?(__method__) && current_resource
                Chef.deprecated(:namespace_collisions, "rename #{name} to current_resource.#{name}")
                return current_resource.public_send(__method__)
              end
            end
            Chef.deprecated(:namespace_collisions, "rename #{name} to new_resource.#{name}")
            new_resource.public_send(__method__, *args, &block)
          end
        EOM
      end
      dsl_methods =
        resource.class.public_instance_methods +
        resource.class.protected_instance_methods -
        provider_class.instance_methods -
        resource.class.properties.keys
      def_delegators(:new_resource, *dsl_methods)
    end
    include @included_resource_dsl_module
  end
end

.provides(short_name, opts = {}, &block) ⇒ Object 


290
291
292
 
# File 'lib/chef/provider.rb', line 290

def self.provides(short_name, opts = {}, &block)
  Chef.provider_handler_map.set(short_name, self, opts, &block)
end

.provides?(node, resource) ⇒ Boolean

Returns:

  • (Boolean) 

294
295
296
 
# File 'lib/chef/provider.rb', line 294

def self.provides?(node, resource)
  Chef::ProviderResolver.new(node, resource, :nothing).provided_by?(self)
end

.supports?(resource, action) ⇒ Boolean

supports the given resource and action (late binding)

Returns:

  • (Boolean) 

50
51
52
 
# File 'lib/chef/provider.rb', line 50

def self.supports?(resource, action)
  true
end

.use_inline_resources ⇒ void

This method returns an undefined value.

Deprecation stub for the old use_inline_resources mode.


75
76
77
78
 
# File 'lib/chef/provider.rb', line 75

def self.use_inline_resources
  # Uncomment this in Chef 13.6.
  # Chef.deprecated(:use_inline_resources, "The use_inline_resources mode is no longer optional and the line enabling it can be removed")
end

Instance Method Details

#action_nothing ⇒ Object 


133
134
135
136
 
# File 'lib/chef/provider.rb', line 133

def action_nothing
  Chef::Log.debug("Doing nothing for #{@new_resource}")
  true
end

#check_resource_semantics! ⇒ Object 


120
121
 
# File 'lib/chef/provider.rb', line 120

def check_resource_semantics!
end

#cleanup_after_converge ⇒ Object 


130
131
 
# File 'lib/chef/provider.rb', line 130

def cleanup_after_converge
end

#compile_and_converge_action(&block) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Create a child run_context, compile the block, and converge it.


208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/chef/provider.rb', line 208

def compile_and_converge_action(&block)
  old_run_context = run_context
  @run_context = run_context.create_child
  return_value = instance_eval(&block)
  Chef::Runner.new(run_context).converge
  return_value
ensure
  if run_context.resource_collection.any? { |r| r.updated? }
    new_resource.updated_by_last_action(true)
  end
  @run_context = old_run_context
end

#converge_by(descriptions, &block) ⇒ Object 


201
202
203
 
# File 'lib/chef/provider.rb', line 201

def converge_by(descriptions, &block)
  converge_actions.add_action(descriptions, &block)
end

#converge_if_changed(*properties, &converge_block) ⇒ Boolean

Handle patchy convergence safely.

  • Does not call the block if the current_resource's properties match the properties the user specified on the resource.
  • Calls the block if current_resource does not exist
  • Calls the block if the user has specified any properties in the resource whose values are different from current_resource.
  • Does not call the block if why-run is enabled (just prints out text).
  • Prints out automatic green text saying what properties have changed.

Parameters:

  • properties —

    An optional list of property names (symbols). If not specified, new_resource.class.state_properties will be used.

  • converge_block —

    The block to do the converging in.

Returns:

  • (Boolean) —

    whether the block was executed.


238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
 
# File 'lib/chef/provider.rb', line 238

def converge_if_changed(*properties, &converge_block)
  if !converge_block
    raise ArgumentError, "converge_if_changed must be passed a block!"
  end

  properties = new_resource.class.state_properties.map { |p| p.name } if properties.empty?
  properties = properties.map { |p| p.to_sym }
  if current_resource
    # Collect the list of modified properties
    specified_properties = properties.select { |property| new_resource.property_is_set?(property) }
    modified = specified_properties.select { |p| new_resource.send(p) != current_resource.send(p) }
    if modified.empty?
      properties_str = if new_resource.sensitive
                         specified_properties.join(", ")
                       else
                         specified_properties.map { |p| "#{p}=#{new_resource.send(p).inspect}" }.join(", ")
                       end
      Chef::Log.debug("Skipping update of #{new_resource}: has not changed any of the specified properties #{properties_str}.")
      return false
    end

    # Print the pretty green text and run the block
    property_size = modified.map { |p| p.size }.max
    modified.map! do |p|
      properties_str = if new_resource.sensitive
                         "(suppressed sensitive property)"
                       else
                         "#{new_resource.send(p).inspect} (was #{current_resource.send(p).inspect})"
                       end
      "  set #{p.to_s.ljust(property_size)} to #{properties_str}"
    end
    converge_by([ "update #{current_resource.identity}" ] + modified, &converge_block)

  else
    # The resource doesn't exist. Mark that we are *creating* this, and
    # write down any properties we are setting.
    property_size = properties.map { |p| p.size }.max
    created = properties.map do |property|
      default = " (default value)" unless new_resource.property_is_set?(property)
      properties_str = if new_resource.sensitive
                         "(suppressed sensitive property)"
                       else
                         new_resource.send(property).inspect
                       end
      "  set #{property.to_s.ljust(property_size)} to #{properties_str}#{default}"
    end

    converge_by([ "create #{new_resource.identity}" ] + created, &converge_block)
  end
  true
end

#define_resource_requirements ⇒ Object 


127
128
 
# File 'lib/chef/provider.rb', line 127

def define_resource_requirements
end

#events ⇒ Object 


138
139
140
 
# File 'lib/chef/provider.rb', line 138

def events
  run_context.events
end

#load_current_resource ⇒ Object

Raises:


123
124
125
 
# File 'lib/chef/provider.rb', line 123

def load_current_resource
  raise Chef::Exceptions::Override, "You must override load_current_resource in #{self}"
end

#node ⇒ Object 


107
108
109
 
# File 'lib/chef/provider.rb', line 107

def node
  run_context && run_context.node
end

#process_resource_requirements ⇒ Object 


179
180
181
182
 
# File 'lib/chef/provider.rb', line 179

def process_resource_requirements
  requirements.run(:all_actions) unless @action == :nothing
  requirements.run(@action)
end

#requirements ⇒ Object 


197
198
199
 
# File 'lib/chef/provider.rb', line 197

def requirements
  @requirements ||= ResourceRequirements.new(@new_resource, run_context)
end

#resource_collection ⇒ Object

Used by providers supporting embedded recipes


112
113
114
 
# File 'lib/chef/provider.rb', line 112

def resource_collection
  run_context && run_context.resource_collection
end

#resource_updated? ⇒ Boolean

Returns:

  • (Boolean) 

184
185
186
 
# File 'lib/chef/provider.rb', line 184

def resource_updated?
  !converge_actions.empty? || @new_resource.updated_by_last_action?
end

#run_action(action = nil) ⇒ Object 


142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/chef/provider.rb', line 142

def run_action(action = nil)
  @action = action unless action.nil?

  # TODO: it would be preferable to get the action to be executed in the
  # constructor...

  check_resource_semantics!

  # user-defined LWRPs may include unsafe load_current_resource methods that cannot be run in whyrun mode
  if whyrun_mode? && !whyrun_supported?
    events.resource_current_state_load_bypassed(@new_resource, @action, @current_resource)
  else
    load_current_resource
    events.resource_current_state_loaded(@new_resource, @action, @current_resource)
  end

  define_resource_requirements
  process_resource_requirements

  # user-defined providers including LWRPs may
  # not include whyrun support - if they don't support it
  # we can't execute any actions while we're running in
  # whyrun mode. Instead we 'fake' whyrun by documenting that
  # we can't execute the action.
  # in non-whyrun mode, this will still cause the action to be
  # executed normally.
  if whyrun_mode? && (!whyrun_supported? || requirements.action_blocked?(@action))
    events.resource_bypassed(@new_resource, @action, self)
  else
    send("action_#{@action}")
  end

  set_updated_status

  cleanup_after_converge
end

#set_updated_status ⇒ Object 


188
189
190
191
192
193
194
195
 
# File 'lib/chef/provider.rb', line 188

def set_updated_status
  if !resource_updated?
    events.resource_up_to_date(@new_resource, @action)
  else
    events.resource_updated(@new_resource, @action)
    new_resource.updated_by_last_action(true)
  end
end

#whyrun_mode? ⇒ Boolean

Returns:

  • (Boolean) 

99
100
101
 
# File 'lib/chef/provider.rb', line 99

def whyrun_mode?
  Chef::Config[:why_run]
end

#whyrun_supported? ⇒ Boolean

Returns:

  • (Boolean) 

103
104
105
 
# File 'lib/chef/provider.rb', line 103

def whyrun_supported?
  true
end