There are two high level operations in pallet, lift and converge. Both return an operation map, that can be queried as the operation completes asynchronously.

Converge

The converge function can be used to adjust node counts and to apply phases. The :bootstrap phase is the first phase applied to any new node that is started, and :settings is always applied. Additional phases may also be specified. If the :configure phase is not explicitly passed, then it will always be applied as the first phase (or second, after :bootstrap on new nodes).

In this example we define a function that changes the number of running nodes for the "mygroup" group.

  (require 'pallet.api)

  (defn scale-cluster [n]
    (pallet.api/converge
      (pallet.api/group-spec "mygroup" :count n)
      :compute (pallet.configure/compute-service "aws")))

Lift

The lift function is used to apply phases but does not change node counts. The :configure phase is run by default only if no phases are explicitly specified.

Operations

lift and converge are synchronous by default. They have a :timeout-ms option that can be used to specify a timeout for the operation in milliseconds (in which case the value specified by :timeout-val is returned).

If passed :async true, they return operation maps, that implement the Control protocol.

The status of the operation can be monitored using the status, complete? and failed? functions.

You can wait on the result of an operation by derefing it. In this case, deref will re-raise any exception that occurs in the operation.

The wait-for function allows you to wait for the operation to complete, without re-throwing exceptions.

Once the operation has completed, you can re-throw any exception with throw-operation-exception.

If any plan function fails, the failures can be reported as a sequence of maps, using the phase-errors function, or turned into an exception using throw-phase-errors.