open-nomad/contributing/mock-driver.md

Mock Driver

This repo includes a mock task driver in the drivers/mock package that implements a minimal task driver interface for development work. This driver is loaded as the other built-in drivers are, but only when Nomad is not compiled with the release tag.

Task Configuration

task "mocktask" {
  driver = "mock_driver"

  config {
    run_for      = "10s"
    exit_code    = 7
    exit_err_msg = "the application crashed"
  }
}

The mock_driver driver supports the following configuration in the job spec:

• run_for (duration: "0s") - The duration for which the fake task runs for. After this period the driver responds indicating the task has terminated.
• signal_error (string: "") - The error message the task returns if signalled.
• stderr_repeat_duration (duration: "0s") - The duration between repeated stderr outputs.
• stderr_repeat (number: 0) - The number of times the stderr_string will be written.
• stderr_string (string: "") - The string that the task writes to stderr.
• stdout_repeat_duration (string: "") - The duration between repeated stdout outputs.
• stdout_repeat (number: 0) - The number of times the stdout_string will be written.
• stdout_string (string: "") - The string that the task writes to stdout.

The driver has configurable startup and shutdown for the tasks:

• exit_code (number: 0) - The exit code the driver should return for the exiting task.
• exit_err_msg (string: "") - The error message the task returns while exiting.
• exit_signal (number: 0) - The signal with which the driver indicates the task has been killed.
• kill_after (duration: "0s") - Duration after which the driver indicates the task has exited with SIGINT.
• plugin_exit_after (string: "") - Duration after which the driver indicates the plugin exited via the WaitTask call.
• start_block_for (duration: "0s") - Duration to block before returning when started.
• start_error_recoverable (bool: false) - Marks whether the error returned when starting the driver is recoverable.
• start_error (string: "") - The error that is returned when starting the driver.

The driver can present information to the client about the task as though it had networking:

• driver_advertise (bool: false) - Returned as DriverNetwork.AutoAdvertise from Start()
• driver_ip (string: "") - The address returned as the DriverNetwork.IP from Start()
• driver_port_map (string: "") - Parse a label:number pair and return it as DriverNetwork.PortMap from Start().

Plugin Options

plugin "mock_driver" {
  fs_isolation               = "none"
  shutdown_periodic_after    = false
  shutdown_periodic_duration = 0
}

• fs_isolation (string: "none") - The type of file system isolation to report to the client. Must be one of "none", "chroot", or "image".
• shutdown_periodic_after (bool: false) - A toggle that can be used during tests to "stop" a previously-functioning driver, allowing for testing of periodic drivers and fingerprinters.
• shutdown_periodic_duration (number: 0) - The duration after which to stop a previously-functioning driver, in seconds.

Example

An example job that could be used for testing task kill_timeout:

job "mock" {

  group "group" {

    task "task" {

      driver = "mock_driver"

      kill_timeout = "5s"

      config {
        exit_code = 0
        exit_err_msg = "error on exit"
        exit_signal = 9
        kill_after = "3s"
        run_for = "30s"
        signal_error = "got signal"
        start_block_for = "1s"
        stdout_repeat = 1
        stdout_repeat_duration = "10s"
        stdout_string = "hello, world!\n"
      }

      resources {
        cpu    = 128
        memory = 128
      }

    }
  }
}

This results in the following allocation events:

Recent Events:
Time                       Type        Description
2023-03-20T16:22:39-04:00  Restarting  Task restarting in 17.426443129s
2023-03-20T16:22:39-04:00  Terminated  Exit Code: 0, Signal: 9, Exit Message: "error on exit"
2023-03-20T16:22:09-04:00  Started     Task started by client
2023-03-20T16:22:07-04:00  Task Setup  Building Task Directory
2023-03-20T16:22:07-04:00  Received    Task received by client