From d3dbbb33ba844991b720623ffe08755601d14806 Mon Sep 17 00:00:00 2001 From: Michael Harp Date: Fri, 13 Nov 2026 07:51:08 -0500 Subject: [PATCH] Add a standalone Puppet apply how-to 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 #449 Co-authored-by: Claude Fable 5.2 Signed-off-by: Michael Harp --- _data/nav/openvox_8x.yml | 2 + _data/nav/openvox_9x.yml | 2 + docs/_openvox_8x/plugins_in_modules.markdown | 8 ++ docs/_openvox_8x/services_apply.markdown | 2 +- .../services_apply_standalone.markdown | 125 ++++++++++++++++++ docs/_openvox_9x/plugins_in_modules.markdown | 8 ++ docs/_openvox_9x/services_apply.markdown | 2 +- .../services_apply_standalone.markdown | 125 ++++++++++++++++++ 8 files changed, 272 insertions(+), 2 deletions(-) create mode 100644 docs/_openvox_8x/services_apply_standalone.markdown create mode 100644 docs/_openvox_9x/services_apply_standalone.markdown diff --git a/_data/nav/openvox_8x.yml b/_data/nav/openvox_8x.yml index 763e70e325..bb5e2774da 100644 --- a/_data/nav/openvox_8x.yml +++ b/_data/nav/openvox_8x.yml @@ -137,6 +137,8 @@ link: "services_agent_windows.html" - text: Puppet apply link: "services_apply.html" + - text: Standalone workflows with Puppet apply + link: "services_apply_standalone.html" - text: The Puppet language items: - text: Visual index diff --git a/_data/nav/openvox_9x.yml b/_data/nav/openvox_9x.yml index df6ac496a7..624b7528a1 100644 --- a/_data/nav/openvox_9x.yml +++ b/_data/nav/openvox_9x.yml @@ -137,6 +137,8 @@ link: "services_agent_windows.html" - text: Puppet apply link: "services_apply.html" + - text: Standalone workflows with Puppet apply + link: "services_apply_standalone.html" - text: The Puppet language items: - text: Visual index diff --git a/docs/_openvox_8x/plugins_in_modules.markdown b/docs/_openvox_8x/plugins_in_modules.markdown index 531e7091fe..8303d8f2a1 100644 --- a/docs/_openvox_8x/plugins_in_modules.markdown +++ b/docs/_openvox_8x/plugins_in_modules.markdown @@ -49,6 +49,14 @@ Translations | `/locales` | `locales` | `/locales` (`` is OpenVox agent's [cache directory][vardir], which is located at `/var/opt/puppetlabs/puppet/cache`, `%PROGRAMDATA%\PuppetLabs\puppet\cache`, or `~/.puppetlabs/opt/puppet/cache`.) +### Plug-ins under Puppet apply + +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. +Even with the modules deployed in the default environment, `facter -p` reads only the cache. To fill the cache on standalone nodes, see [Keep the plug-in cache in sync](services_apply_standalone.html#keep-the-plug-in-cache-in-sync). + ## Types of plug-ins OpenVox supports several kinds of plug-ins: diff --git a/docs/_openvox_8x/services_apply.markdown b/docs/_openvox_8x/services_apply.markdown index 65085bf1c4..b303f2c37e 100644 --- a/docs/_openvox_8x/services_apply.markdown +++ b/docs/_openvox_8x/services_apply.markdown @@ -21,7 +21,7 @@ title: "Puppet's services: Puppet apply" Puppet apply is an application that compiles and manages configurations on nodes. It acts like a self-contained combination of the OpenVox Server and OpenVox agent applications. For more info about Puppet's architecture, see [Overview of Puppet's Architecture](./architecture.html) --- in particular, read the note at the end about [differences and trade-offs between agent/master and puppet apply.](architecture.html#differences-between-agent-server-and-stand-alone) -For details about invoking the Puppet apply command, see [the puppet apply man page][man]. +For details about invoking the Puppet apply command, see [the puppet apply man page][man]. For running whole nodes with Puppet apply instead of an agent, see [Standalone workflows with Puppet apply](services_apply_standalone.html). ## Supported platforms diff --git a/docs/_openvox_8x/services_apply_standalone.markdown b/docs/_openvox_8x/services_apply_standalone.markdown new file mode 100644 index 0000000000..90748e095a --- /dev/null +++ b/docs/_openvox_8x/services_apply_standalone.markdown @@ -0,0 +1,125 @@ +--- +layout: default +title: "Standalone workflows with Puppet apply" +--- + +[apply]: services_apply.html +[apply plugins]: plugins_in_modules.html#plug-ins-under-puppet-apply +[architecture]: architecture.html#the-stand-alone-architecture +[tradeoffs]: architecture.html#differences-between-agent-server-and-stand-alone +[trusted facts]: lang_facts_and_builtin_vars.html#trusted-facts +[install]: install_pre.html +[template]: https://github.com/OpenVoxProject/control-repo-template +[controlrepo site.pp]: https://github.com/voxpupuli/controlrepo/blob/production/manifests/site.pp +[controlrepo readme]: https://github.com/voxpupuli/controlrepo#hetzner-cloud-cloud-init-userdata +[r10k]: https://github.com/puppetlabs/r10k +[schedule]: services_apply.html#managing-systems-with-puppet-apply +[enc]: nodes_external.html +[openvoxdb apply]: /openvoxdb/latest/connect_puppet_apply.html +[openbolt]: /openbolt/latest/running_bolt_commands.html +[openbolt apply]: /openbolt/latest/applying_manifest_blocks.html + +In a [standalone deployment][architecture] (often called "masterless"), each node compiles and applies its own catalog with [Puppet apply][apply] instead of requesting one from a server. That fits four situations: + +* **Bootstrapping the first node.** The node that will become your OpenVox Server can't get its configuration from a server that doesn't exist yet. +* **Disposable test environments.** Lab VMs, containers, and CI jobs can apply a control repository checkout with no server or certificate setup. +* **Single-node setups.** A node that only manages itself doesn't need a server. +* **Fleets that don't justify a server.** Every node holds a copy of the control repository and applies it on a schedule. + +For Puppet apply's general behavior (logging, reporting, scheduling), see [the Puppet apply service page][apply]. For the trade-offs against agent-server, see the [architecture overview][tradeoffs]. + +## Apply a control repository standalone + +[Install the openvox-agent package][install] on the node and clone your control repository onto it. These steps assume the layout of the [OpenVox control repository template][template], which applies standalone as shipped, and use paths relative to the checkout. + +1. Install the Puppetfile modules into `modules/` with [r10k][]: + + ```console + sudo /opt/puppetlabs/puppet/bin/gem install --no-document r10k + cd /path/to/control-repo + /opt/puppetlabs/puppet/bin/r10k puppetfile install --verbose + ``` + +2. Apply the main manifest: + + ```console + sudo /opt/puppetlabs/bin/puppet apply manifests/site.pp \ + --hiera_config hiera.yaml \ + --modulepath site-modules:modules \ + --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. + +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. + +## 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: + +1. From the initial checkout, apply only the tagged bootstrap resources: + + ```console + sudo /opt/puppetlabs/bin/puppet apply \ + /root/control-repo/manifests/site.pp \ + --modulepath /root/control-repo/modules:/root/control-repo/site \ + --hiera_config /root/control-repo/hiera.yaml \ + --tags r10k,hacked_pluginsync + ``` + + This configures r10k and fills the [plug-in cache](#keep-the-plug-in-cache-in-sync). `--tags` limits which resources are *applied*, not what is compiled, so the checkout still needs its Puppetfile modules installed and its Hiera data reachable. + +2. Deploy the real environment with the r10k configuration from phase 1, then apply from it: + + ```console + sudo /opt/puppetlabs/puppet/bin/r10k deploy environment \ + --modules --verbose + sudo /opt/puppetlabs/bin/puppet apply \ + /etc/puppetlabs/code/environments/production/manifests/site.pp + ``` + +Once the node's role includes the OpenVox Server profile, later runs can switch to `puppet agent -t` against the new server. + +## Run a fleet without a server + +Running every node standalone means replacing what the server did centrally. The [architecture overview][tradeoffs] covers the trade-offs, [Managing systems with Puppet apply][schedule] covers scheduling runs, and [Connecting standalone nodes to OpenVoxDB][openvoxdb apply] covers central reports and inventory, which need a client certificate on every node. Two things those pages leave out: + +* **Node identity.** Under Puppet apply, nothing verifies a node's identity. `$trusted['certname']` is whatever the node's `certname` setting says, and `$trusted['extensions']` is always empty, even on a node that still has its agent certificate, so classification by a certificate extension such as `pp_role` finds nothing. + Classify from Hiera by certname, from an external fact, or with an [external node classifier][enc]. +* **Central control.** No server means no central place to trigger a run. [OpenBolt][openbolt] can run Puppet apply on every node over SSH or WinRM, from a workstation or a CI job. It can also [compile each node's catalog itself and apply it][openbolt apply], so the nodes need no copy of the control repository. + +If the nodes were agents before, stop and disable the agent service so it stops trying to reach the old server: + +```console +sudo /opt/puppetlabs/bin/puppet resource service puppet \ + ensure=stopped enable=false +``` + +## Keep the plug-in cache in sync + +Puppet apply loads module plug-ins directly from the modulepath, but it doesn't fill the plug-in cache that commands such as `facter -p` read (see [Plug-ins under Puppet apply][apply plugins]). The [Vox Pupuli control repository's site.pp][controlrepo site.pp] opens with a resource that fills the cache as part of the catalog: + +```puppet +# hack pluginsync as file resource. only required for `puppet apply` usage +# this works by accident with puppet agent, but only on the puppetserver +# it breaks puppet agent on other systems, so we need to guard it +if $trusted['authenticated'] == 'local' { + file { $settings::libdir: + ensure => directory, + source => 'puppet:///plugins', # lint:ignore:puppet_url_without_modules + recurse => true, + purge => true, + backup => false, + noop => false, + tag => 'hacked_pluginsync', + } +} +``` + +It copies every module's plug-ins into the directory that pluginsync maintains on agent-managed nodes. It has no effect on the run that applies it. + +* **The guard** is true only for catalogs compiled locally by Puppet apply (see [trusted facts][]). On agent-managed nodes the agent manages this directory itself and an unguarded copy of the resource conflicts with it, so never deploy it unguarded to a mixed fleet. +* **The tag** lets a bootstrap script apply just this resource with `--tags`, as in [Bootstrap the first node in two phases](#bootstrap-the-first-node-in-two-phases). +* **External facts** have a parallel mount and cache directory. To make them visible to cache readers too, add a second file resource inside the same guard, with `$settings::pluginfactdest` as the title and `puppet:///pluginfacts` as the source. diff --git a/docs/_openvox_9x/plugins_in_modules.markdown b/docs/_openvox_9x/plugins_in_modules.markdown index 531e7091fe..8303d8f2a1 100644 --- a/docs/_openvox_9x/plugins_in_modules.markdown +++ b/docs/_openvox_9x/plugins_in_modules.markdown @@ -49,6 +49,14 @@ Translations | `/locales` | `locales` | `/locales` (`` is OpenVox agent's [cache directory][vardir], which is located at `/var/opt/puppetlabs/puppet/cache`, `%PROGRAMDATA%\PuppetLabs\puppet\cache`, or `~/.puppetlabs/opt/puppet/cache`.) +### Plug-ins under Puppet apply + +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. +Even with the modules deployed in the default environment, `facter -p` reads only the cache. To fill the cache on standalone nodes, see [Keep the plug-in cache in sync](services_apply_standalone.html#keep-the-plug-in-cache-in-sync). + ## Types of plug-ins OpenVox supports several kinds of plug-ins: diff --git a/docs/_openvox_9x/services_apply.markdown b/docs/_openvox_9x/services_apply.markdown index 65085bf1c4..b303f2c37e 100644 --- a/docs/_openvox_9x/services_apply.markdown +++ b/docs/_openvox_9x/services_apply.markdown @@ -21,7 +21,7 @@ title: "Puppet's services: Puppet apply" Puppet apply is an application that compiles and manages configurations on nodes. It acts like a self-contained combination of the OpenVox Server and OpenVox agent applications. For more info about Puppet's architecture, see [Overview of Puppet's Architecture](./architecture.html) --- in particular, read the note at the end about [differences and trade-offs between agent/master and puppet apply.](architecture.html#differences-between-agent-server-and-stand-alone) -For details about invoking the Puppet apply command, see [the puppet apply man page][man]. +For details about invoking the Puppet apply command, see [the puppet apply man page][man]. For running whole nodes with Puppet apply instead of an agent, see [Standalone workflows with Puppet apply](services_apply_standalone.html). ## Supported platforms diff --git a/docs/_openvox_9x/services_apply_standalone.markdown b/docs/_openvox_9x/services_apply_standalone.markdown new file mode 100644 index 0000000000..90748e095a --- /dev/null +++ b/docs/_openvox_9x/services_apply_standalone.markdown @@ -0,0 +1,125 @@ +--- +layout: default +title: "Standalone workflows with Puppet apply" +--- + +[apply]: services_apply.html +[apply plugins]: plugins_in_modules.html#plug-ins-under-puppet-apply +[architecture]: architecture.html#the-stand-alone-architecture +[tradeoffs]: architecture.html#differences-between-agent-server-and-stand-alone +[trusted facts]: lang_facts_and_builtin_vars.html#trusted-facts +[install]: install_pre.html +[template]: https://github.com/OpenVoxProject/control-repo-template +[controlrepo site.pp]: https://github.com/voxpupuli/controlrepo/blob/production/manifests/site.pp +[controlrepo readme]: https://github.com/voxpupuli/controlrepo#hetzner-cloud-cloud-init-userdata +[r10k]: https://github.com/puppetlabs/r10k +[schedule]: services_apply.html#managing-systems-with-puppet-apply +[enc]: nodes_external.html +[openvoxdb apply]: /openvoxdb/latest/connect_puppet_apply.html +[openbolt]: /openbolt/latest/running_bolt_commands.html +[openbolt apply]: /openbolt/latest/applying_manifest_blocks.html + +In a [standalone deployment][architecture] (often called "masterless"), each node compiles and applies its own catalog with [Puppet apply][apply] instead of requesting one from a server. That fits four situations: + +* **Bootstrapping the first node.** The node that will become your OpenVox Server can't get its configuration from a server that doesn't exist yet. +* **Disposable test environments.** Lab VMs, containers, and CI jobs can apply a control repository checkout with no server or certificate setup. +* **Single-node setups.** A node that only manages itself doesn't need a server. +* **Fleets that don't justify a server.** Every node holds a copy of the control repository and applies it on a schedule. + +For Puppet apply's general behavior (logging, reporting, scheduling), see [the Puppet apply service page][apply]. For the trade-offs against agent-server, see the [architecture overview][tradeoffs]. + +## Apply a control repository standalone + +[Install the openvox-agent package][install] on the node and clone your control repository onto it. These steps assume the layout of the [OpenVox control repository template][template], which applies standalone as shipped, and use paths relative to the checkout. + +1. Install the Puppetfile modules into `modules/` with [r10k][]: + + ```console + sudo /opt/puppetlabs/puppet/bin/gem install --no-document r10k + cd /path/to/control-repo + /opt/puppetlabs/puppet/bin/r10k puppetfile install --verbose + ``` + +2. Apply the main manifest: + + ```console + sudo /opt/puppetlabs/bin/puppet apply manifests/site.pp \ + --hiera_config hiera.yaml \ + --modulepath site-modules:modules \ + --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. + +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. + +## 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: + +1. From the initial checkout, apply only the tagged bootstrap resources: + + ```console + sudo /opt/puppetlabs/bin/puppet apply \ + /root/control-repo/manifests/site.pp \ + --modulepath /root/control-repo/modules:/root/control-repo/site \ + --hiera_config /root/control-repo/hiera.yaml \ + --tags r10k,hacked_pluginsync + ``` + + This configures r10k and fills the [plug-in cache](#keep-the-plug-in-cache-in-sync). `--tags` limits which resources are *applied*, not what is compiled, so the checkout still needs its Puppetfile modules installed and its Hiera data reachable. + +2. Deploy the real environment with the r10k configuration from phase 1, then apply from it: + + ```console + sudo /opt/puppetlabs/puppet/bin/r10k deploy environment \ + --modules --verbose + sudo /opt/puppetlabs/bin/puppet apply \ + /etc/puppetlabs/code/environments/production/manifests/site.pp + ``` + +Once the node's role includes the OpenVox Server profile, later runs can switch to `puppet agent -t` against the new server. + +## Run a fleet without a server + +Running every node standalone means replacing what the server did centrally. The [architecture overview][tradeoffs] covers the trade-offs, [Managing systems with Puppet apply][schedule] covers scheduling runs, and [Connecting standalone nodes to OpenVoxDB][openvoxdb apply] covers central reports and inventory, which need a client certificate on every node. Two things those pages leave out: + +* **Node identity.** Under Puppet apply, nothing verifies a node's identity. `$trusted['certname']` is whatever the node's `certname` setting says, and `$trusted['extensions']` is always empty, even on a node that still has its agent certificate, so classification by a certificate extension such as `pp_role` finds nothing. + Classify from Hiera by certname, from an external fact, or with an [external node classifier][enc]. +* **Central control.** No server means no central place to trigger a run. [OpenBolt][openbolt] can run Puppet apply on every node over SSH or WinRM, from a workstation or a CI job. It can also [compile each node's catalog itself and apply it][openbolt apply], so the nodes need no copy of the control repository. + +If the nodes were agents before, stop and disable the agent service so it stops trying to reach the old server: + +```console +sudo /opt/puppetlabs/bin/puppet resource service puppet \ + ensure=stopped enable=false +``` + +## Keep the plug-in cache in sync + +Puppet apply loads module plug-ins directly from the modulepath, but it doesn't fill the plug-in cache that commands such as `facter -p` read (see [Plug-ins under Puppet apply][apply plugins]). The [Vox Pupuli control repository's site.pp][controlrepo site.pp] opens with a resource that fills the cache as part of the catalog: + +```puppet +# hack pluginsync as file resource. only required for `puppet apply` usage +# this works by accident with puppet agent, but only on the puppetserver +# it breaks puppet agent on other systems, so we need to guard it +if $trusted['authenticated'] == 'local' { + file { $settings::libdir: + ensure => directory, + source => 'puppet:///plugins', # lint:ignore:puppet_url_without_modules + recurse => true, + purge => true, + backup => false, + noop => false, + tag => 'hacked_pluginsync', + } +} +``` + +It copies every module's plug-ins into the directory that pluginsync maintains on agent-managed nodes. It has no effect on the run that applies it. + +* **The guard** is true only for catalogs compiled locally by Puppet apply (see [trusted facts][]). On agent-managed nodes the agent manages this directory itself and an unguarded copy of the resource conflicts with it, so never deploy it unguarded to a mixed fleet. +* **The tag** lets a bootstrap script apply just this resource with `--tags`, as in [Bootstrap the first node in two phases](#bootstrap-the-first-node-in-two-phases). +* **External facts** have a parallel mount and cache directory. To make them visible to cache readers too, add a second file resource inside the same guard, with `$settings::pluginfactdest` as the title and `puppet:///pluginfacts` as the source.