Pallet 0.8.0-RC.8 API documentation

DevOps for the JVM.

Pallet is a platform for agile and programmatic automation of infrastructure in the cloud, on server racks or directly on virtual machines. Pallet provides cloud provider and operating system independence, and allows for an unprecedented level of customization.

Actions are the primitives that are called by crate functions.

Actions can have multiple implementations, but by default most are implemented as script to be executed on the remote node.

An action has an :execution, which is one of :aggregated, :in-sequence, :collected, :delayed-crate-fn or :aggregated-crate-fn.

Calls to :aggregated actions will be grouped, and run before :in-sequence actions. Calls to :collected actions will be grouped, and run after :in-sequence actions.

Calls to :delayed-crate-fn and :aggregated-crate-fn actions are evaluated at action plan translation time, which provides a mechanism for calling crate functions after all other crate functions have been called.

Provides a data structure for pallet's actions. This is the internal representation of an action. User code should use pallet.action, where actions are represented via the functions that insert them into the session action plan.

Each action has a symbol associated with an action is used in error messages. The symbol does not have to resolve to a var.

The execution specifies the execution model for the action.

Precedence is stored as a map, with :always-before and :always-after keys.

Each implementation is represented as a map of metadata and function. The map is stored in a map in an atom on the ::impls key of the metadata of the action, keyed by the dispatch value. This allows for the implementation function to be an anonymous named function, while still having metadata associated with it.

An action plan contains instances of actions (action maps) for execution.

The action plan is built by executing a phase function. Each phase function calls actions which insert themselves into the action plan.

The action plan is transformed to provide aggregated operations, run delayed crate functions, and to resolve precedence relations between actions.

A translated plan is executed by passing an executor, which is a function that will be passed each action map in the plan. The executor function is responsible for selecting the implementation of the action to be used, and calling the implementation with the action-map arguments.

Note this is an implementation namespace.

Direct execution action implementations

Conditional action execution.

A directory manipulation action, to create and remove directories with given ownership and mode.

Script execution. Script generation occurs with the correct script context.

File manipulation.

Package management action.

package is used to install or remove a package.

package-source is used to specify a non-standard source for packages.

Action to specify the content of a remote directory. At present the content can come from a downloaded tar or zip file.

Action to specify remote file content.

Provides an action that can be repeated if it fails

Service control. Deprecated in favour of pallet.crate.service.

User management action.

Arguments to actions. Adds capability of evaluating arguments at action application

Blobstore abstraction

Implementation details

A url based blobstore implementation.

Process command-line arguments according to a given cmdspec

Hybrid provider service implementation.

Implementation details

Information from local jvm

Localhost provider service implementation.

This enables your localhost to masquerade as a node for any group.

run-nodes will set the group-name for the localhost node, but is otherwise a no-op. The localhost node is marked as bootstrapped to prevent bootstrap actions from occurring on group-name changes.

Node removal functions are no-ops.

A simple node list provider.

The node-list provider enables pallet to work with a server rack or existing virtual machines. It works by maintaining a list of nodes. Each node minimally provides an IP address, a host name, a group name and an operating system. Nodes are constructed using make-node.

An instance of the node-list provider can be built using node-list-service.

  [["host1" "fullstack" "" :ubuntu]
   ["host2" "fullstack" "" :ubuntu]])

Some standard file formating.

Provides contexts for exceptions, logging, etc

Contracts that can be enforced in pallet code.

Protocols for file upload

Implementation of file upload using rsync.

Functions to manipulate the plan-state map. The plan-state represents all the cumulative settings information on the nodes in an operation.

Provides a thread local place, using a dynamic var.

A thread local place can be given a value using with-thread-locals. It is an error to use with-thread-locals if the thread local already has a value.

The current value of the thread local is found with thread-local.

The current value of the thread local can be set with thread-local!. It is an error to set the value on a thread other than the one used to provide the initial value using with-thread-locals.

 (def ^:dynamic *tl*)

 (with-thread-locals [*t1* {}]
  (assert (= (thread-local *tl*) {}))
  (thread-local! *tl* {:a 1})
  (assert (= (thread-local *tl*) {:a 1})))

Version dispatch

Set up the system environment.

Generation and installation of /etc/default-style files.

Filesystem crate.

Provides service supervision via initd

Configure the /etc/security/limits.conf file.

Crate for working with network services

Provides supervision via nohup. Note that this is very limited, and not really recommended for production use.

