github.com/kaisenlinux/docker.io@v0.0.0-20230510090727-ea55db55fac7/swarmkit/design/nomenclature.md (about)

     1  # Nomenclature
     2  
     3  To keep track of the software components in swarm, this document defines
     4  various aspects of the swarm system as referenced in _this_ code base.
     5  
     6  Several of these definitions may be a part of the product, while others are
     7  simply for communicating about backend components. Where this distinction is
     8  important, it will be called out.
     9  
    10  ## Overview
    11  
    12  There are several moving parts in a swarm cluster. This section attempts to
    13  define the high-level aspects that can provide context to the specifics.
    14  
    15  To begin, we'll define the concept of a _cluster_.
    16  
    17  ### Cluster
    18  
    19  A _cluster_ is made up of an organized set of Docker _Engines_ configured in a
    20  manner to allow the dispatch of _services_.
    21  
    22  ### Node
    23  
    24  A _Node_ refers to an active member in a cluster. Nodes can execute work and / or
    25  act as a cluster _manager_.
    26  
    27  ### Manager
    28  
    29  A _manager_ accepts _services_ defined by users through the cluster API. When a
    30  valid _service_ is provided, the manager will generate tasks, allocate resources
    31  and dispatch _tasks_ to an available _node_.
    32  
    33  _Managers_ operate in a coordinated group, organized via the Raft protocol.
    34  When a quorum is available, a leader will be elected to handle all API requests
    35  and all other members of the quorum will proxy to the leader.
    36  
    37  #### Orchestrator
    38  
    39  The _Orchestrator_ ensures that services have the appropriate set of tasks
    40  running in the _cluster_ according to the _service_ configuration and polices.
    41  
    42  #### Allocator
    43  
    44  The _allocator_ dispenses resources, such as volumes and networks to tasks, as required.
    45  
    46  #### Scheduler
    47  
    48  The _scheduler_ assigns _tasks_ to available nodes.
    49  
    50  #### Dispatcher
    51  
    52  The _dispatcher_ directly handles all _agent_ connections. This includes
    53  registration, session management, and notification of task assignment.
    54  
    55  ### Worker
    56  
    57  A _worker_ is a complete _Engine_ joined to a _cluster_. It receives and executes
    58  _tasks_ while reporting on their status.
    59  
    60  A worker's _agent_ coordinates the receipt of task assignments and ensures status
    61  is correctly reported to the _dispatcher_.
    62  
    63  #### Engine
    64  
    65  The _Engine_ is shorthand for the _Docker Engine_. It runs containers
    66  distributed via the _scheduler_ -> _dispatcher_ -> _agent_ pipeline.
    67  
    68  #### Agent
    69  
    70  The _agent_ coordinates the dispatch of work for a _worker_. The _agent_
    71  maintains a connection to the _dispatcher_, waiting for the current set of
    72  tasks assigned to the node. Assigned tasks are then dispatched to the Engine.
    73  The agent notifies the _dispatcher_ of the current state of assigned tasks.
    74  
    75  This is roughly analogous to a real life talent agent who ensures the worker
    76  has the correct set of _tasks_ and lets others know what the worker is doing.
    77  
    78  While we refer to a cluster Engine as a "worker", the term _agent_ encompasses
    79  only the component of a worker that communicates with the dispatcher.
    80  
    81  ## Objects
    82  
    83  An _object_ is any configuration component accessed at the top-level. These
    84  typically include a set of APIs to inspect the objects and manipulate them
    85  through a _spec_. 
    86  
    87  _Objects_ are typically broken up into a _spec_ component and a set of fields
    88  to keep track of the implementation of the _spec_. The _spec_ represents the
    89  users intent. When a user wants to modify an object, only the spec portion is
    90  provided. When an object flows through the system, the spec portion is left
    91  untouched by all cluster components.
    92  
    93  Examples of _objects_ include `Service`, `Task`, `Network` and `Volume`.
    94  
    95  ### Service
    96  
    97  The _service_ instructs the cluster on what needs to be run. It is the central
    98  structure of the cluster system and the primary root of user interaction. The
    99  service informs the orchestrator about how to create and manage tasks.
   100  
   101  A _service_ is configured and updated with the `ServiceSpec`. The
   102  central structure of the spec is a `RuntimeSpec`. This contains definitions on
   103  how to run a container, including attachments to volumes and networks.
   104  
   105  ### Task
   106  
   107  A _task_ represents a unit of work assigned to a node. A _task_ carries a runtime
   108  definition that describes how to run the container.
   109  
   110  As a task flows through the system, its state is updated accordingly. The state
   111  of a task only increases monotonically, meaning that once the task has failed,
   112  it must be recreated to retry.
   113  
   114  The assignment of a _task_ to a node is immutable. Once a the task is bound to a
   115  node, it can only run on that node or fail.
   116  
   117  ### Volume
   118  ### Network
   119