[chef] CHEF-154 and upcoming change to runit cookbook

[Joshua Timberman < >]

Ohai Chefs,

TL;DR: runit_service as a definition will be replaced with runit_service
as a Chef resource/provider, under ticket CHEF-154. See, "Help with
Testing" below.

* http://tickets.opscode.com/browse/CHEF-154

I want to let everyone know about some important changes in Opscode's
runit cookbook. They will be backwards-incompatible with the current
version, and may require changes to cookbooks/recipes that currently use
the "runit_service" definition, and the pattern that it follows. Currently
this is all in a separate branch (CHEF-154), but once the README is
updated, will be merged into master and released, probably as a version
"1.0" of the cookbook.

# Red Hat Support

Before I talk about the runit_service resource, I want to give Paul
Graydon (Twirrim) a shout out for adding support for Red Hat platforms.
The default recipe will now use Ian Meyer's RPM spec for runit to build a
package and install it.

This is all tested under the test-kitchen support on CentOS 5.8 and 6.3
that is also added to the cookbook.

# Resource/Provider

The main change is that the definition is refactored into a regular Chef
resource/provider. As a result, the way runit_service works is going to be
slightly different, and you may need to change recipes to account for that.

In the current release of the cookbook, runit_service is a definition.
This means that during a Chef run, the definition is replaced by the
resources it contains. By default, this in a recipe:

    runit_service "example-service"

Results in these resources in Chef's resource collection:

    "execute[start-runsvdir]"
    "execute[runit-hup-init]"
    "package[runit]"
    "directory[/etc/sv/example-service]"
    "directory[/etc/sv/example-service/log]"
    "directory[/etc/sv/example-service/log/main]"
    "template[/etc/sv/example-service/log/run]"
    "template[/etc/sv/example-service/run]"
    "link[/etc/init.d/example-service]"
    "link[/etc/service/example-service]"
    "ruby_block[supervise_example-service_sleep]"
    "service[example-service]"


Note that the first three (two executes and one package) are from
include_recipe "runit" that is in the definition. This is the first thing
to note, the "runit" recipe must be included before the runit_service
resource can be used.

With "runit_service" available as a resource, none of these resources will
be created. Only a single resource is created, the runit_service itself.
So this in a recipe:

    runit_service "example-service"

Results in this resource in Chef's resource collection:

    "runit_service[example-service]"

The effect of this is that resources notifying a service to restart/reload
must specify a runit_service. For example:

    template "/etc/example/service.conf" do
      notifies :restart, "runit_service[example-service]"
    end

One of the benefits of runit now having a first class resource is for
notification purposes. Runit itself supports a wide variety of commands
that can be sent using the "sv" program, and the resource implements all
of them:

    [:start, :stop, :enable, :disable, :restart,
     :reload, :status, :once, :hup, :cont, :term,
     :kill, :up, :down, :usr1, :usr2]

These will all be documented for the next release. They do pretty much
what you'd expect. The :enable action handles the things that the
runit_service definition did, and is the default action. For more
information see the `sv(8)` man page.

Next thing to note is that the resource will block on the enable action
until the named pipe supervise/ok exists in the service directory for the
service. Previously, we only waited up to 10 seconds, which lead to race
conditions that were hard to debug.

In the past, attempts to create services that could be controlled by
non-privileged users were made. These didn't always work correctly, and
none of them implemented non-privileged services according to the runit
documentation. The documentation says to create a runsvdir service for
that user, pointing to the desired service directory (in the run script).

    % cat /etc/service/runsvdir-floyd
    #!/bin/sh
    exec 2>&1
    exec chpst -ufloyd runsvdir /home/floyd/service

Presuming a user named floyd is created, this allows the user to create
any services they desire, and manage them. A full example of this can be
found in the runit_test cookbook that comes with the runit cookbook's
repository:

https://github.com/opscode-cookbooks/runit/blob/CHEF-154/test/kitchen/cookb
ooks/runit_test/recipes/service.rb


This will be documented for the cookbook release.

In the interest of clarity of their purpose, some parameters used in the
definition have new names in the resource. These aren't commonly specified
in our own cookbooks, but we don't know what users are doing out there, so
please be aware.

* directory -> sv_dir
* active_directory -> service_dir
* template_name -> use service_name (name attribute)
* nolog -> set "log" to false
* start_command -> unused (was previously in the "service" resource)
* stop_command -> unused (was previously in the "service" resource)
* restart_command -> unused (was previously in the "service" resource)


## Changes of Note

1. The "runit" recipe must be included before the runit_service resource
can be used.
2. runit_service definition created a "service" resource. This is now a
"runit_service" resource, for the purposes of notifications.
3. enable action blocks waiting for supervise/ok after the service symlink
is created.
4. Create user-controlled services per the runit documentation.
5. Some parameters in the definition have changed names in the resource.

# Spec Tests

This cookbook now includes "spec" tests, in the repository's
`test/spec/runit_service_spec.rb`. To run the tests on your system:

    git clone git://github.com/opscode-cookbooks/runit.git
    bundle install
    bundle exec rake spec

# Test Kitchen

The cookbook is setup for Chef convergence, and post convergence
minitest-handler tests.

    git clone git://github.com/opscode-cookbooks/runit.git
    bundle install
    bundle exec kitchen test

The "service" configuration will set up a number of runit_service
resources to:


1. Test various use cases.
2. Serve as examples that you can use.

# Help With Testing

We could use help testing the runit_service resource. If you're using
runit_service (the definition) in your own cookbooks and have a test
environment, please take the CHEF-154 branch for a spin. If you're using
Librarian, add to your Cheffile:

    cookbook 'runit',
      :git => 'git://github.com/opscode-cookbooks/runit',
      :ref => "CHEF-154"


If you're using Berkshelf, add to your Berksfile:

    cookbook "runit",
      :github => "opscode-cookbooks/runit",
      :branch => "CHEF-154"


If you're using a Chef Server, and use environments, set a constraint on
the runit cookbook, for example:

    cookbook "runit", "<= 0.16.2"

Version 0.16.2 is the currently released version.

# Next Steps

I'm working to update the README to reflect the changes discussed here.
Once it is updated, a 1.0 version will be released.

Before that happens, the various Opscode cookbooks that use runit will
have their metadata updated so they don't get the new version until
they've been updated as required for the changes listed above. I've opened
COOK-2253 for tracking this.

Thanks!

-- 
Opscode, Inc
Joshua Timberman, Technical Community Manager
IRC, Skype, Twitter, Github: jtimberman