mig5/enroll
1
0
Fork 0
Code Issues Pull requests Projects Releases 11 Packages Wiki Activity Actions
Page: enroll single-shot
Pages
Contact Me Home Technical_Decomp_Accounts Technical_Decomp_Cache Technical_Decomp_Diff Technical_Decomp_Harvest Technical_Decomp_Ignore Technical_Decomp_JinjaTurtle Technical_Decomp_Manifest Technical_Decomp_PathFilter Technical_Decomp_SopsUtil Technical_Decomp_Systemd Troubleshooting enroll single-shot enroll diff enroll harvest enroll manifest
2 enroll single-shot
Miguel Jacq edited this page 2025-12-17 22:49:02 -06:00
Table of Contents

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

enroll single-shot   \
  --harvest <DIR>   \
  --out <DIR|FILE>   \
  [--fqdn <HOST>]   \
  [--dangerous]   \
  [--sops <GPG_FPR...>]   \
  [--jinjaturtle | --no-jinjaturtle]   \
  [--remote-host <HOST>]  [--remote-user <USER>]  [--remote-port <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)
  1. 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 <dir>

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 <path>

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 <host>

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

NOTE: Strongly consider using --sops when you enable --dangerous.

--sops <GPG_FINGERPRINT...>

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.

NOTE: If you want plaintext harvest but encrypted manifest (or the other way around), use enroll harvest and enroll manifest separately instead of enroll 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 <host>

Run the harvest phase on a remote host over SSH, then generate the manifest locally.

--remote-user <user>

SSH username (default: local $USER).

--remote-port <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

enroll single-shot --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible

Local, plain, site mode (--fqdn)

enroll single-shot --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --fqdn "$(hostname -f)"

Local, plain, --dangerous

enroll single-shot --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --dangerous

Local, plain, control JinjaTurtle

Force off:

enroll single-shot --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --no-jinjaturtle

Force on:

enroll single-shot --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --jinjaturtle

Local, SOPS-encrypted (--sops) output

Output to directory:

enroll single-shot --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --sops <FPR1>
# writes /tmp/enroll-harvest/harvest.tar.gz.sops and /tmp/enroll-ansible/manifest.tar.gz.sops

Output to a specific manifest file:

enroll single-shot --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible/manifest.tar.gz.sops --sops <FPR1>

Local, SOPS-encrypted + --dangerous

enroll single-shot --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --dangerous --sops <FPR1>

Local, SOPS-encrypted + site mode

enroll single-shot   --harvest /tmp/enroll-harvest   --out /tmp/enroll-ansible   --fqdn "$(hostname -f)"   --sops <FPR1>

Remote, plain, single-site

enroll single-shot   --remote-host host.example.com   --harvest /tmp/enroll-harvest   --out /tmp/enroll-ansible

Remote, plain, site mode

enroll single-shot   --remote-host host.example.com   --harvest /tmp/enroll-harvest   --out /tmp/enroll-ansible   --fqdn "host.example.com"

Remote, plain, --dangerous

enroll single-shot   --remote-host host.example.com   --harvest /tmp/enroll-harvest   --out /tmp/enroll-ansible   --dangerous

Remote, plain, without sudo

enroll single-shot   --remote-host host.example.com   --no-sudo   --harvest /tmp/enroll-harvest   --out /tmp/enroll-ansible

Remote, SOPS-encrypted output

enroll single-shot   --remote-host host.example.com   --harvest /tmp/enroll-harvest   --out /tmp/enroll-ansible   --sops <FPR1>

Remote, SOPS-encrypted + --dangerous + site mode

enroll single-shot   --remote-host host.example.com   --harvest /tmp/enroll-harvest   --out /tmp/enroll-ansible   --fqdn "host.example.com"   --dangerous   --sops <FPR1>

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:

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.