Project: Docker Swarm (Orchestration & Management / Scheduling & Orchestration)
File: nomenclature.md

To keep track of the software components in swarm, this document defines various aspects of the swarm system as referenced in this code base. Several of these definitions may be a part of the product, while others are simply for communicating about backend components. Where this distinction is important, it will be called out. There are several moving parts in a swarm cluster. This section attempts to define the high-level aspects that can provide context to the specifics. To begin, we'll define the concept of a cluster. A cluster is made up of an organized set of Docker Engines configured in a manner to allow the dispatch of services. A Node refers to an active member in a cluster. Nodes can execute work and / or act as a cluster manager. A manager accepts services defined by users through the cluster API. When a valid service is provided, the manager will generate tasks, allocate resources and dispatch tasks to an available node. Managers operate in a coordinated group, organized via the Raft protocol. When a quorum is available, a leader will be elected to handle all API requests and all other members of the quorum will proxy to the leader. The Orchestrator ensures that services have the appropriate set of tasks running in the cluster according to the service configuration and polices. The allocator dispenses resources, such as volumes and networks to tasks, as required. The scheduler assigns tasks to available nodes. The dispatcher directly handles all agent connections. This includes registration, session management, and notification of task assignment. A worker is a complete Engine joined to a cluster. It receives and executes tasks while reporting on their status. A worker's agent coordinates the receipt of task assignments and ensures status is correctly reported to the dispatcher. The Engine is shorthand for the Docker Engine. It runs containers distributed via the scheduler -> dispatcher -> agent pipeline. The agent coordinates the dispatch of work for a

The agent maintains a connection to the dispatcher, waiting for the current set of tasks assigned to the node. Assigned tasks are then dispatched to the Engine. The agent notifies the dispatcher of the current state of assigned tasks. This is roughly analogous to a real life talent agent who ensures the worker has the correct set of tasks and lets others know what the worker is doing. While we refer to a cluster Engine as a "worker", the term agent encompasses only the component of a worker that communicates with the dispatcher. An object is any configuration component accessed at the top-level. These typically include a set of APIs to inspect the objects and manipulate them through a spec. Objects are typically broken up into a spec component and a set of fields to keep track of the implementation of the spec. The spec represents the users intent. When a user wants to modify an object, only the spec portion is provided. When an object flows through the system, the spec portion is left untouched by all cluster components. Examples of objects include `Service`, `Task`, `Network` and `Volume`. The service instructs the cluster on what needs to be run. It is the central structure of the cluster system and the primary root of user interaction. The service informs the orchestrator about how to create and manage tasks. A service is configured and updated with the `ServiceSpec`. The central structure of the spec is a `RuntimeSpec`. This contains definitions on how to run a container, including attachments to volumes and networks. A task represents a unit of work assigned to a node. A task carries a runtime definition that describes how to run the container. As a task flows through the system, its state is updated accordingly. The state of a task only increases monotonically, meaning that once the task has failed, it must be recreated to retry. The assignment of a task to a node is immutable. Once a the task is bound to a node, it can only run on that node or fail.