5.2 KiB
title, description, weight
| title | description | weight |
|---|---|---|
| Engine API reference | The descriptor and ctx APIs available to action authors. | 34 |
The surface an action author programs against: the argument descriptors in engine.descriptor and the members of the execution context. Conceptual background in Concept: The execution context.
Descriptors
from engine.descriptor import Meta, Arg, Opt, Flag, Rest
| Class | Signature | argparse mapping |
|---|---|---|
Meta |
Meta(summary, args=[]) |
Drives both the listing summary and the parser. |
Arg |
Arg(name, help="", required=True) |
Positional; required=False → nargs="?", default None. |
Opt |
Opt(name, help="", default=None) |
Value option (--name VALUE) with a default. |
Flag |
Flag(name, help="") |
Boolean store_true flag. |
Rest |
Rest(name, help="") |
Greedy remainder (argparse.REMAINDER). |
Usage errors exit 64 instead of argparse's default 2.
Warning
Restcaptures everything after the first positional — including flags. AFlagdeclared next to aRestis only recognized before the positional; an action that must accept its flag anywhere has to strip it out of the remainder itself (thecomposeaction does exactly this for--dry-run).
ctx.log
info(msg) · warn(msg) · success(msg) → stdout; error(msg) → stderr. All lines carry the [<node>] [<action>] [LEVEL] prefix.
ctx.sys
| Method | Behavior |
|---|---|
run(cmd, check=True, capture=False, cwd=None, env=None, input=None) |
subprocess.run wrapper returning CompletedProcess; capture=True collects text stdout/stderr. |
sudo(cmd, **kw) |
run(["sudo", *cmd]). |
ok(cmd, **kw) |
True iff exit 0; never raises. |
service_exists(name) / service_is_active(name) / service_is_enabled(name) |
systemd unit queries. |
start_and_enable(name) |
Start + enable when needed; returns final active state. |
ensure_running(name) |
enable --now when inactive. |
restart(name) / reload(name, dry_run=False) / daemon_reload() |
Service lifecycle. |
wait_for(name, timeout=30, interval=2) |
Poll until active. |
install_packages(packages) |
For each package: skip when its binary is on PATH, else apt-get update -y + apt-get install -y. |
ctx.tpl
| Method | Behavior |
|---|---|
render(path, vars) |
Render one file (relative paths resolve against configs/); safe_substitute semantics — unknown variables stay literal. |
render_dir(rel_dir, vars) |
Render every file under a configs/ subtree; returns {relative_path: content}. |
ctx.host
| Method | Behavior |
|---|---|
backup(path, sudo=False) |
Copy the file to <path>.<epoch>.bak; returns the backup path or None. |
write_file(path, content, backup=True, dry_run=False, sudo=False) |
Atomic install via temp file (mode 0644); optional prior backup; sudo variant preserves an existing target's mode. |
inject_block(target, content, start, end, anchor=None, old_pairs=(), dry_run=False, sudo=True) |
Managed marker-block replacement; removes current and legacy blocks, inserts after the first anchor line; False when the anchor is missing; missing target is an error. |
install_crontab(text, dry_run=False) |
Snapshot, refuse empty render (SystemExit(65)), preview, install via crontab -, restore snapshot on failure (SystemExit(1)). |
ctx.ufw
apply(rules_dir, config_dir=None, dry_run=False) — the full firewall pass: directory guards (exit 66), tool guards (ufw, ufw-docker), host rules, managed-block injection into /etc/ufw/before.rules and after.rules, container rules from *.rules files.
ctx.crowdsec
ensure_installed() · deploy(configs_subdir, vars, dry_run=False) · install_collections(collections).
ctx.systemd
deploy_units(configs_subdir, vars, dry_run=False) — render the subtree's top-level non-hidden files into /etc/systemd/system/, then daemon-reload and enable --now each .service.
ctx.notify
telegram(title, bot_url, message, node=None, level="INFO") plus the shorthands success / error / info / warn. All return bool — True only when the message was delivered; an empty bot_url logs a warning and returns False. The alert instance defaults to the node's public host (APEX_NODE_HOST) — no domain or node prefix is applied.
ctx.paths and ctx.node
ctx.paths: repo_root, commons, proprietaries, configs, compositions, core, tier1..3, stier1..3, root_tier1..3. ctx.node: the identity record (name, subnet, fqdn, host) or None in a standalone commons checkout. ctx.vars(): the template/compose environment (see Reference: Environment variables). ctx.commons.run(args): delegate to the shadowed commons action — only valid in an overriding proprietary module.
See also: