Class: Chef::Provider

Inherits:
Object
  • Object
show all
Extended by:
Mixin::Provides, DeprecatedLWRPClass
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/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/breakpoint.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/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/ips.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/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/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/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/easy_install.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/remote_file/cache_control_data.rb,
lib/chef/provider/package/windows/registry_uninstall_entry.rb

Defined Under Namespace

Modules: DeprecatedLWRPClass, InlineResources Classes: AptRepository, AptUpdate, Batch, Breakpoint, 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

Constant Summary

Constants included from Mixin::ShellOut

Mixin::ShellOut::DEPRECATED_OPTIONS

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 DeprecatedLWRPClass

const_missing, deprecated_constants, register_deprecated_lwrp_class

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

#run_command_compatible_options, #shell_out, #shell_out!, #shell_out_with_systems_locale, #shell_out_with_systems_locale!

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.



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

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.



59
60
61
 
# File 'lib/chef/provider.rb', line 59

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

.include_resource_dsl(include_resource_dsl) ⇒ Object

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`).



270
271
272
 
# File 'lib/chef/provider.rb', line 270

def self.include_resource_dsl(include_resource_dsl)
  @include_resource_dsl = include_resource_dsl
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



277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
 
# File 'lib/chef/provider.rb', line 277

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.
            if args.empty? && !block
              if !new_resource.property_is_set?(__method__) && current_resource
                return current_resource.public_send(__method__)
              end
            end
            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 



248
249
250
 
# File 'lib/chef/provider.rb', line 248

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

.provides?(node, resource) ⇒ Boolean

Returns:

  • (Boolean) 


252
253
254
 
# File 'lib/chef/provider.rb', line 252

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 ⇒ Object

Enables inline evaluation of resources in provider actions.

Without this option, any resources declared inside the Provider are added to the resource collection after the current position at the time the action is executed. Because they are added to the primary resource collection for the chef run, they can notify other resources outside the Provider, and potentially be notified by resources outside the Provider (but this is complicated by the fact that they don’t exist until the provider executes). In this mode, it is impossible to correctly set the updated_by_last_action flag on the parent Provider resource, since it executes and returns before its component resources are run.

With this option enabled, each action creates a temporary run_context with its own resource collection, evaluates the action’s code in that context, and then converges the resources created. If any resources were updated, then this provider’s new_resource will be marked updated.

In this mode, resources created within the Provider cannot interact with external resources via notifies, though notifications to other resources within the Provider will work. Delayed notifications are executed at the conclusion of the provider’s action, not at the end of the main chef run.

This mode of evaluation is experimental, but is believed to be a better set of tradeoffs than the append-after mode, so it will likely become the default in a future major release of Chef.



340
341
342
343
 
# File 'lib/chef/provider.rb', line 340

def self.use_inline_resources
  extend InlineResources::ClassMethods
  include InlineResources
end

Instance Method Details

#action_nothing ⇒ Object 



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

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

#check_resource_semantics! ⇒ Object 



94
95
 
# File 'lib/chef/provider.rb', line 94

def check_resource_semantics!
end

#cleanup_after_converge ⇒ Object 



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

def cleanup_after_converge
end

#converge_by(descriptions, &block) ⇒ Object 



175
176
177
 
# File 'lib/chef/provider.rb', line 175

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.



196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
 
# File 'lib/chef/provider.rb', line 196

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 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 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 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 



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

def define_resource_requirements
end

#events ⇒ Object 



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

def events
  run_context.events
end

#load_current_resource ⇒ Object

Raises:



97
98
99
 
# File 'lib/chef/provider.rb', line 97

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

#node ⇒ Object 



81
82
83
 
# File 'lib/chef/provider.rb', line 81

def node
  run_context && run_context.node
end

#process_resource_requirements ⇒ Object 



153
154
155
156
 
# File 'lib/chef/provider.rb', line 153

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

#requirements ⇒ Object 



171
172
173
 
# File 'lib/chef/provider.rb', line 171

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

#resource_collection ⇒ Object

Used by providers supporting embedded recipes



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

def resource_collection
  run_context && run_context.resource_collection
end

#resource_updated? ⇒ Boolean

Returns:

  • (Boolean) 


158
159
160
 
# File 'lib/chef/provider.rb', line 158

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

#run_action(action = nil) ⇒ Object 



116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/chef/provider.rb', line 116

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 



162
163
164
165
166
167
168
169
 
# File 'lib/chef/provider.rb', line 162

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) 


73
74
75
 
# File 'lib/chef/provider.rb', line 73

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

#whyrun_supported? ⇒ Boolean

Returns:

  • (Boolean) 


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

def whyrun_supported?
  false
end