github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/plugins/drivers/remote/index.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: 'Task Driver Plugins: Remote Task Drivers'
     4  description: >-
     5    Remote Task Drivers support cloud and other nonlocal task runtime
     6    environments.
     7  ---
     8  
     9  # Remote Task Drivers
    10  
    11  ~> **Note:** Remote Task Driver support is experimental and subject to backward
    12  incompatible changes between Nomad releases or deprecation. Please refer to the
    13  [Upgrade Guide][upgrade] to find breaking changes.
    14  
    15  ~> **Known Bugs:** When a Nomad node running a remote task driver goes down,
    16  another node must be available and able to run the replacement allocation in
    17  order to take advantage of remote task driver's ability to avoid restarting
    18  lost tasks. If a new node is not immediately available but started later,
    19  it will start a new instance of the remote task instead of reconnecting to the
    20  old one. Follow [#10592][gh-10592] for the fix.
    21  
    22  Nomad 1.1.0 introduces support for Remote Task Drivers. Remote Task Drivers
    23  allow custom task driver plugins to execute tasks using nonlocal runtimes such
    24  as cloud container runtimes. Without this support, task driver plugins trying
    25  to manage remote tasks would run into the following problems:
    26  
    27  1. When [draining][drain] a node, Nomad stops all allocations on that node
    28     before rescheduling them.
    29  
    30  2. When a node is `down`, Nomad reschedules all allocations onto other nodes.
    31  
    32  These 2 behaviors are optimal for traditional task drivers where the task
    33  process is colocated with the Nomad agent. If the Nomad node is down or
    34  drained, the allocations should be considered down or be drained as well.
    35  
    36  However these 2 behaviors do not apply to tasks executing on remote runtimes.
    37  If the Nomad node managing them goes down, a new Nomad node should be able to
    38  manage them without restarting the task. Likewise if the Nomad node managing
    39  the remote task is drained, a new Nomad node should manage the remote task
    40  without requiring it be stopped and restarted.
    41  
    42  The Remote Task Driver feature in Nomad 1.1.0 improves these behaviors for
    43  custom plugins that advertise the [`RemoteTasks` capability][remote-cap].
    44  
    45  ## Caveats
    46  
    47  Due to the exerpimental nature there are a number of standard Nomad features
    48  which Remote Task Drivers do not support by default.
    49  
    50  ### Resources
    51  
    52  ~> See [*Remote Task Drivers and Resources* #10549][gh-10549] on Github for
    53  details.  Comments, ideas, and use cases welcome!
    54  
    55  The [`resources`][resources] stanza has not been altered for remote task
    56  drivers. Since remote tasks do not consume local resources, remote task drivers
    57  should not use the existing `resources` stanza and instead implement their own
    58  resource parameters in their [`task.config`][task-config] block.
    59  
    60  Jobs using remote task drivers should use the minimum allowed resources in
    61  their [`task.resources`][resources] stanza:
    62  
    63  ```hcl
    64  resources {
    65    cpu    = 1
    66    memory = 10
    67  }
    68  ```
    69  
    70  ### Nomad Client Features
    71  
    72  Remote task drivers defer most Nomad client features to the driver plugin.
    73  
    74  Since the allocation directory is local to the Nomad node, unless a remote task
    75  driver is able to remotely mount or copy its contents, the following features
    76  will be unavailable:
    77  
    78  - [`artifact`][artifact] - artifacts are downloaded to the local Nomad
    79    allocation directory.
    80  - [`dispatch_payload`][dispatch-payload] - dispatch payloads are written to the
    81    local Nomad allocation directory.
    82  - [`ephemeral_disk`][ephemeral-disk] - ephemeral disks are local to the Nomad
    83    node and therefore not applicable to remote task drivers.
    84  - [`template`][template] - templates are rendered in the local Nomad allocation
    85    directory.
    86  - [`vault`][vault] - a secret token may be retrieved but the task driver may
    87    not place the token file in the expected location.
    88  - [`volume`][volume] - volume and volue mounts assumed tasks have access to the
    89    Nomad node's local disk are unlikely to work with remote task drivers.
    90  
    91  Furthermore since networking is completely handled by the remote runtime the
    92  behavior of the following features is completely driver dependent:
    93  
    94  - [`network`][network] - group networks are created on the local Nomad node,
    95    and task networks are up to the remote task driver to implement.
    96  - [`connect`][connect] - since group networks and sidecars are local to the
    97    Nomad node, Consul Connect sidecars will not work as expected.
    98  
    99  [artifact]:  /docs/job-specification/artifact
   100  [connect]: /docs/job-specification/connect
   101  [dispatch-payload]: /docs/job-specification/dispatch_payload
   102  [drain]: /docs/commands/node/drain
   103  [ephemeral-disk]: /docs/job-specification/ephemeral_disk
   104  [gh-10549]: https://github.com/hashicorp/nomad/issues/10549
   105  [gh-10592]: https://github.com/hashicorp/nomad/issues/10592
   106  [network]: /docs/job-specification/network
   107  [remote-cap]: /docs/concepts/plugins/task-drivers#capabilities-capabilities-error
   108  [resources]: /docs/job-specification/resources
   109  [task-config]: /docs/job-specification/task#config
   110  [template]: /docs/job-specification/template
   111  [upgrade]: /docs/upgrade/upgrade-specific
   112  [vault]: /docs/job-specification/vault
   113  [volume]: /docs/job-specification/volume