Skip to content
canikoPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

324 Commits

Folders and files

Repository files navigation

fleetix

CI Nix docs crates.io artifacts

Fleet topology library — typed Pkl schema, Rust bindings, and Nix modules.

fleetix provides generic tooling for fleet-wide host, link, domain, and service topology. A consuming flake owns the real topology data and generated sidecars; Fleetix provides the Pkl schema shape, Rust bindings, export CLI, and Nix modules that expose a generated topology to NixOS and Home Manager.

For paired full-stack dev/prod deployments and exact-output promotion, see service surfaces. The opt-in NixOS modules and fleetix-surfaces CLI keep each surface's data and credentials separate.

Layout

  • Cargo.toml — Cargo workspace containing the Fleetix and sidecar products.
  • src/ — Rust crate (fleetix) with topology types, accessors, and a CLI.
  • crates/fleetix-sidecar/ — standalone Pkl-to-Nix library and Rust executable.
  • examples/Topology.pkl — self-contained synthetic topology example.
  • lib/topology/ — generic Pkl schema material; no production fleet data.
  • modules/nixos.nix and modules/home-manager.nix — consumer modules.

Nix Helpers

For shared MCP server declarations and client configuration, see MCP adapters: fleetix.lib.mcp, fleetix.homeModules.mcp, and the fleetix mcp managed-entry reconciler.

The separate, opt-in mcp-server Cargo feature provides a composable Rust MCP server. fleetix mcp-serve PATH serves a selected topology snapshot over stdio; downstream applications can register typed handlers with their own authorization. See MCP server for the API and trust boundary.

fleetix.lib exposes pure helper functions for downstream flakes that need to derive runtime data from a generated topology sidecar:

  • hosts.resolveHostAddress resolves a host through an explicit ordered address policy such as [ "lan" "direct-link" "wg-home" ].
  • hosts.vpnProfile resolves a host-local VPN profile by host and profile name.
  • services.resolveEndpoint deterministically resolves a local endpoint or its declared LAN remoteVia endpoint for an ingress host.
  • services.resolveProxyEndpoints resolves a proxy action's endpoint followed by its ordered fallbackEndpoints the same way, for upstream failover. Validation requires every fallback to be a reachable HTTP endpoint sharing the primary's transport and tlsServerName, without repeats.
  • services.endpointsForHost, services.serviceHosts, and services.managedDnsCnameIntents derive host, HTTP-site, and DNS views. Like vpn, lan sites (served by a lan-scope ingress group) are private: they never get managed CNAMEs or public probes, and validation rejects dnsPublication = "managed" for them; consumers publish explicit records.
  • domains.publicationAddressIntents renders explicit static destinations and directly published apexes as A/AAAA ownership intents.
  • adapters.infernix.mkFleetNodes converts fleet host topology plus consumer-owned node overlays into Infernix node definitions.

Adapters stay intentionally thin: Fleetix provides network and service derivation, while consumers such as Infernix keep workload semantics, model inventory, scheduling policy, and application-specific defaults.

Host rebuild.buildCache is backend-neutral fleet policy. It records whether a host should use a fleet build cache for selected package attributes, while the consuming flake chooses the concrete cache implementation.

Cloud management and publication (0.4)

Host.management keeps installed-system SSH facts separate from LAN and public service DNS. Its optional publicAddress is a literal unicast recovery IP, sshPort overrides the caller's fleet default, and link selects a declared host binding. Explicit routes require an enrolled hostPubkey; installer keys and bootstrap ports remain installer-owned. Topology::management_routes returns a shared-link candidate followed by independent public recovery. The caller supplies source/target names and its default port, then probes candidates and integrates them into its own routing policy.

Domains.publicationTargets maps names to PublicationTarget values containing hostname, targetHost, ipv4, and optional ipv6. These are desired, non-secret facts promoted into topology, never live provider state. An HTTP site selects a destination through optional publicationTarget; selection requires managed DNS-only public access and that host in the site's ingress group. Its CNAME targets the destination hostname; an apex or destination-hostname site gets address records instead. A null selector preserves legacy zone-apex CNAME synthesis, and Pages destinations stay independent.

Validation rejects unknown destinations/hosts, duplicate destination names, invalid addresses, and competing DDNS, Pages or explicit/excluded A/AAAA/CNAME ownership. IPv4-only publication still owns absent AAAA, so reconciliation can remove stale IPv6. Consumers must validate topology before rendering or applying DNS. The Nix helper exposes address intents; consumers render absent IPv6 by omitting AAAA while retaining management of that record type.

