lib/dispatchcloud/readme.go

   1 // Copyright (C) The Arvados Authors. All rights reserved.
   2 //
   3 // SPDX-License-Identifier: AGPL-3.0
   4
   5 package dispatchcloud
   6
   7 // A dispatcher comprises a container queue, a scheduler, a worker
   8 // pool, a remote command executor, and a cloud driver.
   9 // 1. Choose a provider.
  10 // 2. Start a worker pool.
  11 // 3. Start a container queue.
  12 // 4. Run the scheduler's stale-lock fixer.
  13 // 5. Run the scheduler's mapper.
  14 // 6. Run the scheduler's syncer.
  15 // 7. Wait for updates to the container queue or worker pool.
  16 // 8. Repeat from 5.
  17 //
  18 //
  19 // A cloud driver creates new cloud VM instances and gets the latest
  20 // list of instances. The returned instances are caches/proxies for
  21 // the provider's metadata and control interfaces (get IP address,
  22 // update tags, shutdown).
  23 //
  24 //
  25 // A worker pool tracks workers' instance types and readiness states
  26 // (available to do work now, booting, suffering a temporary network
  27 // outage, shutting down). It loads internal state from the cloud
  28 // provider's list of instances at startup, and syncs periodically
  29 // after that.
  30 //
  31 //
  32 // An executor maintains a multiplexed SSH connection to a cloud
  33 // instance, retrying/reconnecting as needed, so the worker pool can
  34 // execute commands. It asks the cloud driver's instance to verify its
  35 // SSH public key once when first connecting, and again later if the
  36 // key changes.
  37 //
  38 //
  39 // A container queue tracks the known state (according to
  40 // arvados-controller) of each container of interest -- i.e., queued,
  41 // or locked/running using our own dispatch token. It also proxies the
  42 // dispatcher's lock/unlock/cancel requests to the controller. It
  43 // handles concurrent refresh and update operations without exposing
  44 // out-of-order updates to its callers. (It drops any new information
  45 // that might have originated before its own most recent
  46 // lock/unlock/cancel operation.)
  47 //
  48 //
  49 // The scheduler's stale-lock fixer waits for any already-locked
  50 // containers (i.e., locked by a prior dispatcher process) to appear
  51 // on workers as the worker pool recovers its state. It
  52 // unlocks/requeues any that still remain when all workers are
  53 // recovered or shutdown, or its timer expires.
  54 //
  55 //
  56 // The scheduler's mapper chooses which containers to assign to which
  57 // idle workers, and decides what to do when there are not enough idle
  58 // workers (including shutting down some idle nodes).
  59 //
  60 //
  61 // The scheduler's syncer updates state to Cancelled when a running
  62 // container process dies without finalizing its entry in the
  63 // controller database. It also calls the worker pool to kill
  64 // containers that have priority=0 while locked or running.
  65 //
  66 //
  67 // An instance set proxy wraps a driver's instance set with
  68 // rate-limiting logic. After the wrapped instance set receives a
  69 // cloud.RateLimitError, the proxy starts returning errors to callers
  70 // immediately without calling through to the wrapped instance set.