This commit is contained in:
parent
89831d600b
commit
a0a2ed4e4e
GPG key ID:
03906B4110AAD3B8
3 changed files with 195 additions and 3 deletions
|
|
@ -158,7 +158,7 @@ description: "How Enroll works: harvest, manifest, modes, and configuration."
|
||||||
|
|
||||||
<div class="alert alert-secondary mt-3 mb-0">
|
<div class="alert alert-secondary mt-3 mb-0">
|
||||||
<div class="fw-semibold">Does Enroll use community roles/modules?</div>
|
<div class="fw-semibold">Does Enroll use community roles/modules?</div>
|
||||||
<div class="small mb-0">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 <code>requirements.yml</code> you can use with <code>ansible-galaxy</code> 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.</div>
|
<div class="small mb-0">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 <code>requirements.yml</code> you can use with <code>ansible-galaxy</code> 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 <code>podman_image</code> parameters or Flatpak <code>from_url</code>, see the <a href="troubleshooting.html">Troubleshooting</a> page.</div>
|
||||||
</div>
|
</div>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
|
||||||
189
src/content/troubleshooting.html
Normal file
189
src/content/troubleshooting.html
Normal file
|
|
@ -0,0 +1,189 @@
|
||||||
|
---
|
||||||
|
title: "Troubleshooting"
|
||||||
|
html_title: "Enroll Troubleshooting"
|
||||||
|
description: "Common Enroll errors and fixes for generated Ansible, Puppet, and Salt manifests."
|
||||||
|
---
|
||||||
|
<header class="py-5 hero">
|
||||||
|
<div class="container py-3">
|
||||||
|
<div class="kicker mb-3"><i class="bi bi-tools"></i> Troubleshooting</div>
|
||||||
|
<h1 class="display-6 fw-bold mb-2">Common errors and how to fix them</h1>
|
||||||
|
<p class="lead mb-0">Most first-run problems are either missing runtime tools, old Ansible community collections, or files that Enroll intentionally skipped for safety.</p>
|
||||||
|
</div>
|
||||||
|
</header>
|
||||||
|
|
||||||
|
<main class="py-5">
|
||||||
|
<div class="container">
|
||||||
|
<div class="row g-4">
|
||||||
|
<div class="col-lg-3">
|
||||||
|
<div class="position-sticky" style="top: 96px;">
|
||||||
|
<div class="list-group">
|
||||||
|
<a class="list-group-item list-group-item-action" href="#ansible-collections">Ansible collections</a>
|
||||||
|
<a class="list-group-item list-group-item-action" href="#podman-platform">Podman platform error</a>
|
||||||
|
<a class="list-group-item list-group-item-action" href="#flatpak-from-url">Flatpak from_url error</a>
|
||||||
|
<a class="list-group-item list-group-item-action" href="#jinjaturtle">JinjaTurtle</a>
|
||||||
|
<a class="list-group-item list-group-item-action" href="#missing-files">Missing files</a>
|
||||||
|
<a class="list-group-item list-group-item-action" href="#validate">Validate artifacts</a>
|
||||||
|
<a class="list-group-item list-group-item-action" href="#remote">Remote harvest</a>
|
||||||
|
<a class="list-group-item list-group-item-action" href="#enforce">Diff enforcement</a>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div class="col-lg-9">
|
||||||
|
<section id="ansible-collections" class="scroll-mt-nav mb-5">
|
||||||
|
<div class="feature-card p-4 border border-warning">
|
||||||
|
<div class="d-flex align-items-start gap-3">
|
||||||
|
<div class="icon-pill" style="background: rgba(255,193,7,0.20); border-color: rgba(255,193,7,0.45);"><i class="bi bi-box-seam"></i></div>
|
||||||
|
<div>
|
||||||
|
<h2 class="h4 fw-bold mb-2">Start here for Ansible module errors</h2>
|
||||||
|
<p class="text-secondary mb-3">Generated Ansible manifests may use community collections when a harvest contains Docker/Podman images, Flatpaks, or Snaps. Enroll writes a <code>requirements.yml</code> beside <code>playbook.yml</code>, and the generated manifest <code>README.md</code> shows the install command.</p>
|
||||||
|
<div class="codeblock terminal">
|
||||||
|
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#trouble-ansible-galaxy"><i class="bi bi-clipboard"></i> Copy</button>
|
||||||
|
<pre class="mb-0"><code id="trouble-ansible-galaxy"><span class="prompt">$</span> cd /path/to/generated/ansible-manifest
|
||||||
|
<span class="prompt">$</span> ansible-galaxy collection install -r requirements.yml</code></pre>
|
||||||
|
</div>
|
||||||
|
<p class="small text-secondary mt-3 mb-0">Run this in the same Python virtualenv, container, CI job, or user account that will run <code>ansible-playbook</code>. If an older collection is already installed and Ansible keeps finding it first, retry with <code>--force</code> or adjust <code>ANSIBLE_COLLECTIONS_PATH</code>.</p>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="podman-platform" class="scroll-mt-nav mb-5">
|
||||||
|
<h2 class="section-title fw-bold">Podman error: unsupported <code>platform</code> parameter</h2>
|
||||||
|
<p class="text-secondary">If the host has an older <code>containers.podman</code> / <code>community.podman</code> Galaxy collection, an Ansible run may fail with a message like this:</p>
|
||||||
|
<div class="codeblock terminal">
|
||||||
|
<pre class="mb-0"><code>[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).</code></pre>
|
||||||
|
</div>
|
||||||
|
<div class="callout p-4 mt-3">
|
||||||
|
<div class="fw-semibold mb-2">Cause</div>
|
||||||
|
<p class="small text-secondary mb-0">The generated task is using a newer module interface than the collection currently installed on the machine running Ansible.</p>
|
||||||
|
</div>
|
||||||
|
<div class="callout p-4 mt-3">
|
||||||
|
<div class="fw-semibold mb-2">Fix</div>
|
||||||
|
<p class="small text-secondary mb-3">Install the collection versions constrained by the generated manifest:</p>
|
||||||
|
<div class="codeblock terminal">
|
||||||
|
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#trouble-podman-fix"><i class="bi bi-clipboard"></i> Copy</button>
|
||||||
|
<pre class="mb-0"><code id="trouble-podman-fix"><span class="prompt">$</span> cd /path/to/generated/ansible-manifest
|
||||||
|
<span class="prompt">$</span> ansible-galaxy collection install -r requirements.yml</code></pre>
|
||||||
|
</div>
|
||||||
|
<p class="small text-secondary mt-3 mb-0">Then re-run the playbook from the same environment. If Ansible still reports the older module, check <code>ansible-galaxy collection list</code> and remove or override the stale collection path.</p>
|
||||||
|
</div>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="flatpak-from-url" class="scroll-mt-nav mb-5">
|
||||||
|
<h2 class="section-title fw-bold">Flatpak error: unsupported <code>from_url</code> parameter</h2>
|
||||||
|
<p class="text-secondary">Flatpak tasks can fail in the same way when the installed <code>community.general</code> collection is too old for the generated role.</p>
|
||||||
|
<div class="callout p-4">
|
||||||
|
<div class="fw-semibold mb-2">Fix</div>
|
||||||
|
<p class="small text-secondary mb-3">Use the generated Ansible requirements file before applying the manifest:</p>
|
||||||
|
<div class="codeblock terminal">
|
||||||
|
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#trouble-flatpak-fix"><i class="bi bi-clipboard"></i> Copy</button>
|
||||||
|
<pre class="mb-0"><code id="trouble-flatpak-fix"><span class="prompt">$</span> cd /path/to/generated/ansible-manifest
|
||||||
|
<span class="prompt">$</span> ansible-galaxy collection install -r requirements.yml</code></pre>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<p class="small text-secondary mt-3 mb-0">The same advice applies when Snap, Docker, Podman, or Flatpak roles complain about unknown module parameters: install from <code>requirements.yml</code> first, because Enroll generated that file for the manifest it just wrote.</p>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="salt-pycrypto-error" class="scroll-mt-nav mb-5">
|
||||||
|
<h2 class="section-title fw-bold">Salt error: <code>Failed to import utils pycrypto</code></h2>
|
||||||
|
<p class="text-secondary">You run the salt-call command and see an error <code>Failed to import utils pycrypto, this is due most likely to a syntax error</code> with a Traceback that includes <code>AttributeError: module 'crypt' has no attribute 'methods'</code>.</p>
|
||||||
|
<div class="callout p-4">
|
||||||
|
<div class="fw-semibold mb-2">Fix</div>
|
||||||
|
<p class="small text-secondary mb-3">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 <a href="https://github.com/saltstack/salt/issues/67118" target="_blank" rel="noopener noreferrer">this upstream bug report</a>.</p>
|
||||||
|
</div>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="jinjaturtle" class="scroll-mt-nav mb-5">
|
||||||
|
<h2 class="section-title fw-bold">JinjaTurtle is not found, or template generation was skipped</h2>
|
||||||
|
<p class="text-secondary">When <code>--jinjaturtle auto</code> is used, Enroll only templates recognised config files if the <code>jinjaturtle</code> executable is available on <code>PATH</code>. If it is missing, Enroll safely falls back to copying raw files. When <code>--jinjaturtle on</code> is used, missing JinjaTurtle is a hard error.</p>
|
||||||
|
<div class="row g-3">
|
||||||
|
<div class="col-md-6">
|
||||||
|
<div class="callout p-4 h-100">
|
||||||
|
<div class="fw-semibold mb-2">Make templating optional (this is the default already)</div>
|
||||||
|
<div class="terminal"><pre class="mb-0"><code><span class="prompt">$</span> enroll manifest --harvest ./harvest --target ansible --out ./ansible --jinjaturtle auto</code></pre></div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div class="col-md-6">
|
||||||
|
<div class="callout p-4 h-100">
|
||||||
|
<div class="fw-semibold mb-2">Disable templating entirely</div>
|
||||||
|
<div class="terminal"><pre class="mb-0"><code><span class="prompt">$</span> enroll manifest --harvest ./harvest --target puppet --out ./puppet --jinjaturtle off # or --no-jinjaturtle</code></pre></div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<p class="small text-secondary mt-3 mb-0">If a generated template would reference missing variables, Enroll should fall back to a raw file copy rather than producing a broken manifest.</p>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="missing-files" class="scroll-mt-nav mb-5">
|
||||||
|
<h2 class="section-title fw-bold">A file I expected was not harvested</h2>
|
||||||
|
<p class="text-secondary">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.</p>
|
||||||
|
<div class="row g-3">
|
||||||
|
<div class="col-md-6">
|
||||||
|
<div class="callout p-4 h-100">
|
||||||
|
<div class="fw-semibold mb-2">Explicitly include a path</div>
|
||||||
|
<div class="terminal"><pre class="mb-0"><code><span class="prompt">$</span> enroll harvest --out ./harvest --include-path /opt/myapp/config.yml</code></pre></div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div class="col-md-6">
|
||||||
|
<div class="callout p-4 h-100">
|
||||||
|
<div class="fw-semibold mb-2">Inspect what happened</div>
|
||||||
|
<div class="terminal"><pre class="mb-0"><code><span class="prompt">$</span> enroll explain ./harvest
|
||||||
|
<span class="prompt">$</span> enroll validate ./harvest</code></pre></div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div class="alert alert-warning mt-3 mb-0">
|
||||||
|
<div class="fw-semibold">Be careful with <code>--dangerous</code></div>
|
||||||
|
<div class="small mb-0">Use <code>--dangerous</code> only when you understand that it can harvest secrets such as private keys, tokens, credentials, and application config containing passwords.</div>
|
||||||
|
</div>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="validate" class="scroll-mt-nav mb-5">
|
||||||
|
<h2 class="section-title fw-bold">Generated manifest references a missing artifact</h2>
|
||||||
|
<p class="text-secondary">If a manifest task points at a missing source file, validate the original harvest first. Validation checks <code>state.json</code>, referenced artifacts, generated firewall/sysctl files, and unreferenced artifact warnings.</p>
|
||||||
|
<div class="codeblock terminal">
|
||||||
|
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#trouble-validate"><i class="bi bi-clipboard"></i> Copy</button>
|
||||||
|
<pre class="mb-0"><code id="trouble-validate"><span class="prompt">$</span> enroll validate /path/to/harvest</code></pre>
|
||||||
|
</div>
|
||||||
|
<p class="small text-secondary mt-3 mb-0">If validation passes, check whether you moved, edited, or partially copied the generated manifest after rendering it.</p>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="remote" class="scroll-mt-nav mb-5">
|
||||||
|
<h2 class="section-title fw-bold">Remote harvest cannot sudo or cannot unlock an SSH key</h2>
|
||||||
|
<p class="text-secondary">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 <code>ENROLL_SSH_KEY_PASSPHRASE</code> environment variable if needed, and then pass <code>--ssh-key-passphrase-env ENROLL_SSH_KEY_PASSPHRASE</code>.</p>
|
||||||
|
<div class="row g-3">
|
||||||
|
<div class="col-md-6">
|
||||||
|
<div class="callout p-4 h-100">
|
||||||
|
<div class="fw-semibold mb-2">Prompt for sudo</div>
|
||||||
|
<div class="terminal"><pre class="mb-0"><code><span class="prompt">$</span> enroll harvest --remote-host host.example.net --ask-become-pass --out ./harvest</code></pre></div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div class="col-md-6">
|
||||||
|
<div class="callout p-4 h-100">
|
||||||
|
<div class="fw-semibold mb-2">Prompt for encrypted SSH key</div>
|
||||||
|
<div class="terminal"><pre class="mb-0"><code><span class="prompt">$</span> enroll harvest --remote-host host.example.net --ask-key-passphrase --out ./harvest</code></pre></div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<p class="small text-secondary mt-3 mb-0">If host key verification fails, connect with normal <code>ssh</code> first so the expected key is in <code>known_hosts</code>, or use your normal SSH config with Enroll's remote SSH config support.</p>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="enforce" class="scroll-mt-nav mb-5">
|
||||||
|
<h2 class="section-title fw-bold"><code>enroll diff --enforce</code> did not change everything</h2>
|
||||||
|
<p class="text-secondary">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.</p>
|
||||||
|
<div class="callout p-4">
|
||||||
|
<div class="fw-semibold mb-2">Choose the enforcement target explicitly</div>
|
||||||
|
<p class="small text-secondary mb-3">By default, enforcement uses Ansible. You can choose Puppet or Salt when those tools are available on the host running enforcement:</p>
|
||||||
|
<div class="codeblock terminal">
|
||||||
|
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#trouble-enforce"><i class="bi bi-clipboard"></i> Copy</button>
|
||||||
|
<pre class="mb-0"><code id="trouble-enforce"><span class="prompt">$</span> enroll diff --old ./golden --new ./current --enforce --target ansible
|
||||||
|
<span class="prompt">$</span> enroll diff --old ./golden --new ./current --enforce --target puppet
|
||||||
|
<span class="prompt">$</span> enroll diff --old ./golden --new ./current --enforce --target salt</code></pre>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<p class="small text-secondary mt-3 mb-0">For non-Ansible targets, make sure <code>puppet</code> or <code>salt-call</code> is installed and on <code>PATH</code> before running enforcement.</p>
|
||||||
|
</section>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</main>
|
||||||
|
|
@ -12,6 +12,9 @@
|
||||||
|
|
||||||
<div class="collapse navbar-collapse" id="nav">
|
<div class="collapse navbar-collapse" id="nav">
|
||||||
<ul class="navbar-nav ms-auto align-items-lg-center gap-lg-2">
|
<ul class="navbar-nav ms-auto align-items-lg-center gap-lg-2">
|
||||||
|
<li class="nav-item">
|
||||||
|
<a class="nav-link" href="{{ "news.html" | relURL }}">News</a>
|
||||||
|
</li>
|
||||||
<li class="nav-item">
|
<li class="nav-item">
|
||||||
<a class="nav-link" href="{{ "docs.html" | relURL }}">Docs</a>
|
<a class="nav-link" href="{{ "docs.html" | relURL }}">Docs</a>
|
||||||
</li>
|
</li>
|
||||||
|
|
@ -19,10 +22,10 @@
|
||||||
<a class="nav-link" href="{{ "examples.html" | relURL }}">Examples</a>
|
<a class="nav-link" href="{{ "examples.html" | relURL }}">Examples</a>
|
||||||
</li>
|
</li>
|
||||||
<li class="nav-item">
|
<li class="nav-item">
|
||||||
<a class="nav-link" href="{{ "news.html" | relURL }}">News</a>
|
<a class="nav-link" href="{{ "security.html" | relURL }}">Security Design</a>
|
||||||
</li>
|
</li>
|
||||||
<li class="nav-item">
|
<li class="nav-item">
|
||||||
<a class="nav-link" href="{{ "security.html" | relURL }}">Security Design</a>
|
<a class="nav-link" href="{{ "troubleshooting.html" | relURL }}">Troubleshooting</a>
|
||||||
</li>
|
</li>
|
||||||
|
|
||||||
<li class="nav-item ms-lg-2">
|
<li class="nav-item ms-lg-2">
|
||||||
|
|
|
||||||
Reference in a new issue