These contracts require Fleetix 0.4 or later. Verify registry publication before adding production callers. Existing serialized topology remains compatible; Rust struct literals for Host, Domains, and HttpSite need the new fields (or their available defaults) when adopting that release.

Primary GPU compute

An optional gpu.render = new S.GpuRender { renderNode = "/dev/dri/by-path/pci-0000:03:00.0-render" } declares a default game/3D device. This is independent of the video-decoding gpu.media route and the compute request below. Use a stable PCI alias rather than a probe-order renderD128 name. Runtime consumers must verify accessibility, PCI identity and driver support; topology is desired configuration, not proof that an application rendered on that device.

lib/topology/GpuContract.pkl exports the schema's stable-node pattern, vendor and backend vocabulary, and shared conformance fixtures. Regenerate its Rust/Nix consumer with pkl eval --format json lib/topology/GpuContract.pkl -o lib/generated/gpu-contract.json. Fleetix tests check producer drift and compare official Pkl constraint enforcement with Rust parsing. Official pkl must be on PATH for those tests; the Nix Cargo checks supply it.

fleetix.lib.gpu.routes projects a host GPU record to independent rendering, media and compute defaults; fleetix.lib.gpu.forHost also retains inventory and legacy aliases. Absent routes stay disabled. Consumers translate these roles to their own framework controls and perform live device validation.

Rust applications can reuse fleetix::gpu::pci_selector with default-features = false, which excludes the Pkl evaluator and Tokio. Enable the pkl feature for loading/exporting Pkl and trust-source patching, and health for live probes. The default CLI enables both features.

Hosts may declare gpu.compute = new S.GpuCompute { backend = "oneapi" }. The optional request targets the dGPU when present, otherwise the iGPU. Validation requires oneapi on Intel, rocm on AMD, or cuda on NVIDIA. Omitting compute preserves existing consumer policy. This is a requested stack, not proof of runtime device availability; package selection and hardware verification belong to the consuming application/configuration.

Pkl Helpers

Rust consumers can add fleetix = { version = "0.6", default-features = false, features = ["pkl"] } to their Cargo dependencies and call fleetix::pkl_to_nix::write_with_cache_sync or its async counterpart. The library evaluates Pkl through the published pklx crate; a Fleetix Nix flake input is not needed to run the Rust generator. The Fleetix flake remains available for NixOS/Home Manager modules and Nix helper functions.

Enable mcp for the harness adapter APIs, or cli for the standalone executable. Simit generates verification and crates.io publication workflows: simit init ci --platform github --runtime nix --workspace --publish-crates. Release tags are signed package versions; member publishing is generated by Simit. The workspace policy is recorded in simit.toml. Regenerate its workflows with the command above and verify with simit init ci --workspace --check --diff. Generate these workflows with Simit 0.20.0. The aggregate verification workflow is .github/workflows/ci.yaml; .github/workflows/nix-builds.yaml retains revision/tree-bound evidence for the production packages and Nix checks. The signed-tag .github/workflows/publish-workspace.yaml builds credential-free archives for both members at the same version. The independent .github/workflows/trusted-publish-workspace.yaml admits those archives and publishes fleetix-sidecar before Fleetix, with exact registry resolution between them.

Before enrolling publication, configure SIMIT_PUBLISHER_REVISION to an independently qualified immutable Simit revision and place CRATES_IO_API_TOKEN only in the simit-crates-io environment restricted to protected trunk. Repository and organization credentials must not be exposed to the tag-controlled workflow. Retry the original signed-tag run for release recovery. Canix consumers need Fleetix 0.6.1 or later for Train::dispatch_where; verify publication before upgrading their Cargo dependency. The CI environment retains the repository's Nix module checks; Rust consumers still resolve and build the published library entirely through Cargo. See product boundaries for the deployment extraction contract. See shared native construction for the optional build-train library, standalone request lifecycle and builder-local NixOS service.

fleetix::pkl exposes generic Rust helpers for downstream crates that keep their canonical config in Pkl:

  • load(path).await evaluates a Pkl file and deserializes it into any serde model.
  • load_sync(path) provides the same behavior for synchronous command-line code.
  • string_literal(value) renders strings safely for generated Pkl files.

