API endpoint: /v1/actions/execute-command

[Al2Klimov]

Is your feature request related to a problem? Please describe.

As a user I'd like to let a particular endpoint execute a particular check/notification/event-command in context of a particular checkable.

Also I'd like to see:

• the exit code / kill signal / execution error
• output

Describe the solution you'd like

• POST /v1/actions/execute-command
  • takes:
    • the same target checkables specification parameters as POST /v1/actions/schedule-downtime
    • a macro string endpoint
      • defaults to $command_endpoint$
      • must resolve to a valid endpoint name (!= "") on all target checkables
    • a string command_type
      • CheckCommand/EventCommand/NotificationCommand
      • defaults to EventCommand
    • a macro string command
      • depending on command_type defaults to either $check_command$ or $event_command$ or ""
      • must resolve to a valid command name (!= "") of command_type on all target checkables
    • a dictionary macros
      • defaults to {}
      • overrides resolved macros (including the ones in the other parameters), e.g. {"http_ssl": false}
    • (a macro string resolving to) a number ttl
    • a boolean (like pretty) wait
  • does (action-specific):
    1. Collects the target checkables like POST /v1/actions/schedule-downtime, but with the new permission objects/execute/<type>
    2. Resolves (and validates) all of the above macro strings
    3. Resolves the macros as if for letting a command endpoint execute a check command
    4. Generates one UUID per target checkable
    5. Computes an absolute deadline from the TTL
    6. Routes messages to the endpoints to run the commands on:
    • method: event::ExecuteCommand
    • params:
      • like the event::ExecuteCommand ones
      • a UUID string source – the UUID generated above
      • a timestamp number deadline – the deadline computed above
    7. If wait is true:
    • Waits for the command executions to finish
    • Returns a dictionary:
      • key: checkable name
      • value: dictionary – keys:
        • error: execution error if any
        • signal: termination signal if any
        • exit: exit code if any
        • output: output if could be started
        • start: start time (*nix timestamp) if could be started
        • end: end time (*nix timestamp) if could be started
    8. Otherwise: returns a dictionary with checkable name mapped to its UUID (202, not 200 OK)
• GET /v1/actions/execute-command
  • takes:
    • one or more UUID strings execution (AFAIK there are already some parameters in existing actions which may be specified multiple times, see there)
  • does (action-specific):
    1. Returns a sub-response per execution parameter (AFAIK there are already some existing actions which do that, see there):
    • If the execution doesn’t exist or is expired: 404
    • Else, if the execution finished: a dictionary as from POST /v1/actions/execute-command?wait=1 below the checkable name
    • Else: a dictionary {"pending": true}
• event::ExecuteCommand source handling
  • Executes the command as usual, but instead of converting the output to a check result, send it as a event::ExecutedCommand cluster message:
    • execution – the UUID
    • attributes as from POST /v1/actions/execute-command?wait=1 below the checkable name
  • Sends on rejection (accepts commands? hierarchy ok? etc.) also a such message with the reason as execution error
• event::ExecutedCommand handling
  • If not rejected (accepts commands? hierarchy ok? etc.), mark execution as finished

Describe alternatives you've considered

#7709

Additional context

@lippserd

[Al2Klimov]

@lippserd @N-o-X Please comment.

[lippserd]

Good idea to have this on the very same action and support more than one checkable.
How do we persist the results or pending actions across restarts?

[Al2Klimov]

• New internal state attribute Checkable#executions
  • dictionary
  • key: UUID
  • value: all event::ExecuteCommand params (from above) ex. UUID

[lippserd]

🟢

[Al2Klimov]

@lippserd Shall we restrict on which endpoint who may run commands in addition to ... ?

• ... nodes may or may not accept commands
• ... nodes don't accept commands from below
• ... executing at all is restricted by a permission

[lippserd]

We have a filter option for the other actions so it makes sense to support this here as well.
Do you have more ideas?

[Al2Klimov]

AFAIK we've already implicitly got a permission filter on target checkables. I've asked whether we also shall filter target endpoints.