Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 37 ยท Resources and Recipes

Chef Notifications and Subscribes

Learn how Chef resources trigger each other: notifies and subscribes, delayed versus immediate and before timers, action :nothing, and the restart-on-config-change pattern.

Some actions should happen only when something else changed. Restart nginx only when its config file changed. Reload systemd only when a unit file was updated. Chef models this with notifications: a resource that changed can tell another resource to run an action. This lesson covers notifies, subscribes, the timers :delayed, :immediately and :before, and the pattern you will use dozens of times. Real code is read-only; stand-ins let you run and watch the ordering.

notifies

notifies sits on the resource that changes and names the target resource and action:

Ruby
template '/etc/nginx/nginx.conf' do
  source 'nginx.conf.erb'
  notifies :restart, 'service[nginx]'
end

service 'nginx' do
  action [:enable, :start]
end

The format is notifies :action, 'resource_type[resource_name]', :timer. The notification fires only if the notifying resource was updated (the file content really changed). If the template is already correct, nginx is not touched, so you avoid needless restarts.

subscribes

subscribes is the same idea seen from the other side: the target resource says which resource it listens to.

Ruby
service 'nginx' do
  action [:enable, :start]
  subscribes :restart, 'template[/etc/nginx/nginx.conf]'
end

Use notifies when the cause knows its effect, and subscribes when the effect should list everything that affects it, for example a service that depends on several files in different cookbooks.

Timers: delayed, immediately and before

The third argument chooses when the target acts:

  • :delayed (default): wait until the end of the converge phase, then run, and only once even if notified many times.
  • :immediately: run the target action right after the notifying resource.
  • :before: run the target before the notifying resource changes (rare, for example a backup before an upgrade).
Ruby
template '/etc/app/app.conf' do
  source 'app.conf.erb'
  notifies :restart, 'service[app]', :delayed
end

execute 'systemctl daemon-reload' do
  action :nothing
end

template '/etc/systemd/system/app.service' do
  source 'app.service.erb'
  notifies :run, 'execute[systemctl daemon-reload]', :immediately
end

The unit file case needs :immediately, because the service start later in the run needs the reloaded definition. The config file case is fine with :delayed, which also batches: three config files can all notify a restart and the service is restarted only once.

action :nothing

A resource that exists only to be triggered should have action :nothing. It is declared normally but dormant until notified. This is how the execute above avoids running on every run.

Stand-in: a notification engine

The model below implements notifies with :delayed and :immediately timers, de-duplicates delayed notifications and runs them at the end. It is not real Chef.

Ruby Stand-in: delayed vs immediate notifications

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Observe three behaviors: the service is restarted once in run 1 although two files notified it, the immediate action runs in place, and run 2 triggers nothing because nothing changed.

Chains and the restart-on-failure trap

Notifications can chain: A notifies B, B notifies C. But there is a trap. If Chef fails before the end of converge, the delayed notifications are lost, and the config change that triggered them is already on disk. On the next run the template is "up to date", so no notification fires and the service never restarts. If a restart matters, use :immediately for the pair that must stay consistent, or design the recipe so the failing step runs earlier.

Ruby Stand-in: a failure loses a delayed notification

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

The second run changes nothing, so the running service keeps the old config. Chef recipes should be tested for exactly this case, which is where Test Kitchen comes in later.

If you need to force the restart, notify with :immediately right after the template, or use a service :restart inside a guarded execute that compares versions.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. When does a notifies fire?

    A notification is triggered by a change in the notifying resource.
  2. 2. What does the default :delayed timer do when three resources notify the same restart?

    Delayed notifications are collected and run once at the end.
  3. 3. Why give the target resource action :nothing?

    Dormant resources only act when a notification arrives.
  4. 4. What is the difference between notifies and subscribes?

    They express the same relationship from opposite resources.

Summary

  • notifies and subscribes run an action on another resource only after a real change.
  • :delayed batches to the end of converge; :immediately runs in place; :before runs first.
  • Use action :nothing for resources that exist to be triggered.
  • A failed run can lose delayed notifications, so design critical pairs carefully.

Next: Ruby in Recipes