From a0a2ed4e4e2619c97d1ca18374e1df1788216ab3 Mon Sep 17 00:00:00 2001 From: Miguel Jacq Date: Sun, 21 Jun 2026 13:26:54 +1000 Subject: [PATCH] Troubleshooting --- src/content/docs.html | 2 +- src/content/troubleshooting.html | 189 ++++++++++++++++++ .../enroll-theme/layouts/partials/nav.html | 7 +- 3 files changed, 195 insertions(+), 3 deletions(-) create mode 100644 src/content/troubleshooting.html diff --git a/src/content/docs.html b/src/content/docs.html index 7bea6e3..69594c8 100644 --- a/src/content/docs.html +++ b/src/content/docs.html @@ -158,7 +158,7 @@ description: "How Enroll works: harvest, manifest, modes, and configuration."
Does Enroll use community roles/modules?
-
When using Ansible and any Docker/Podman images, Flatpak or Snaps are 'harvested' by the system, the manifested ansible playbooks will expect to use some of those community collections, but otherwise, everything is 'core' Ansible. Enroll generates a requirements.yml you can use with ansible-galaxy to install it, if needed, but many community collections may already be on your system, depending on your installation. For Puppet and Salt, no third-party extensions or modules are used.
+
When using Ansible and any Docker/Podman images, Flatpak or Snaps are 'harvested' by the system, the manifested ansible playbooks will expect to use some of those community collections, but otherwise, everything is 'core' Ansible. Enroll generates a requirements.yml you can use with ansible-galaxy to install it, if needed, but many community collections may already be on your system, depending on your installation. For Puppet and Salt, no third-party extensions or modules are used. If you see Ansible errors about unsupported podman_image parameters or Flatpak from_url, see the Troubleshooting page.
diff --git a/src/content/troubleshooting.html b/src/content/troubleshooting.html new file mode 100644 index 0000000..aa68499 --- /dev/null +++ b/src/content/troubleshooting.html @@ -0,0 +1,189 @@ +--- +title: "Troubleshooting" +html_title: "Enroll Troubleshooting" +description: "Common Enroll errors and fixes for generated Ansible, Puppet, and Salt manifests." +--- +
+
+
Troubleshooting
+

Common errors and how to fix them

+

Most first-run problems are either missing runtime tools, old Ansible community collections, or files that Enroll intentionally skipped for safety.

+
+
+ +
+
+
+
+
+
+ Ansible collections + Podman platform error + Flatpak from_url error + JinjaTurtle + Missing files + Validate artifacts + Remote harvest + Diff enforcement +
+
+
+ +
+
+
+
+
+
+

Start here for Ansible module errors

+

Generated Ansible manifests may use community collections when a harvest contains Docker/Podman images, Flatpaks, or Snaps. Enroll writes a requirements.yml beside playbook.yml, and the generated manifest README.md shows the install command.

+
+ + 
$ cd /path/to/generated/ansible-manifest
+$ ansible-galaxy collection install -r requirements.yml
+
+

Run this in the same Python virtualenv, container, CI job, or user account that will run ansible-playbook. If an older collection is already installed and Ansible keeps finding it first, retry with --force or adjust ANSIBLE_COLLECTIONS_PATH.

+
+
+
+
+ +
+

Podman error: unsupported platform parameter

+

If the host has an older containers.podman / community.podman Galaxy collection, an Ansible run may fail with a message like this:

+
+ 
[ERROR]: Task failed: Module failed: Unsupported parameters for (containers.podman.podman_image) module: platform. Supported parameters include: arch, auth_file, build, ca_cert_dir, executable, force, name, password, path, pull, pull_extra_args, push, push_args, quadlet_dir, quadlet_file_mode, quadlet_filename, quadlet_options, state, tag, username, validate_certs (authfile, build_args, buildargs, tls_verify, tlsverify).
+
+
+
Cause
+

The generated task is using a newer module interface than the collection currently installed on the machine running Ansible.

+
+
+
Fix
+

Install the collection versions constrained by the generated manifest:

+
+ + 
$ cd /path/to/generated/ansible-manifest
+$ ansible-galaxy collection install -r requirements.yml
+
+

Then re-run the playbook from the same environment. If Ansible still reports the older module, check ansible-galaxy collection list and remove or override the stale collection path.

+
+
+ +
+

Flatpak error: unsupported from_url parameter

+

Flatpak tasks can fail in the same way when the installed community.general collection is too old for the generated role.

+
+
Fix
+

Use the generated Ansible requirements file before applying the manifest:

