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

[Hedge Hog < >]

This is an exemplary change notice.
Is there a Cookbook convention yet for distributing notices like these
with a cookbook?
If not, I'd nominate this notice and the runit cookbook as candidates
for a best-practice example.

Maybe a cookbook can have an optional notices folder, with markdown
files named by the version number?

cookbooks/runit/notices/0.16.2

thoughts?

On Fri, Jan 25, 2013 at 4:33 AM, Akzhan Abdulin
<
 >
 wrote:
> Agrhh.. A lot of our cookbooks should be rewritten now.
>
> But I glad that it is happens. runit should be in core.
>
>
> 2013/1/23 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
>>
>>
>



-- 
πόλλ' οἶδ ἀλώπηξ, ἀλλ' ἐχῖνος ἓν μέγα
[The fox knows many things, but the hedgehog knows one big thing.]
  Archilochus, Greek poet (c. 680 BC – c. 645 BC)
http://hedgehogshiatus.com