meshctl CLI & Orchestration ============================== `meshctl` is the declarative fleet management and orchestration CLI for Fleetmesh. Written in Rust, it provides operators with a fast, dependency-light controller to manage, inspect, reconcile, and deploy Fleetmesh nodes and peer topologies. .. image:: ../_static/logo-fleetmesh.svg :align: center :alt: Fleetmesh Logo :width: 240px \ Overview & Capabilities ----------------------- While ``meshnode`` is the persistent runtime daemon that maintains peer connections, cryptographic stores, and message routing, ``meshctl`` acts as the administrative control plane. It consumes Kubernetes-style declarative manifests (``apiVersion: fleetmesh.org/v1alpha1``) and communicates directly with local or remote node instances: - **Non-Destructive Hot-Reconciliation** (``meshctl apply``): Applies declarative changes to peerings, ingress/egress rules, budgets, and trust policies dynamically against a running daemon via Unix domain socket without dropping active QUIC connections or interrupting sessions. - **Manifest Diffing** (``meshctl diff``): Computes terminal diffs highlighting exact property divergences between desired manifest declarations and live daemon state. - **Multi-Target Deployment Compiler** (``meshctl export``): Translates declarative fleet manifests into production-ready infrastructure templates: - Kubernetes (``--target=k8s``): Deployments, Services, ConfigMaps. - Podman Quadlet (``--target=quadlet``): Rootless container systemd units. - Hardened systemd (``--target=systemd``): Sandboxed ``.service`` and ``.timer`` units. - Docker Compose (``--target=compose``): Multi-node local clusters. - **Fleet Observation & Monitoring** (``meshctl watch``): Provides a single-pane status display across an entire fleet over SSH, tracking protocol digest consistency, relay connectivity, compartment faults, and CI status. - **Independent Rust Conformance Engine** (``meshctl conform``): A clean-room implementation of the Fleetmesh store and reconciliation mechanisms written solely from the specification and test vectors, providing independent protocol verification. - **Linked Data Projections** (``meshctl linked``): Extracts and inspects the node's schema.org JSON-LD metadata for services, standing reports, and Blossom blobs. Architecture & Design --------------------- `meshctl` is built with a minimalist, high-reliability design philosophy: .. list-table:: :widths: 25 75 :header-rows: 1 * - Aspect - Architecture Decision * - **Language & Toolchain** - Rust 2021 (MSRV 1.84). Compiled as a statically linked, standalone binary. * - **Transport & Control** - Unix domain socket IPC using the ``meshnode-control/1`` protocol. Zero exposed network admin ports. * - **Network Dependencies** - Uses ``tungstenite`` and ``rustls`` with webpki-roots for relay querying. No heavy async runtime (zero Tokio overhead), keeping binary size minimal. * - **Security Sandbox** - Rootless execution by default. Can administer remote nodes entirely over secure SSH transport without special remote daemon agents. Installation ------------ Build and install from the workspace repository: .. code-block:: sh cd meshctl cargo install --path . Or verify the build directly: .. code-block:: sh cargo run -- version Quick Start ----------- .. code-block:: sh # Check status of local node daemon meshctl status --dir /var/lib/fleetmesh # Dry-run reconciliation of a peering manifest meshctl apply -f manifests/peering.yaml --dry-run # Apply live hot-reconciliation meshctl apply -f manifests/peering.yaml # Export manifest to Podman Quadlet systemd container meshctl export -f manifests/meshnode.yaml --target quadlet > ~/.config/containers/systemd/node.container # Inspect JSON-LD schema.org service descriptor meshctl linked service --dir /var/lib/fleetmesh | jq . Subsystems & Documentation -------------------------- .. list-table:: :widths: 25 75 :header-rows: 1 * - Document - Description * - :doc:`cli` - Complete reference for commands, flags, subcommands, and exit codes. * - :doc:`reconciliation` - Non-destructive hot-reconciliation mechanism, Unix domain socket control protocol, and zero-drop updates. * - :doc:`deployment` - Multi-target deployment compiler for Kubernetes, Podman Quadlet, systemd, and Docker Compose. * - :doc:`watching` - Fleet observation over SSH, systemd timer integration, and protocol digest drift detection. * - :doc:`conform` - Clean-room Rust conformance engine, wire protocol specification, and test vector coverage.