What is meant by 'converge_by'

Question

I am pretty new to chef and have just started with machine and LWRP resource.

While doing lots of reading I am finding a term converge_by. What does it mean?

Answer 1

If you write your own pure-ruby code which modifies the system within an LWRP then you want to wrap that code with a converge_by. It does two things which is that it protects the wrapped code so that it does not run during why-run mode. And it automatically marks the resource as being updated when it runs.

In order for the resource you are writing to be idempotent (and not be reported as updated on every single run) you should typically wrap the converge_by in a check for idempotency.

So something like:

use_inline_resources
action :doit do
  unless File.exist("/tmp/doit")
    converge_by("creating /tmp/doit") do
      FileUtils.touch("/tmp/doit")
    end
  end
end

Of course core chef resources already do most of this work for you so for that example its better written just as:

use_inline_resources
action :doit do
  file "/tmp/doit"
end

Which serves to show that your first choice should be to compose the action out of other resources, the second choice is usually to write your own converge_by code.

Answer 2

Convergence means to "bring the system state in line with a defined policy". You will see converge_by around code blocks that will actually perform actions to arrange your system.

It is used by why-run to identify and skip actions that would actually modify system state.