pallet.core documentation

Core functionality is provided in lift and converge.

  • node :: A node in the compute service
  • node-spec :: A specification for a node. The node-spec provides an image hardware, location and network template for starting new nodes.
  • server-spec :: A specification for a server. This is a map of phases and a default node-spec. A server-spec has the following keys :phase, :packager and node-spec keys.
  • group-spec :: A group of identically configured nodes, represented as a map with :group-name, :count and server-spec keys. The group-name is used to link running nodes to their configuration (via pallet.node.Node/group-name)
  • group :: A group of identically configured nodes, represented as a group-spec, together with the servers that are running for that group-spec.
  • group name :: The name used to identify a group.
  • server :: A map used to descibe the node, image, etc of a single node running as part of a group. A server has the following keys :group-name, :node, :node-id and server-spec keys.
  • phase list :: A list of phases to be used
  • action plan :: A list of actions that should be run.

*warn-on-undefined-phase*

Flag to control output of warnings about undefined phases in calls to lift and converge.

adjust-session-for-nodes

[session]

Take :new-nodes and :old-nodes, and adjust :original-nodes and :all-nodes

admin-user

[user]
[username & {:keys [public-key-path private-key-path passphrase password sudo-password no-sudo], :as options}]

Set the root binding for the admin user. The user arg is a map as returned by make-user, or a username. When passing a username the options can be specified as in pallet.utils/make-user.

This is mainly for use at the repl, since the admin user can be specified functionally using the :user key in a lift or converge call, or in the environment.

all-node-set-selector

[session]

Select all nodes for groups in the node-set for processing

cluster-groups

[cluster]

Return the groups in the passed cluster or sequence of clusters.

cluster-spec

[cluster-name & {:keys [extends groups phases node-spec environment], :as options}]

Create a cluster-spec.

name is used as a prefix for all groups in the cluster.

  • :groups specify a sequence of groups that define the cluster

  • :extends specify a server-spec, a group-spec, or sequence thereof for all groups in the cluster

  • :phases define phases on all groups.

  • :node-spec default node-spec for the nodes in the cluster

  • :roles roles for the group-spec

converge

[group-spec->count & {:keys [compute blobstore user phase prefix middleware all-nodes all-node-set environment], :as options}]

Converge the existing compute resources with the counts specified in group-spec->count. New nodes are started, or nodes are destroyed, to obtain the specified node counts.

group-spec->count can be a map from group-spec to node count, or can be a sequence of group-specs containing a :count key.

The compute service may be supplied as an option, otherwise the bound compute-service is used.

This applies the bootstrap phase to all new nodes and the configure phase to all running nodes whose group-name matches a key in the node map. Additional phases can also be specified in the options, and will be applied to all matching nodes. The :configure phase is always applied, by default as the first (post bootstrap) phase. You can change the order in which the :configure phase is applied by explicitly listing it.

An optional group-name prefix may be specified. This will be used to modify the group-name for each group-spec, allowing you to build multiple discrete clusters from a single set of group-specs.

converge*

[session]

Converge the node counts of each node-spec in :node-set, executing each of the configuration phases on all the group-names in :node-set. The phase-functions are also executed, but not applied, for any other nodes in :all-node-set

converge-cluster

[cluster & options]

Converge the specified cluster. As for converge, but takes a cluster-spec or sequence of cluster-specs.

default-algorithms

Algorithms to use when none specified

default-environment

[]

Specify the built-in default environment

default-executors

Default executor map

defnode

(tag doc-str? attr-map? image & phasekw-phasefn-pairs)

Deprecated: 0.5.0

Define a node type. The name is used for the group name.

image defines the image selector template. This is a vector of keyword or keyword value pairs that are used to filter the image list to select an image. Options are used to define phases. Standard phases are: :bootstrap run on first boot :configure defines the configuration of the node.

destroy-cluster

[cluster & options]

Destroy the specified cluster. As for converge, but takes a cluster-spec or sequence of cluster-specs.

environment-args

args that are really part of the environment

expand-cluster-groups

[node-set]

Expand a node-set into its groups

expand-group-spec-with-counts

[node-set spec-count]
[node-set]

Expand a converge node spec into its groups

group-spec

[name & {:keys [extends count image phases packager node-spec roles], :as options}]

Create a group-spec.

name is used for the group name, which is set on each node and links a node to it's node-spec

  • :extends specify a server-spec, a group-spec, or sequence thereof, and is used to inherit phases, etc.

  • :phases used to define phases. Standard phases are:

    • :bootstrap run on first boot of a new node
    • :configure defines the configuration of the node.
  • :count specify the target number of nodes for this node-spec

  • :packager override the choice of packager to use
  • :node-spec default node-spec for this server-spec

groups-with-servers

[node-map execute-node?]

Takes a map from node-spec to sequence of nodes, and converts it to a sequence of group definitions, containing a server for each node in then :servers key of each group. The server will contain the node-spec, updated with any information that was available from the node.

(groups-with-servers {(node-spec "spec" {}) [a b c]})
  => [{:group-name "spec"
       :servers [{:group-name "spec" :node a}
                 {:group-name "spec" :node b}
                 {:group-name "spec" :node c}]}]

options allows adding extra keys to the servers.

lift

[node-set & {:keys [compute phase prefix middleware all-node-set environment], :as options}]

Lift the running nodes in the specified node-set by applying the specified phases. The compute service may be supplied as an option, otherwise the bound compute-service is used. The configure phase is applied by default unless other phases are specified.

node-set can be a group-spec, a sequence of group-specs, or a map of group-spec to nodes (to explicitly associate nodes to a group-spec).

