command_execution_once

Execute a command only once on a node.

⚙️ Compatible targets: Linux

Parameters

NameDocumentation
commandCommand to run.

This parameter is required.
ok_codesList of codes that produce a repaired status separated with commas (ex: 1,2,5). Defaults to 0.

This parameter is optional.
untilTry to execute the command until a particular state: 'ok', 'any' (defaults to 'any').

Choices:
  • any
  • ok

This parameter is optional.
unique_idTo identify the action without losing track if the command changes. Defaults to the command if you don't need it.

This parameter is optional.

Outcome conditions

You need to replace ${command} with its actual canonified value.

  • ✅ Ok: command_execution_once_${command}_ok
    • ☑️ Already compliant: command_execution_once_${command}_kept
    • 🟨 Repaired: command_execution_once_${command}_repaired
  • ❌ Error: command_execution_once_${command}_error

Example

method: command_execution_once
params:
  ok_codes: OPTIONAL_VALUE
  command: VALUE
  until: any
  unique_id: OPTIONAL_VALUE

Documentation

This method is useful for specific commands that should only be executed once per node.

If you can spot a condition for the command execution by testing the state of its target, it is better to use the condition_from_command method to test the state coupled with the command_execution_result method to run the command if necessary.

In case of reinstallation or factory-reset of the Rudder agent, this method will no longer detect if a command has already been executed.

The method will:

Define the command_execution_once_${command}_kept condition and do nothing if a command_execution_once has already been executed on this machine with the same Unique id.

Execute the command if it is the first occurrence and:

  • If the parameter Until is *any*, it will consider the command as executed on the machine and define either:
    • command_execution_once_${command}_repaired if the return code is in ok_codes,
    • command_execution_once_${command}_error otherwise.
  • If the parameter Until is ok and:
    • If the return code is in the Ok codes list, define the command_execution_once_${command}_repaired condition
    • If the return code is not in Ok codes it define the command_execution_once_${command}_error condition and retry at next agent run.

If an exit code is not in the list it will lead to an error status. If you want "0" to be a success you have to list it in the Ok codes list

Example:

If you use:

    command_execution_once("command -a -t", "0", "ok", "my_program_setup")

It will retry to run command -a -t until it returns "0". Then it will not execute it again.