Skip to content

Add a standalone Puppet apply how-to - #591

Open
miharp wants to merge 1 commit into
OpenVoxProject:masterfrom
miharp:docs/apply-standalone
Open

miharp wants to merge 1 commit into
OpenVoxProject:masterfrom
miharp:docs/apply-standalone

Conversation

@miharp

@miharp miharp commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Short description

Adds a how-to for running nodes with puppet apply and 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 apply loads 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

pr591-standalone-top

Checklist

I have:

Drafted with Claude; I reviewed and tested it.

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>
@miharp
miharp force-pushed the docs/apply-standalone branch from 40f5444 to d3dbbb3 Compare November 13, 2026 12:51
@miharp
miharp marked this pull request as ready for review November 13, 2026 13:09
@miharp
miharp requested a review from a team as a code owner November 13, 2026 13:09

## 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:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document standalone (masterless) puppet apply workflows

2 participants