diff --git a/enroll single-shot.-.md b/enroll single-shot.-.md new file mode 100644 index 0000000..24b6aa3 --- /dev/null +++ b/enroll single-shot.-.md @@ -0,0 +1,214 @@ +# enroll single-shot + +Run **harvest -> manifest** in one command. + +This is the convenience "do the whole thing" mode: it collects a harvest bundle (locally or remotely) and immediately generates an Ansible manifest from it. + +--- + +## Synopsis + +```bash +enroll single-shot --harvest --out [--fqdn ] [--dangerous] [--sops ] [--jinjaturtle | --no-jinjaturtle] [--remote-host [--remote-user ] [--remote-port ] [--no-sudo]] +``` + +--- + +## What it does + +1) **Harvest phase** +- Runs the same logic as `enroll harvest` +- Produces a harvest bundle (plaintext directory unless `--sops` is enabled) + +2) **Manifest phase** +- Runs the same logic as `enroll manifest` +- Produces an Ansible output tree (plaintext directory unless `--sops` is enabled) +- `--fqdn` controls whether the output is **single-site** (default) or **site mode** + +--- + +## Required arguments + +### `--harvest ` +Where to write the (intermediate) harvest bundle. + +- In single-shot, `--harvest` is treated as a **directory path**. +- It may be: + - a newly created directory, or + - an existing directory (contents may be overwritten/updated) + +> Note: Unlike `enroll harvest`, single-shot assumes you want a concrete directory for the intermediate harvest output. + +### `--out ` +Where to write the final manifest output. + +- **Plain mode (no `--sops`)** + - must be a directory path +- **SOPS mode (`--sops ...`)** + - may be a directory (writes `manifest.tar.gz.sops` inside), or + - may be a file path (writes that exact file) + +--- + +## Options + +### `--fqdn ` +Enable "site mode" output (inventory + per-host vars) in the manifest phase. + +If omitted, output is generated in "single-site mode" with a top-level `playbook.yml`. + +### `--dangerous` +Applies to the harvest phase. + +Disables "likely secret" safety checks, potentially collecting: +- private keys +- TLS key material +- database passwords +- API tokens +- other credentials + +Strongly consider using `--sops` when you enable `--dangerous`. + +### `--sops ` +Enable SOPS "encrypt at rest" mode for single-shot. + +In single-shot, `--sops` affects **both** phases: + +- Harvest output is written as a SOPS file (typically `harvest.tar.gz.sops`) in the harvest directory +- Manifest output is written as a SOPS file (typically `manifest.tar.gz.sops`) in the output location + +Requires `sops` available on `PATH`. + +> If you want plaintext harvest but encrypted manifest (or the other way around), use `enroll harvest` and `enroll manifest` separately instead of single-shot. + +### JinjaTurtle integration + +#### `--jinjaturtle` +Force templating **on** for the manifest phase (errors if not installed). + +#### `--no-jinjaturtle` +Force templating **off** for the manifest phase. + +#### Default (no flag) +Auto mode: use JinjaTurtle if found on `PATH`. + +### Remote harvesting + +#### `--remote-host ` +Run the harvest phase on a remote host over SSH, then generate the manifest locally. + +#### `--remote-user ` +SSH username (default: local `$USER`). + +#### `--remote-port ` +SSH port (default: `22`). + +#### `--no-sudo` +Don’t use sudo on the remote host (may result in partial harvest). + +--- + +## Permutations (valid combinations) + +### Local, plain, single-site +```bash +enroll single-shot --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible +``` + +### Local, plain, site mode (`--fqdn`) +```bash +enroll single-shot --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --fqdn "$(hostname -f)" +``` + +### Local, plain, `--dangerous` +```bash +enroll single-shot --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --dangerous +``` + +### Local, plain, control JinjaTurtle +Force off: +```bash +enroll single-shot --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --no-jinjaturtle +``` + +Force on: +```bash +enroll single-shot --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --jinjaturtle +``` + +--- + +### Local, SOPS-encrypted (`--sops`) output +Output to directory: +```bash +enroll single-shot --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --sops +# writes /tmp/enroll-harvest/harvest.tar.gz.sops and /tmp/enroll-ansible/manifest.tar.gz.sops +``` + +Output to a specific manifest file: +```bash +enroll single-shot --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible/manifest.tar.gz.sops --sops +``` + +### Local, SOPS-encrypted + `--dangerous` +```bash +enroll single-shot --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --dangerous --sops +``` + +### Local, SOPS-encrypted + site mode +```bash +enroll single-shot --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --fqdn "$(hostname -f)" --sops +``` + +--- + +### Remote, plain, single-site +```bash +enroll single-shot --remote-host host.example.com --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible +``` + +### Remote, plain, site mode +```bash +enroll single-shot --remote-host host.example.com --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --fqdn "host.example.com" +``` + +### Remote, plain, `--dangerous` +```bash +enroll single-shot --remote-host host.example.com --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --dangerous +``` + +### Remote, plain, without sudo +```bash +enroll single-shot --remote-host host.example.com --no-sudo --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible +``` + +### Remote, SOPS-encrypted output +```bash +enroll single-shot --remote-host host.example.com --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --sops +``` + +### Remote, SOPS-encrypted + `--dangerous` + site mode +```bash +enroll single-shot --remote-host host.example.com --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --fqdn "host.example.com" --dangerous --sops +``` + +--- + +## Working with the encrypted manifest output + +If you used `--sops`, the final output is a single file (typically `manifest.tar.gz.sops`). To use it with Ansible: + +```bash +mkdir -p /tmp/enroll-manifest && cd /tmp/enroll-manifest +sops -d /path/to/manifest.tar.gz.sops | tar -xzvf - +``` + +Then run Ansible from inside the extracted tree. + +--- + +## Common gotchas + +- `--dangerous` affects **harvest only** (but in single-shot it still impacts what ends up in the manifest). +- In SOPS mode, you must decrypt/extract before running Ansible. +- If you want to mix plaintext and SOPS between phases, use `harvest` and `manifest` separately instead of single-shot.