puppet.run

Runs the Puppet agent on the node. The request returns immediately, and progress is streamed until the run completes. While the run is in progress, its output is written to /var/log/puppetlabs/current_execution.log; once the run completes, the file is renamed to /var/log/puppetlabs/last_execution.log. Only the most recent run is kept.

A run is carried out by a process separate from the RVC server, so stopping, restarting, or upgrading the RVC server while a run is in progress does not interrupt it. The run completes normally and its output is still saved to last_execution.log.

If Puppet is disabled on the node, the run is refused rather than started. The response names the reason the agent was disabled and the user who disabled it, the CLI exits with code 1, and the times of the last and next runs are left unchanged. Use force to run anyway, which enables Puppet, runs it, and disables it again afterward with the original user and reason. To check the current state first, see puppet.status.

Only one run can be pending or in progress on a node at a time. While a run is waiting to start or running, another request is refused with Puppet busy running since <time> ago. and the CLI exits with code 1.

In RVC 3.13.0, the CLI exits with code 0 when a run completes, including when Puppet applied changes. The Puppet exit code is reported in the last line of the output, for example Puppet applied changes (exit code 2). In earlier versions, the CLI exits with the Puppet exit code, so a run that applied changes exits with code 2.

JSON-RPC Request

{"jsonrpc":"2.0","id":1,"method":"puppet.run","params":{"environment":"<environment>","server":"<puppet_server>","ca_server":"<ca_server>","notify_uri":"<notify_uri>","noop":"<boolean>","force":"<boolean>","random_wait":"<seconds>","cluster":"<cluster_role>","skip_hooks":"<boolean>"}}

Request Parameters

Cluster orchestration

Without cluster, or with cluster set to none, Puppet runs on the local node only, including on a node that is part of a cluster.

On a cluster, primary runs Puppet on the primary node first and then on the secondary node, and secondary runs it on the secondary node first and then on the primary node. The run can be started from either node. When it is started from the node that runs second, that node waits until the first node finishes.

• Pre-flight check: If Puppet is disabled on the other node, RVC warns before the first run starts that the other node will not run.
• Success: If the first run succeeds (Puppet exit code 0, or 2 when changes were applied), the run on the second node starts automatically.
• Failure: If the first run fails (exit code greater than 2), the run on the second node is skipped so that a failed configuration is not applied to both nodes.
• Busy or unreachable node: If the other node is already running Puppet or cannot be reached, the orchestration stops with a message rather than waiting.

Post-run hooks

After a Puppet run finishes, RVC runs any post-run hook scripts that are installed on the node and reports the result of each. Hooks run after both successful and failed runs, but not after a run stopped with puppet.stop. A failing hook does not change the exit code of the Puppet run. The hook results are streamed with the run output and added to last_execution.log, followed by a summary line. To run the hooks on demand without a Puppet run, see puppet.hooks.

JSON-RPC Response

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": "<result_message>"
}

RVC CLI Example

rvc puppet run

Response

↻ Executing method 'puppet.run' as external process with PID 28860 ...
Running puppet...
Info: Using environment 'production'
Info: Retrieving pluginfacts
Info: Retrieving plugin
Info: Loading facts
Notice: Requesting catalog from puppet:8140
Notice: Applied catalog in 18.89 seconds
Running post-run hook: 10-hello.sh...
Hook 10-hello.sh succeeded.
hook ok

Running post-run hook: 20-fail.sh...
Hook 20-fail.sh failed (exit code 1).
about to fail

Post-run hooks: 1 passed, 1 failed (20-fail.sh)
Puppet run took less than a minute. Puppet applied changes (exit code 2). Output saved to /var/log/puppetlabs/last_execution.log.

Output when Puppet is disabled on the node:

Puppet agent is currently disabled and will not run until it is manually enabled. Reason: <text_describing_reason>. Disabled by: test.user.

Output with --force when Puppet is disabled on the node:

Enabling puppet...
Running puppet...
Info: Using environment 'production'
...
Notice: Applied catalog in 176.07 seconds
Disabling puppet...
Puppet run took 4 minutes. Puppet applied changes (exit code 2). Output saved to /var/log/puppetlabs/last_execution.log.

Output with --random-wait, where the run waits a random time before it starts:

↻ Executing method 'puppet.run' as external process with PID 28860 ...
Waiting 85 seconds before running puppet...
Running puppet...
...

Output when a run is already pending or in progress:

Puppet busy running since less than 5 seconds ago.