Puppet Recipe Manager
=====================

This is a small utility to facilitate the distribution of 'recipes',
configurations under the control of puppet. A recipe, a precanned
configuration for a specific aspect of a system's functioning, consists of
one or more puppet manifests and configuration files needed by the
manifest. Using prm to manage recipes makes it both easier for system
administrators to incorporate configurations from others, manage changes to
their site's configuration, and share their configuration beyond their
site.

The Puppet Recipe Manager, prm, takes care of the details of downloading
and updating recipes, deploying them at a site, and ensuring that puppet
manifests and config files wind up in the proper places in the file system
of the puppet server and its file server.

A recipe can be initially obtained from an 'upstream' repository, and then
modifed locally to better fit the needs of the site that deploys it. Since
it is likely that upstream updates to recipes need to be incorporated
into a site's configuration, even after that site has made changes to the
initial recipe, recipes should be kept under the control of a distributed
source control system; this prototype uses mercurial
(http://www.selenic.com/mercurial/) for this purpose.

The lifecycle of a recipe can be illustrated as follows:
* Upstream maintainer publishes version 1.0 as a mercurial
  repository at some URL
* Site admin downloads and deploys recipe with 'prm get'
* Site admin makes local changes to recipe, and checks them
  into her local copy of the mercurial repo
* Upstream maintainer makes changes to recipe and publishes
  version 2.0
* Site admin updates recipe from upstream by running 'prm update';
  this may require resolving conflicts between the upstream version
  and the changed local version. For now, this would have to be done
  manually.

Directory layout for a recipe
-----------------------------

The upstream mercurial repo for a recipe should adhere to a fixed directory
layout. In particular, all puppet manifests should go into a 'manifests'
directory. Apart from this requirement, accompanying config files can be
placed anywhere in the mercurial repo, though it is expected that more
standards around directory layout will evolve.

After downloading or updating a recipe from upstream, prm copies puppet
manifests and configuration files into the proper places in the puppet
server's file system. It is assumed that prm is run on the same machine as
the puppet server; the location for puppet manifests can be set with the
'manifestPath' option in prm.conf, and the location of the 'config' module
for puppet's fileserver can be set with the 'configPath' option. (FIXME:
what is the convention for mapping these files into 'puppet:' URL's in the
manifests ?)

In summary, a puppet recipe has the following directory layout

$recipeName/
    .hg/
    manifests/
        *.pp
    other files and direcories

When prm deploys a recipe, it copies the files and directories inside the
manifests/ directory to $manifestPath/$recipeName, and any other files and
directories (with the exception of the .hg/ subdir) to
$configPath/$recipeName.

Usage
=====

prm uses a two level cli. You can specify global arguments, a "mode", and
per mode arguments. For example:

    prm get -v ssh://willyprmuser@hg.example.com//path/to/recipe

Global Arguments
----------------

  Aside from help and verbosity, the current arguments are:

    --config/-c:  specify a config file. Default is /etc/prm.conf; See
                  the sample config file for an explanation of the
                  configuration options.

prm get - initial download
--------------------------

    prm get URL

"prm get" will download the recipe from the URL into the local repo via "hg
clone", and then deploy it on the system by copying manifests and config
files into the proper places as described above. The URL must point to the
mercurial repository for a recipe and can be anything that mercurial
understands, including http and ssh URL's.


prm update - update an existing recipe
--------------------------------------

    prm update RECIPE

This downloads the latest version of the recipe and integrates it into the
existing recipe. RECIPE can either be the name of an existing recipe, or
the full URL used with the initial "prm get". Integration of the recipe is
done via "hg pull" followed by "hg update -m". Once the new version has
been integrated, it is deployed in the same manner as with "prm get".

prm commit - commit local changes to the local recipe
-----------------------------------------------------

    prm commit RECIPE

Commit changes made in the puppet server's file system to the local
mercurial repo. Copies files from the puppet server's file system back into
the local mercurial repo, basically undoing the deploy step, and then does
an 'hg commit'. RECIPE must be the name of a recipe.

prm tag - tag the latest version of a recipe
--------------------------------------------
    prm tag -r 1.2.3

Tag the current version of the recipe with a revision number. The revision
number can also be passed to "prm update" to update/downgrade to a specific
version.

prm init - initialize the directories used by prm
-------------------------------------------------
    prm init [-n|--dryrun]
        
Check that the directories needed by prm exist and are writable by the
current user. If they do not exist, prm will try to create them.
     
If the --dryrun option is given, only the checks are performed, but nothing
is created