Generate Nix files directly with the standalone Rust CLI. From this workspace:

cargo install fleetix-sidecar --path crates/fleetix-sidecar --locked
fleetix-sidecar generate examples/Topology.pkl topology.nix
fleetix-sidecar check examples/Topology.pkl topology.nix
# Existing Fleetix command remains compatible:
fleetix pkl-to-nix examples/Topology.pkl topology.nix

The sidecar crate owns the evaluator, renderer, dependency cache and atomic writer. It has no Fleetix topology, Canix, Nix or external Pkl executable dependency. Its standalone check compares exact bytes without writing output or cache and exits 2 for drift. Consumers may compare evaluated Nix values to allow formatting changes, as Canix does.

fleetix::pkl_to_nix re-exports this library, preserving existing callers such as canix config generate, canix config check, and canix config render. Direct library-only consumers can depend on fleetix-sidecar with default features disabled after verifying publication. Publish the sidecar prerequisite before a Fleetix release that depends on it. Nix packages/apps remain available for installation and qualification, but generation does not evaluate a flake.

fleetix::pkl_to_nix::{render, write, write_sync} provides the same generator to Rust consumers. Writes preserve unchanged files and reuse a private, dependency-checked cache under $XDG_CACHE_HOME/fleetix/pkl-to-nix (or ~/.cache/fleetix/pkl-to-nix). Imported files and the modular topology's flattened sources invalidate the cache by content. Evaluations that read environment or remote resources are never cached. Pass --no-cache to force reevaluation, for example in a reproducibility check.

Topology-specific consumers should keep using export-nix when they need Fleetix's normalized topology rendering.

Validation and module integration

Validate a topology before consuming it. Human diagnostics are the default; automation can request a stable JSON report containing severity, code, path, value, and message for every issue:

fleetix validate examples/Topology.pkl --format json

The NixOS module is disabled when fleetix.source = null (the default). Set fleetix.source to a generated Nix sidecar to populate fleetix.topology:

{ config, ... }:
{
  imports = [ fleetix.nixosModules.topology ];
  fleetix.source = ./lib/generated/topology.nix;
}

The Home Manager module has one integration mode: when imported by Home Manager with an osConfig, it mirrors osConfig.fleetix.topology; when used standalone it remains an empty, opt-in surface. Fleetix does not own a consumer's machine data or deployment policy.

The declared Rust MSRV is 1.88, required by the resolved pklr dependency. CI also checks the pinned current stable Rust 1.96.1 toolchain so the minimum compatibility promise and modern compiler behavior are tested separately.

Boot operations

nixosModules.boot-operations runs one-shot host maintenance during boot, while no user session or user service holds the affected state: renaming a tree that live processes reference by path, retiring a compatibility symlink, rewriting state a user service keeps open. Each operation is a oneshot unit ordered before systemd-user-sessions.service and guarded by ConditionPathExists=/run/nologin, which systemd creates only at boot. A live switch therefore leaves a newly declared operation pending until the next reboot instead of running it under active sessions.

{ pkgs, ... }:
{
  imports = [ fleetix.nixosModules.boot-operations ];
  fleetix.bootOperations.rename-data = {
    user = "alice";
    commands = [ [ "${pkgs.coreutils}/bin/mv" "-T" "/srv/old" "/srv/new" ] ];
    requiresMountsFor = [ "/srv" ];
  };
}

An operation runs once per definition: success records a marker under /var/lib/fleetix/boot-operations/ keyed by a hash of its user, commands, environment and path, so changing any of them schedules it again (once = false runs it on every boot). A failure leaves no marker and is retried on the next boot; it never delays logins beyond timeoutSeconds. Inspect an operation with systemctl status fleetix-boot-op-<name>.

Supply facts

fleetix::supply merges producer facts (fleetix.supply-facts.v1), such as Simit's usage facts and an operator's enrollment overlay, into one graph. It reports which usages no upgrade path covers, and why. See Supply facts.

fleetix supply gaps --facts facts.json --topology Topology.pkl --by repo
fleetix supply path rev:github.com/example/tool@<sha> --reverse --facts facts.json
fleetix supply graph --facts facts.json --facts overlay.json
fleetix supply budget --facts facts.json --facts overlay.json --topology Topology.pkl

License

Dual-licensed under MIT or Apache-2.0, at your option.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages