2021-01-02 04:44:22 +00:00
|
|
|
|
:toc: macro
|
|
|
|
|
|
2020-12-29 06:12:45 +00:00
|
|
|
|
= 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.
|
|
|
|
|
|
2021-01-02 04:44:22 +00:00
|
|
|
|
toc::[]
|
|
|
|
|
|
2021-01-01 18:47:07 +00:00
|
|
|
|
== 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
|
2021-01-01 19:37:36 +00:00
|
|
|
|
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
|
2021-01-01 18:47:07 +00:00
|
|
|
|
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
|
|
|
|
|
----
|
|
|
|
|
|
2021-01-01 19:13:07 +00:00
|
|
|
|
== 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
|
|
|
|
|
|
2021-01-01 18:47:07 +00:00
|
|
|
|
|
2020-12-31 19:10:12 +00:00
|
|
|
|
== Examples
|
2020-12-29 06:12:45 +00:00
|
|
|
|
|
2020-12-31 19:10:12 +00:00
|
|
|
|
[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
|
2020-12-30 17:43:02 +00:00
|
|
|
|
|
2020-12-31 19:10:12 +00:00
|
|
|
|
----
|
2020-12-31 17:48:39 +00:00
|
|
|
|
|
|
|
|
|
[source]
|
|
|
|
|
----
|
2020-12-31 19:10:12 +00:00
|
|
|
|
❯ 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
|
|
|
|
|
|
2020-12-31 17:48:39 +00:00
|
|
|
|
----
|
2020-12-30 06:16:52 +00:00
|
|
|
|
|
2020-12-31 19:10:12 +00:00
|
|
|
|
=== Task
|
2020-12-30 06:16:52 +00:00
|
|
|
|
|
2020-12-31 19:10:12 +00:00
|
|
|
|
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.
|
2020-12-30 06:16:52 +00:00
|
|
|
|
|
2020-12-31 21:46:34 +00:00
|
|
|
|
Tasks have some default parameters that should not be overridden in new task
|
|
|
|
|
definitions.
|
2020-12-31 19:19:05 +00:00
|
|
|
|
|
|
|
|
|
.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.
|
|
|
|
|
|
2021-01-01 06:42:23 +00:00
|
|
|
|
| `unless`
|
|
|
|
|
| A script snippet which can determine whether the task should execute. A non-zero exit status causes the task to execute.
|
|
|
|
|
|
2020-12-31 19:19:05 +00:00
|
|
|
|
|===
|
|
|
|
|
|
2020-12-31 19:10:12 +00:00
|
|
|
|
.echo.ztask
|
2020-12-30 06:16:52 +00:00
|
|
|
|
[source]
|
2020-12-31 19:19:05 +00:00
|
|
|
|
----
|
2020-12-31 19:10:12 +00:00
|
|
|
|
task Echo {
|
2020-12-30 06:16:52 +00:00
|
|
|
|
parameters {
|
2020-12-31 19:10:12 +00:00
|
|
|
|
msg {
|
2020-12-30 06:16:52 +00:00
|
|
|
|
required = true
|
2020-12-31 22:40:08 +00:00
|
|
|
|
help = 'String to echo back to the client'
|
2020-12-30 06:16:52 +00:00
|
|
|
|
type = string
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
script {
|
2020-12-31 22:40:08 +00:00
|
|
|
|
inline = 'echo {{msg}}'
|
2020-12-30 06:16:52 +00:00
|
|
|
|
}
|
|
|
|
|
}
|
2020-12-31 19:10:12 +00:00
|
|
|
|
----
|
2020-12-30 17:43:02 +00:00
|
|
|
|
|
2020-12-31 19:10:12 +00:00
|
|
|
|
=== Plan
|
2020-12-30 17:43:02 +00:00
|
|
|
|
|
2020-12-31 19:10:12 +00:00
|
|
|
|
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.
|
2020-12-30 17:43:02 +00:00
|
|
|
|
|
2020-12-30 06:16:52 +00:00
|
|
|
|
|
2020-12-31 19:10:12 +00:00
|
|
|
|
.simple.zplan
|
2020-12-30 06:16:52 +00:00
|
|
|
|
[source]
|
|
|
|
|
----
|
2021-01-01 22:41:42 +00:00
|
|
|
|
task 'tasks/echo' {
|
2020-12-31 22:40:08 +00:00
|
|
|
|
msg = 'Hello from the wonderful world of zplans!'
|
2020-12-30 06:16:52 +00:00
|
|
|
|
}
|
|
|
|
|
|
2021-01-01 22:41:42 +00:00
|
|
|
|
task 'tasks/echo' {
|
2020-12-31 22:40:08 +00:00
|
|
|
|
msg = 'This is nice'
|
2020-12-30 06:16:52 +00:00
|
|
|
|
}
|
2020-12-31 22:40:08 +00:00
|
|
|
|
|
2020-12-30 06:16:52 +00:00
|
|
|
|
----
|
2021-01-02 04:44:22 +00:00
|
|
|
|
|
|
|
|
|
== 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
|
|
|
|
|
|
|
|
|
|
|==
|