OS detection for pallet to determine os and version

Actions for working with the centos repositories

Actions for working with the debian backports repository

Actions for working with the epel repository

Actions for working with the jpackage repository

Actions for working with the rpmforge repository

Package repositories

Run services under supervision.

This crate provides a framework for a process under supervision. It can be extended by different supervision providers, by providing methods for the various multi-methods. A crate can provide configuration for use with a range of supervision providers.

To control a service, the service function is used.

To configure a job for a service, implement a supervisor-config-map for the facility and supervision service you wish to use. Ensure the server-spec for the supervision implementation is extended by your group-spec.

To create an implementation for a new service supervision provider, implement methods for service-supervisor-available?, service-supervisor and service-supervisor-config.

Crate functions for manipulating SSH-keys

Install methods for crates

Helpers for debugging.

Action execution that just echos the action script

Wrappers for enlive to enable template specialisation and use xml.

The environments provide mechanisms for customising Pallet and Pallet crates according to externally determined criteria.

An environment can be specified at the global, service, invocation and tag scopes.

To provide a global default, specify an :environment key at the top level of defpallet in ~/.pallet/config.clj.

To provide a service specific default, specify an :environment key at the service level of defpallet in ~/.pallet/config.clj.

To provide a project specific default, define pallet.config/environment.

To provide a specific environment when invoking lift or converge, pass an environment map using the :environment key.

The merging of values between scopes is key specific, and is determined by merge-key-algorithm.

Implementation namespace for the pallet environment.

Pallet events. Provides ability to hook into pallet event stream.

Action executors for pallet.

An action has a :action-type. Known types include :script and :fn/clojure.

An action has a :location, :origin for execution on the node running pallet, and :target for the target node.

The action-type determines how the action should be handled:

:script - action produces script for execution on remote machine :fn/clojure - action is a function for local execution :transfer/to-local - action is a function specifying remote source and local destination. :transfer/from-local - action is a function specifying local source and remote destination.

Pallet feature recognition.

A feature is implemented as a function within the pallet.feature namespace

Keep track of operations started by pallet

Invoke tasks requiring a compute service. This decouples main from anything pallet, jclouds or maven specific, and ensures compiling main doesn't compile the world.

A node value is a value that is retrieved from a node and can only be deref'd when after the value as been provided by an action.

The action may not be executed on the same pallet machine as the phase, so the actual value is in the session map, and the node-value contains a key into the session map's :node-values key.

A phase is a function of a single session argument, that contains calls to crate functions or actions. A phase has an implicitly defined pre and post phase.

Pallet projects are specified in a pallet.clj file.

The files are loaded by calling clojure.core/load in the pallet.project.load namespace. The defproject form in that file def's a pallet-project-map var, which is reset after loading.

defproject refers to pallet.project.loader/defproject.

Namespace for loading pallet project files. Provides a default set of requires that are available to the pallet file.

Functions and macros required to load a pallet project configuration file.

Build scripts with prologues, epilogues, etc, and command lines for running them in different environments

Script execution for pallet. Abstracts over transport, script environment, and the script itself

Session specific action-plan functions.

Encapsulates the location of the action-plans in the session.

Location of intermediate content files.

Protocols for node state updates

Functions for working with ssh credentials.

Implementation of file upload using SFTP.

This assumes that chown/chgrp/chmod are all going to work.

A node-state implementation that maintains no node state

Protocols for node state updates

Protocols for uploading scripts to be run on the remote machine

Runtime string interpolation built on top of clojure.contrib.strint.

Task helpers, that do not have any dependencies in pallet.

Add a service definition to pallet.

Create a pallet configuration file in ~/.pallet/config.clj

List containers.

Adjust node counts.

Describe the node definition.

Remove project nodes.

Display a list of tasks or help for a given task.

List images.

Apply configuration.

List nodes.

Initialise a project.

Provide information on the supported and enabled providers.

Upload to a blob.

Bring up nodes.

Print Pallet's version to standard out.

Task helpers that depend on pallet implementation

Template file writing

A template for writing properties style config files.

Dispatch that is version aware.

A version is a dotted string, e.g. "1.0.3", which is represented as a vector [1 0 3].

A version specification is either a version vector, which matches a single version (and all point versions thereof), or a vector of two elements, specifying an inclusive version range. A nil in the version vector signifies an open end to the range.

The basic idea is that you wish to dispatch on hierarchy where the dispatched data may provide a version.