+
+ + 
$ cd /path/to/generated/ansible-manifest
+$ ansible-galaxy collection install -r requirements.yml
+
+
+

The same advice applies when Snap, Docker, Podman, or Flatpak roles complain about unknown module parameters: install from requirements.yml first, because Enroll generated that file for the manifest it just wrote.

+
+ +
+

Salt error: Failed to import utils pycrypto

+

You run the salt-call command and see an error Failed to import utils pycrypto, this is due most likely to a syntax error with a Traceback that includes AttributeError: module 'crypt' has no attribute 'methods'.

+
+
Fix
+

It's not an Enroll bug. Upgrade to Salt Stack 3008.1, in their Debian packages they use Python 3.14 and have solved the problem. The problem occurs with older Python, and is described in this upstream bug report.

+
+
+ +
+

JinjaTurtle is not found, or template generation was skipped

+

When --jinjaturtle auto is used, Enroll only templates recognised config files if the jinjaturtle executable is available on PATH. If it is missing, Enroll safely falls back to copying raw files. When --jinjaturtle on is used, missing JinjaTurtle is a hard error.

+
+
+
+
Make templating optional (this is the default already)
+ 
$ enroll manifest --harvest ./harvest --target ansible --out ./ansible --jinjaturtle auto
+
+
+
+
+
Disable templating entirely
+ 
$ enroll manifest --harvest ./harvest --target puppet --out ./puppet --jinjaturtle off # or --no-jinjaturtle
+
+
+
+

If a generated template would reference missing variables, Enroll should fall back to a raw file copy rather than producing a broken manifest.

+
+ +
+

A file I expected was not harvested

+

The default harvest is intentionally conservative. A file may be skipped because it matched an exclude pattern, looked sensitive, looked binary, was too large, was already captured by another role, or was outside Enroll's standard scan paths.

+
+
+
+
Explicitly include a path
+ 
$ enroll harvest --out ./harvest --include-path /opt/myapp/config.yml
+
+
+
+
+
Inspect what happened
+ 
$ enroll explain ./harvest
+$ enroll validate ./harvest
+
+
+
+
+
Be careful with --dangerous
+
Use --dangerous only when you understand that it can harvest secrets such as private keys, tokens, credentials, and application config containing passwords.
+
+
+ +
+

Generated manifest references a missing artifact

+

If a manifest task points at a missing source file, validate the original harvest first. Validation checks state.json, referenced artifacts, generated firewall/sysctl files, and unreferenced artifact warnings.

+
+ + 
$ enroll validate /path/to/harvest
+
+

If validation passes, check whether you moved, edited, or partially copied the generated manifest after rendering it.

+
+ +
+

Remote harvest cannot sudo or cannot unlock an SSH key

+

Remote mode can prompt for sudo and private-key passphrases, but CI and non-interactive shells should pass the required information up front. You can set the ENROLL_SSH_KEY_PASSPHRASE environment variable if needed, and then pass --ssh-key-passphrase-env ENROLL_SSH_KEY_PASSPHRASE.

+
+
+
+
Prompt for sudo
+ 
$ enroll harvest --remote-host host.example.net --ask-become-pass --out ./harvest
+
+
+
+
+
Prompt for encrypted SSH key
+ 
$ enroll harvest --remote-host host.example.net --ask-key-passphrase --out ./harvest
+
+
+
+

If host key verification fails, connect with normal ssh first so the expected key is in known_hosts, or use your normal SSH config with Enroll's remote SSH config support.

+
+ +
+

enroll diff --enforce did not change everything

+

Enforcement is best-effort drift correction from the old harvest. It is intentionally conservative and does not try to do risky things such as arbitrary package downgrades.

+
+
Choose the enforcement target explicitly
+

By default, enforcement uses Ansible. You can choose Puppet or Salt when those tools are available on the host running enforcement:

+
+ + 
$ enroll diff --old ./golden --new ./current --enforce --target ansible
+$ enroll diff --old ./golden --new ./current --enforce --target puppet
+$ enroll diff --old ./golden --new ./current --enforce --target salt
+
+
+

For non-Ansible targets, make sure puppet or salt-call is installed and on PATH before running enforcement.

+
+
+
+
+
diff --git a/src/themes/enroll-theme/layouts/partials/nav.html b/src/themes/enroll-theme/layouts/partials/nav.html index 3812e8f..c49b719 100644 --- a/src/themes/enroll-theme/layouts/partials/nav.html +++ b/src/themes/enroll-theme/layouts/partials/nav.html @@ -12,6 +12,9 @@