puppet-apply

Apply a manifest

$ puppet apply [path/to/manifest]

$ puppet apply --execute [code]

$ puppet apply --modulepath [path/to/directory] --hiera_config [path/to/file] [path/to/manifest]

puppet apply [options] <manifest file(s)>
puppet apply [options] -e <manifest string>

<manifest file(s)>
    Specifies one or more Puppet manifest files (.pp) to be applied. These files contain the declarative Puppet code that defines the desired system state.

-e <manifest string>
    Allows applying a Puppet manifest directly from a string provided on the command line, suitable for quick tests or simple configurations.

--modulepath <path>
    Sets the search path for Puppet modules. This can be a single path or a colon-separated list of directories.

--environment <name>
    Defines the Puppet environment to use for the run (e.g., 'production', 'development'), influencing which manifests, modules, and data are loaded.

--noop
    Performs a 'no-operation' run, simulating the changes that would be made without actually altering the system. Essential for testing and validating manifests safely.

--test
    A convenience option that combines --noop, --debug, and --verbose, providing detailed output for debugging purposes without making actual changes.

--debug
    Enables highly verbose debug logging, displaying detailed information about Puppet's internal processes for in-depth troubleshooting.

--verbose
    Increases the verbosity of output, providing more information about the resources being processed during the run.

--logdest <destination>
    Routes log messages to a specified destination, such as 'syslog', 'console', or a file path (e.g., 'file:/var/log/puppet.log').

--report
    Generates a report of the Puppet run, which is typically stored locally in Puppet's report directory and can be used for auditing.

--show_diff
    Displays the differences between the current state and the desired state of files and other resources when changes are applied.

--detailed-exitcodes
    Modifies the exit code of the command to provide more specific information about the outcome of the run (e.g., changes made, failures).

--trace
    Prints a stack trace when errors occur, invaluable for pinpointing issues within Puppet code or the Puppet environment.

The puppet apply command is a fundamental component of the Puppet configuration management suite, enabling users to compile and apply Puppet manifests directly on the local system. In contrast to the standard master/agent architecture, where a central Puppet master distributes configurations, puppet apply operates in a standalone mode. This makes it exceptionally useful for several key scenarios:

Testing and Development: Developers can quickly test Puppet code changes and observe their effects without a full master infrastructure.
Small-Scale Deployments: Ideal for configuring single machines or small clusters where the overhead of a dedicated Puppet master is unnecessary.
Ad-hoc Configuration: Useful for applying specific configurations or performing one-off system adjustments.

It processes Puppet code (from a file or a string), compiles it into a resource catalog, and then enforces the desired state on the local machine. This command leverages the same core compilation and application logic as the Puppet agent, ensuring consistent and idempotent resource management.

While powerful, puppet apply has certain limitations:

No Centralized Reporting or Orchestration: It lacks the centralized reporting, external node classification integration, and orchestration capabilities provided by a Puppet master.
Manual or External Scheduling: Requires manual invocation or external scheduling mechanisms (like cron or systemd timers) for periodic application, unlike the continuously running Puppet agent.
Privilege Requirements: Typically demands root or administrator privileges to enact system-level changes, similar to other configuration management tools.
Scalability: Less suitable for large-scale infrastructure management where a robust master-agent architecture offers better scalability, reporting, and management features.

Like all Puppet operations, puppet apply is inherently idempotent. This means that executing the same manifest multiple times will only cause changes if the system's current state deviates from the desired state defined in the manifest. If the system is already in the correct state, puppet apply will make no modifications, ensuring system consistency and preventing unintended side effects from repeated runs.

When the --detailed-exitcodes option is used, puppet apply provides more specific exit codes to indicate the run's outcome:
0: The run completed successfully with no changes or failures.
1: The run failed due to an error.
2: The run completed successfully, and some resources were changed.
4: The run completed, but some resources failed to be applied.
6: The run completed, with some resources changed and some resources failed.

Puppet was initially released in 2005, and puppet apply has been a foundational command from its inception. It served as a critical tool for developers to test and iterate on Puppet code rapidly without the necessity of a full server setup. This standalone mode was instrumental in the early adoption and growth of the Puppet ecosystem, enabling quick prototyping, local development, and the management of small, independent systems. Even as the master-agent architecture became the standard for larger environments, puppet apply has maintained its importance for testing, debugging, and specific standalone deployments.

puppet(8), puppet-agent(8), puppet-master(8), puppet-module(8), puppet-resource(8), cron(8)