193 lines
3.9 KiB
Plaintext
193 lines
3.9 KiB
Plaintext
:toc: macro
|
||
|
||
= 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.
|
||
|
||
toc::[]
|
||
|
||
== Getting Started
|
||
|
||
Zap is still very early in its development, but if you would like to give it a
|
||
try you can install it via Rust's `cargo` command: `cargo install zap-cli`.
|
||
|
||
[source,bash]
|
||
----
|
||
cargo install zap-cli
|
||
mkdir my-zap-project
|
||
cd my-zap-project
|
||
wget https://github.com/rtyler/zap/archive/v0.1.1.tar.gz
|
||
tar -zxvf v0.1.1.tar.gz zap-0.1.1/tasks -C tasks --strip=1
|
||
cat > hello.zplan <<EOF
|
||
task 'tasks/echo.ztask' {
|
||
msg = 'Show them my medal Kif'
|
||
}
|
||
EOF
|
||
----
|
||
|
||
You will also need to create an inventory file.
|
||
|
||
.Example inventory.yml
|
||
[source,yaml]
|
||
----
|
||
groups: []
|
||
targets:
|
||
- name: alpha
|
||
uri: 192.168.1.1
|
||
config:
|
||
ssh:
|
||
user: root
|
||
password: root
|
||
|
||
config:
|
||
transport: ssh
|
||
----
|
||
|
||
Once this has been set up, you can run:
|
||
|
||
[source,bash]
|
||
----
|
||
zap plan hello.zplan -t alpha --dry-run
|
||
----
|
||
|
||
== Command Line
|
||
|
||
The `zap` command line interface has a number of subcommands that can help with
|
||
the development and deployment of tasks and plans.
|
||
|
||
=== cmd
|
||
|
||
=== check
|
||
|
||
=== plan
|
||
|
||
=== task
|
||
|
||
|
||
== 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.
|
||
|
||
| `unless`
|
||
| A script snippet which can determine whether the task should execute. A non-zero exit status causes the task to execute.
|
||
|
||
|===
|
||
|
||
.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' {
|
||
msg = 'Hello from the wonderful world of zplans!'
|
||
}
|
||
|
||
task 'tasks/echo' {
|
||
msg = 'This is nice'
|
||
}
|
||
|
||
----
|
||
|
||
== Built-in Tasks
|
||
|
||
Zap comes with a number of tasks that are built into `zap` itself. These can be
|
||
referenced in the task declarations in plans via the `zap://` URL.
|
||
|
||
=== `sh`
|
||
|
||
The `sh` task will execute the given script via `/bin/sh` on the target.
|
||
|
||
.Example
|
||
[source]
|
||
----
|
||
task 'zap://sh' {
|
||
script = '''
|
||
pwd
|
||
echo ${SHELL}
|
||
'''
|
||
}
|
||
----
|
||
|
||
.Parameter
|
||
|===
|
||
| Name | Required | Description
|
||
|
||
| `script`
|
||
| yes
|
||
| A shell script
|
||
|
||
| `provides`
|
||
| no
|
||
| When this file is present indicates that the script should not be re-run
|
||
|
||
| `unless`
|
||
| no
|
||
| When this script returns zero exit status, the script should not be re-run
|
||
|
||
|==
|