zap/README.adoc

= Zap

A simple cross-platform orchestration and configuration management tool.

The main goal for Zap is to a simple mechanism for managing groups of computers
with varying configurations and needs. Zap accomplishes this with "tasks" which
can be composed into "plans" or run standalone. These tasks can be collections
of scripts or a statically linked binaries, which will be pushed to the target
machine(s) and executed.

Zap borrows ideas from
link:https://puppet.com/docs/bolt/latest/bolt.html[Puppet Bolt]. but leaves
some of the Puppet-based legacy from Bolt behind.

== Examples

[source]
----
❯ zap task tasks/echo.ztask -p msg="Hello World" -t zap-freebsd
Running task with: TaskOpts { task: "tasks/echo.ztask", parameter: ["msg=Hello World"], targets: "zap-freebsd" }
Hello World

----

[source]
----
❯ zap plan ./examples/basic.zplan -t zap-freebsd
Running plan with: PlanOpts { plan: "./examples/basic.zplan", targets: "zap-freebsd" }
Hello from the wonderful world of zplans!
This is nice

----

=== Task

A task is a simple container of some form of execution. Typically this will be
a wrapped shell/ruby/python script which does some specific piece of
functionality. Tasks may also take parameters, which allow for some
pluggability of new values.

Tasks have some default parameters that should not be overridden in new task
definitions.

.Built-in Parameters
|===
| Parameter | Description

| `provides`
| A relative or absolute path to a file that the task provides. If the file exists, then the task will be skipped.

|===

.echo.ztask
[source]
----
task Echo {
    parameters {
        msg {
            required = true
            help = 'String to echo back to the client'
            type = string
        }
    }

    script {
        inline = 'echo {{msg}}'
    }
}
----

=== Plan

A plan is a collection of tasks which can be applied to a target or targets.
Tasks are referenced with the parameters that should be passed into them, and
will be executed in the order that they are defined.


.simple.zplan
[source]
----
task 'tasks/echo.ztask' {
    msg = 'Hello from the wonderful world of zplans!'
}

task 'tasks/echo.ztask' {
    msg = 'This is nice'
}

----