Pallet is filled with metaphorical names and functions with a bewildering array of options. This article sets out some basic introductory concepts to help you figure out the rest of the documentation.
Pallet manages sets of nodes by talking to cloud hosting services, and configures these nodes by logging into them and executing shell scripts.
The main objects of interest in Pallet are nodes, the servers you are going to use for something. Operationally, this means that you will define one or more nodes, and Pallet will use the configuration directives to ensure that after Pallet has run, you will have all the servers that you defined, each with the appropriate configuration. In order to perform this task, Pallet may talk to a cloud hosting provider you specify and create or delete nodes in order to match your requested configuration, or you may give Pallet a list of pre-existing nodes that it should take as given. In the near future, Pallet may also let you create virtual machine nodes in VirtualBox.
Pallet uses the jclouds library to talk to a large number of different possible cloud hosting services. In order to let Pallet work with one of these, you just have to let Pallet know your login credentials, as provided by that service. From then on, Pallet will log in and perform dozens of API calls when it has to in order to make your servers in the cloud service reflect the configuration. Most cloud hosts have great management consoles available through their websites, but using Pallet you can formalize the configuration of your servers (for reproducibility), move them around to different providers, and create many copies of a given server configuration quickly and automatically.
For any given server, either created automatically by Pallet or a pre-existing one, Pallet will configure the software on that machine by logging in as a user and executing shell scripts. The shell scripts are derived from the configuration you specify for each node, and then shipped to that server for execution. At the end of a Pallet run, the server will have changed itself, if necessary, so that its configuration matches what is asked for. Although the scripts are run every time, directing Pallet to perform a particular configuration that is already in effect on a machine should leave the machine unchanged except for the fact that the steps in the script were performed.
While the rest of Pallet's documentation is being written, you may from time to time have to do a little digging to figure out how to do something. This list of terminology used in the documentation and source code should help.
- Phase Pallet configuration runs are divided conceptually into phases that group together certain tasks. Some phases are always run, and some are run only at certain times. For example, the :configure phase is run every time you run Pallet on a node, while the :bootstrap phase is run only when a node is first brought up. You can write your own phases and ask Pallet to apply them for you as well.
- Crate Crates are what you might call "modules," reusable bundles of code that others have written or that you might write in order to control a particular aspect of configuration. In reality, crates are just functions that take as an argument and return a configuration map, much like a Ring handler. Also like a Ring handler, crates can be composed together to create more advanced configurations; many crates you will write can be created entirely by calling simpler crates provided by Pallet.
- Resource A resource is a low-level piece of functionality built into Pallet that is used to generate shell script for a particular purpose. A lot of OS-specific special-casing is taken care of in resources. For example, there are resources for creating files and directories on the remote system, for rsyncing files to the remote machine, for finding particular system configuration directories for various operating systems, and so on. You may need to use resources when writing crates, particularly if you find yourself trying to do something that feels lower-level than the install-and-setup orientation of most crates.
- Stevedore Stevedore is Pallet's DSL for writing shell scripts directly in Clojure forms. By being able to generate shell script from a Clojure DSL, the shell script for useful tasks can be abstracted into Clojure functions or macros that make them more general than might be possible or convenient with simple templates. Both crates and resources make heavy use of Stevedore.
- Request map When Pallet initiates a phase on a node, the code is run with a map as an argument. The map contains information about the context the command is being run in, such as the node type and admin user. Crates can use the information inside if necessary to their task, and composing crates requires correctly passing and returning the request map as you go. There are a variety of useful macros to thread (in the sense of the -> macro) the request map through various control constructs in pallet.thread_expr.