Struct ClusterWorker 

pub struct ClusterWorker {
    pub host: String,
    pub ranks: Vec<usize>,
    pub local_devices: LocalDevices,
    pub nccl_socket_ifname: String,
    pub path: String,
    pub ssh: Option<SshConfig>,
    pub tunnel: bool,
    pub arch: Option<String>,
    pub data_path: Option<String>,
    pub docker: Option<String>,
    pub env: BTreeMap<String, String>,
}

One worker (a physical host running one or more NCCL ranks).

Fields

host: String

Hostname / identifier (was name: in the pre-Refactor-2 schema). Used for /etc/hosts resolution, --add-host injection, and as the default SSH target (override via ssh:). On the worker itself, this is the value hostname returns (or the FLODL_HOST_NAME-overridden value).

ranks: Vec<usize>

Global ranks owned by this worker.

NOT part of the user YAML schema — populated internally by ClusterConfig::populate_ranks from probed device counts (called by prepare_cluster_env before envelope emission). Sequential assignment by worker order: worker 0 owns [0..counts[0]), worker 1 owns [counts[0]..counts[0]+counts[1]), etc.

Serialized into the wire format so the rank-side library reads the post-probe assignment via FullCluster::from_value, and deserializable so the canonical JSON round-trips. A ranks: key in USER yaml is rejected loudly at load (loading::reject_user_ranks): a user writing it expects it to pin ranks, and it never did (probe is authoritative).

local_devices: LocalDevices

CUDA device indices paired by position with ranks, or "all" shorthand for auto-detect at startup. See LocalDevices for semantics.

nccl_socket_ifname: String

Network interface NCCL binds to (e.g. virbr0, enp1s0). Becomes NCCL_SOCKET_IFNAME in the spawned process environment.

path: String

Project checkout path on this host. fdl-cli cd’s here before invoking the remote command. Heterogeneous mounts are fine (e.g. /opt/flodl on the controller, /srv/flodl in a VM); training data is the user’s responsibility to mount identically across hosts (NAS / SMB / virtiofs / S3-FUSE).

ssh: Option<SshConfig>

SSH endpoint for fdl-cli’s launcher. None means the host runs on the same machine as the launcher (fork/exec, no ssh). When Some, all fields inside are optional and fall back to system ssh defaults (or ~/.ssh/config rules) when unset.

In YAML, the sub-block accepts:

ssh:
  target: node-b.lan          # ssh hostname/IP, default: host
  port: 2222                  # -p <port>
  user: ubuntu                # -l <user>
  identity_file: ~/.ssh/key   # -i <path>
  options:                    # -o <opt> (repeatable)
    - ProxyJump=bastion
    - StrictHostKeyChecking=no

tunnel: bool

Route this worker’s training traffic through its fan-out SSH session instead of a direct TCP connection to the controller: the launcher adds a remote forward to the host’s relay SSH session and points the host at 127.0.0.1:<controller.port>. Requires a CPU ElChe mode (NCCL’s peer-to-peer data plane cannot ride a controller tunnel) and a remote host — validated loudly at launch. When EVERY remote worker is tunneled, the controller binds loopback only. Consumed by the library’s launcher; fdl-cli just carries it through the envelope.

arch: Option<String>

libtorch variant subpath under <path>/libtorch/ on this host. E.g. precompiled/cu128 for a Blackwell host on PT 2.10 cu128, builds/sm61-sm120 for a Pascal host on a from-source build. Convention: the convention path <host.path>/libtorch/<arch> is what the rank exec reads at runtime; the controller-side build mirrors it via <cluster.controller.path or controller-host.path>/libtorch/<arch>. Both paths point at the same physical libtorch via the shared project-root mount.

Optional; when unset, fdl-cli falls back to the host’s project-root .active file (single-host default behaviour for non-cluster runs).

fdl probe’s GPU compat check derives the supported sm architectures by parsing the basename of this value (e.g. builds/sm61-sm120 → 6.1 12.0) AND/OR reading the variant’s .arch metadata file at <path>/libtorch/<arch>/.arch. The former wins when the basename encodes archs; the latter covers precompiled/cuXXX where the basename names the CUDA version, not GPU archs.

data_path: Option<String>

Shared-storage path visible to this host. flodl assumes a shared filesystem (NAS / SMB / virtiofs / S3-FUSE / SSHFS) reachable at the same logical path on every node — training data, model checkpoints, and per-rank logs all live here. When absent, the convention default DEFAULT_DATA_PATH applies. fdl probe verifies the path exists + is readable on each host before training can fan out.

docker: Option<String>

Names the docker compose service that provides this host’s runtime environment (e.g. cuda, dev). It does NOT wrap the training exec: cluster fan-out runs each rank’s binary directly on the host over SSH (the pre-flight build is what runs in a container, in the controller’s ClusterController docker). This field is a probe-time signal only: when set, fdl probe skips host-level NCCL discovery — NCCL ships inside the image, not on the host — and reports “provided via Docker image <svc>” instead of erroring on a missing libnccl.so. The host’s libtorch (resolved via the <path>/libtorch/<arch> convention) is still validated because it’s the bind-mount target, not container state. Per-host (not global) because mixed deployments are common: controller in Docker, worker bare-metal (or vice-versa). Library ignores this field; consumed only by fdl-cli’s probe / deploy paths.

env: BTreeMap<String, String>

Host-scoped env vars exported into every rank child spawned on this host. Mapping NAME: VALUE (string→string). Useful for host-specific tuning that doesn’t belong at cluster scope (e.g. one host needs a different NCCL_SOCKET_IFNAME override, or a custom LD_LIBRARY_PATH due to a non-standard CUDA install). Overrides matching keys from ClusterConfig::env.

Implementations

impl ClusterWorker

pub fn effective_data_path(&self) -> &str

Effective shared-data path: data_path if set, else DEFAULT_DATA_PATH.

Trait Implementations

impl Clone for ClusterWorker

fn clone(&self) -> ClusterWorker

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ClusterWorker

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ClusterWorker

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ClusterWorker

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.