Examples: [group-spec1 group-spec2 {group-spec #{node1 node2}}] group-spec {group-spec #{node1 node2}}

options can also be keywords specifying the phases to apply, or an immediate phase specified with the phase macro, or a function that will be called with each matching node.

Options: :compute a jclouds compute service :compute-service a map of :provider, :identity, :credential, and optionally :extensions for constructing a jclouds compute service. :phase a phase keyword, phase function, or sequence of these :middleware the middleware to apply to the configuration pipeline :prefix a prefix for the group-name names :user the admin-user on the nodes

lift*

[session]

Lift the nodes specified in the session :node-set key. - :node-set - a specification of nodes to lift - :all-nodes - a sequence of all known nodes - :all-node-set - a specification of nodes to invoke (but not lift)

lift-cluster

[cluster & options]

Lift the specified cluster. As for lift, but takes a cluster-spec or sequence of cluster-specs.

lift-nodes

[session]

Lift nodes in target-node-map for the specified phases.

lift-phase

[session]

Lift nodes in target-node-map for the specified phases.

Builds the commands for the phase, then executes pre-phase, phase, and after-phase

log-message

[msg]

Log the message

log-session

[msg]

Log the session state

make-node

[name image & {:as phase-map}]

Deprecated: 0.5.0

Create a node definition. See defnode.

merge-spec-algorithm

Map from key to merge algorithm. Specifies how specs are merged.

middleware-handler

[handler]

Build a middleware processing pipeline from the specified middleware. The result is a middleware.

name-with-attributes

[name macro-args]

Modified version, of that found in contrib, to handle the image map.

new-node-set-selector

[session]

Select all new nodes for groups in the node-set for processing

node-spec

[& {:keys [image hardware location network qos], :as options}]

Create a node-spec.

Defines the compute image and hardware selector template.

This is used to filter a cloud provider's image and hardware list to select an image and hardware for nodes created for this node-spec.

:image a map descirbing a predicate for matching an image: os-family os-name-matches os-version-matches os-description-matches os-64-bit image-version-matches image-name-matches image-description-matches image-id

:location a map describing a predicate for matching location: location-id :hardware a map describing a predicate for matching harware: min-cores min-ram smallest fastest biggest architecture hardware-id :network a map for network connectivity options: inbound-ports :qos a map for quality of service options: spot-price enable-monitoring

nodes-in-set

[node-set prefix nodes]

Build a map of node-spec to nodes for the given node-set. A node set can be a node spec, a map from node-spec to a sequence of nodes, or a sequence of these.

The prefix is applied to the group-name of each node-spec in the result. This allows you to build seperate clusters based on the same node-spec's.

The return value is a map of node-spec to node sequence.

Example node sets: node-spec-1 [node-spec1 node-spec-2] {node-spec #{node1 node2}} [node-spec1 node-spec-2 {node-spec #{node1 node2}}]

parallel-adjust-node-counts

[session op groups]

Start or stop the specified number of nodes.

parallel-apply-phase

[session]

Apply a phase to a sequence of nodes

parallel-lift

[session]

Apply the phases in sequence, to nodes in parallel.

raise-on-error

[handler]

Middleware that raises a condition on an error.

reduce-adjust-nodes

[session session-adjust]

reduce the result of an adjust-node onto a session

select-node-set

[session]

Select a node-set of nodes to be passed to lift

sequential-apply-phase

[session]

Apply a phase to a sequence of nodes

sequential-lift

[session]

Sequential apply the phases.

serial-adjust-node-counts

[session op groups]

Start or stop the specified number of nodes.

server

[group node options]

Take a group and a node, an options map and combine them to produce a server.

The group os-family, os-version, are replaced with the details form the node. The :node key is set to node, and the :node-id and :packager keys are set.

options allows adding extra keys on the server.

server-spec

[& {:keys [phases packager node-spec extends roles], :as options}]

Create a server-spec.

  • :phases a hash-map used to define phases. Standard phases are:
    • :bootstrap run on first boot of a new node
    • :configure defines the configuration of the node
  • :extends takes a server-spec, or sequence thereof, and is used to inherit phases, etc.
  • :roles defines a sequence of roles for the server-spec
  • :node-spec default node-spec for this server-spec
  • :packager override the choice of packager to use

session-with-all-nodes

[session]

If the :all-nodes key is not set, then the nodes are retrieved from the compute service if possible.

session-with-environment

[{:as options}]

Build a session map from the given options, combining the service specific options with those given in the converge or lift invocation.

session-with-groups

[session]

Takes the :selected-nodes, :all-nodes. :node-set and :prefix keys and compute the groups for the session, updating the :selected-nodes, :all-nodes and :groups keys of the session.

The :groups key is set to a sequence of groups, each containing its list of servers on the :servers key.

show-target-keys

[handler]

Middleware that is useful in debugging.

stop-execution-on-error

[result flag]

:execute-status-fn algorithm to stop execution on an error

version

[]

Returns the pallet version.

with-admin-user

[user & body]
[[username & {:keys [public-key-path private-key-path passphrase password sudo-password no-sudo], :as options}] & body]

Specify the admin user for running remote commands. The user is specified either as pallet.utils.User record (see the pallet.utils/make-user convenience fn) or as an argument list that will be passed to make-user.

This is mainly for use at the repl, since the admin user can be specified functionally using the :user key in a lift or converge call, or in the environment.

with-middleware

[f & body]

Wrap node execution in the given middleware. A middleware is a function of one argument (a handler function, that is the next middleware to call) and returns a dunction of one argument (the session map). Middleware can be composed with the pipe macro.