Repository navigation
Conversation
f14fdae to
40f5444
Compare
Adds a page on running nodes with puppet apply and no server: applying a control repository from a checkout, bootstrapping the first node in two phases, what a fleet without a server has to handle itself (node identity, central control with OpenBolt, disabling the old agent service), and keeping the plug-in cache in sync with a file resource. The page is in the 8.x and 9.x collections, with a nav entry after Puppet apply. Adds a 'Plug-ins under Puppet apply' subsection to the plug-ins page. puppet apply loads module facts, functions, and types directly from the modulepath, so no sync step is needed; what it does not do is fill the plug-in cache that commands such as facter -p read. Every command on the page was run as written on packaged OpenVox 8.32.0 and 9.3.0 agents, on AlmaLinux 9 and Ubuntu 24.04. Under puppet apply $trusted['extensions'] is always empty, even on a node whose certificate carries pp_role; the page says so. OpenBolt 9.0.0 compiling and applying a catalog on a target over SSH was checked separately. Part of OpenVoxProject#449 Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>
40f5444 to
d3dbbb3
Compare
|
|
||
| ## Bootstrap the first node in two phases | ||
|
|
||
| When the node is your future OpenVox Server, its real configuration should come from a deployed environment, not a temporary checkout. The [Vox Pupuli control repository's cloud-init example][controlrepo readme] splits the bootstrap in two: |
There was a problem hiding this comment.
The bootstrap commands assume the Vox Pupuli control repository, not the OpenVox control-repo template used in the previous section. The template does not ship the r10k profile or the hacked_pluginsync resource, so these tags no-op there. State that this flow is Vox Pupuli-specific, or point to the template's own bootstrap.
| --show_diff | ||
| ``` | ||
|
|
||
| The `--modulepath` must list every directory that contains modules, or plug-ins from the omitted ones won't load. In scripts and CI, add `--detailed-exitcodes` and treat exit code 2 (changes applied) as success alongside 0. |
There was a problem hiding this comment.
| The `--modulepath` must list every directory that contains modules, or plug-ins from the omitted ones won't load. In scripts and CI, add `--detailed-exitcodes` and treat exit code 2 (changes applied) as success alongside 0. | |
| The `--modulepath` must list every directory that contains modules, or plug-ins from the omitted ones won't load. This example omits `$basemodulepath`; add it if your control repo or its modules depend on Puppet's shipped modules. In scripts and CI, add `--detailed-exitcodes` and treat exit code 2 (changes applied) as success alongside 0. |
|
|
||
| Rerun step 1 whenever the Puppetfile changes and step 2 to converge. | ||
|
|
||
| Alternatively, deploy the control repository into `/etc/puppetlabs/code/environments/production` with `r10k deploy environment --modules` and apply its `manifests/site.pp` without the `--hiera_config` and `--modulepath` arguments. |
There was a problem hiding this comment.
This alternative assumes r10k is already configured with a source for this repository, usually /etc/puppetlabs/r10k/r10k.yaml. The first section only installs r10k, so r10k deploy environment --modules fails without that config. Add the prerequisite or link to the template's quick start.
|
|
||
| ## Bootstrap the first node in two phases | ||
|
|
||
| When the node is your future OpenVox Server, its real configuration should come from a deployed environment, not a temporary checkout. The [Vox Pupuli control repository's cloud-init example][controlrepo readme] splits the bootstrap in two: |
There was a problem hiding this comment.
The bootstrap commands assume the Vox Pupuli control repository, not the OpenVox control-repo template used in the previous section. The template does not ship the r10k profile or the hacked_pluginsync resource, so these tags no-op there. State that this flow is Vox Pupuli-specific, or point to the template's own bootstrap.
| --show_diff | ||
| ``` | ||
|
|
||
| The `--modulepath` must list every directory that contains modules, or plug-ins from the omitted ones won't load. In scripts and CI, add `--detailed-exitcodes` and treat exit code 2 (changes applied) as success alongside 0. |
There was a problem hiding this comment.
| The `--modulepath` must list every directory that contains modules, or plug-ins from the omitted ones won't load. In scripts and CI, add `--detailed-exitcodes` and treat exit code 2 (changes applied) as success alongside 0. | |
| The `--modulepath` must list every directory that contains modules, or plug-ins from the omitted ones won't load. This example omits `$basemodulepath`; add it if your control repo or its modules depend on Puppet's shipped modules. In scripts and CI, add `--detailed-exitcodes` and treat exit code 2 (changes applied) as success alongside 0. |
|
|
||
| Rerun step 1 whenever the Puppetfile changes and step 2 to converge. | ||
|
|
||
| Alternatively, deploy the control repository into `/etc/puppetlabs/code/environments/production` with `r10k deploy environment --modules` and apply its `manifests/site.pp` without the `--hiera_config` and `--modulepath` arguments. |
There was a problem hiding this comment.
This alternative assumes r10k is already configured with a source for this repository, usually /etc/puppetlabs/r10k/r10k.yaml. The first section only installs r10k, so r10k deploy environment --modules fails without that config. Add the prerequisite or link to the template's quick start.
| Puppet apply has no sync phase and doesn't need one. It loads custom facts, external facts, functions, resource types, and providers directly from the modulepath of the run, including during compilation and in `--noop` runs. | ||
| If a module's custom fact comes back `undef` under Puppet apply, the modulepath was incomplete for that run: either the Puppetfile modules weren't installed yet, or `--modulepath` left out a module directory. | ||
|
|
||
| A standalone run does not fill the agent directories in the table above, and other commands read them. After a run that used an explicit `--modulepath`, `facter -p` and `puppet facts` return no module facts, `puppet lookup --explain` interpolates `undef` into hierarchy levels that use them, and `puppet resource` can't find custom types. |
There was a problem hiding this comment.
This says facter -p and puppet facts return no module facts, but they read the plug-in cache. On a node that was previously an agent, the cache can still contain stale module facts. Clarify that they see no facts from the explicit modulepath and may return stale cached values until the cache is refreshed.
| Puppet apply has no sync phase and doesn't need one. It loads custom facts, external facts, functions, resource types, and providers directly from the modulepath of the run, including during compilation and in `--noop` runs. | ||
| If a module's custom fact comes back `undef` under Puppet apply, the modulepath was incomplete for that run: either the Puppetfile modules weren't installed yet, or `--modulepath` left out a module directory. | ||
|
|
||
| A standalone run does not fill the agent directories in the table above, and other commands read them. After a run that used an explicit `--modulepath`, `facter -p` and `puppet facts` return no module facts, `puppet lookup --explain` interpolates `undef` into hierarchy levels that use them, and `puppet resource` can't find custom types. |
There was a problem hiding this comment.
This says facter -p and puppet facts return no module facts, but they read the plug-in cache. On a node that was previously an agent, the cache can still contain stale module facts. Clarify that they see no facts from the explicit modulepath and may return stale cached values until the cache is refreshed.
Short description
Adds a how-to for running nodes with
puppet applyand no server: applying a control repository, bootstrapping the first node, what a fleet without a server has to handle itself, and keeping the plug-in cache in sync. The page is in the 8.x and 9.x collections.Also adds a "Plug-ins under Puppet apply" subsection to the plug-ins page.
puppet applyloads module facts, functions, and types directly from the modulepath, so the common belief that facts are missing without a sync step is wrong.Every command on the page was run as written on packaged OpenVox 8.32.0 and 9.3.0 agents.
Closes #449
Checklist
I have:
Signed-off-byannotation to each of my commitsGenerated-byorAssisted-byannotations to each of my commits created with the help of an AI agentDrafted with Claude; I reviewed and tested it.