Version Management and Compatibility

This chapter describes how Curvine components version themselves and how to operate a cluster whose components may run different versions. Since 0.4.x every binary emits structured version metadata, servers advertise a compatibility contract, and the master evaluates peers with a lenient diagnose-by-default policy.

Version SchemaCopy Anchor Link

All Curvine components use the same version schema:

<major>.<minor>.<patch>[-<pre-release>][+<build>]

Examples: 0.4.0, 0.4.0-alpha, 0.5.0-rc.1+build.1234

Pre-release versions sort before the corresponding release version, following SemVer precedence: 0.4.0-alpha < 0.4.0-beta < 0.4.0.

Protocol VersionCopy Anchor Link

The protocol version is a monotonic integer that governs wire-level compatibility between components. It is not the same as the release version.

A component accepts a peer whose protocol version falls within [min_protocol_version, protocol_version] of the server.

Viewing Component VersionsCopy Anchor Link

Every binary prints its structured version as JSON with --version-json:

cv --version-json
curvine-master --version-json
curvine-worker --version-json
curvine-fuse --version-json

Example output:

{
  "component": "worker",
  "release_version": "0.4.0-alpha",
  "git_commit": "24c848719b5b4fea74519d91cbe462bb49761b36",
  "git_tag": "v0.4.0-alpha",
  "git_branch": "main",
  "protocol_version": 1,
  "min_protocol_version": 1,
  "capabilities": ["transfer", "batch-write"]
}

The fields are:

• component — component name (master, worker, client, fuse, cli, csi).
• release_version — Cargo/package version of the build.
• git_commit / git_tag / git_branch — exact source provenance.
• protocol_version / min_protocol_version — wire protocol bounds.
• capabilities — feature-level negotiation tokens.

Worker Version StatisticsCopy Anchor Link

The CLI can summarize the release-version distribution across all live workers. This is the fastest way to see whether a cluster is running a homogeneous set of versions or a mix of old and new workers:

cv node --versions

Example output:

Version Distribution:
----------------------------------------
  0.4.0-alpha              : 3 worker(s)
  0.4.0-beta               : 5 worker(s)
  legacy (0.3.0-test)      : 1 worker(s)
----------------------------------------
  total                    : 9 worker(s)

Workers that report structured component_info count under their release_version; older workers that only report the legacy software_version string are counted as legacy (<version>). Workers with no usable version data at all are grouped under legacy (no version).

Compatibility Between ComponentsCopy Anchor Link

The master evaluates every worker heartbeat and client handshake against its own compatibility contract. The default behavior is lenient: without explicit configuration the master records a warning and allows the request, so old components are never rejected just because they predate the structured version protocol.

Master ↔ WorkerCopy Anchor Link

Master ↔ Client (including FUSE / CLI / CSI)Copy Anchor Link

Worker ↔ Client (data plane)Copy Anchor Link

Enforcement PolicyCopy Anchor Link

The compatibility policy is configured in the master configuration file:

[master.compatibility]
# "diagnose" (default): warn on incompatibility, allow the request.
# "enforce": reject incompatible requests with an explicit error.
mode = "diagnose"

# Minimum worker release version (empty = not enforced).
min_worker_version = "0.2.0"

# Minimum client release version (empty = not enforced).
min_client_version = "0.1.5"

# Release versions explicitly rejected regardless of mode (emergency backstop).
blocked_versions = ["0.2.5"]

• mode = "diagnose" (default): incompatible peers are allowed, and the master logs a warning describing the peer, its version, and the expected bound. This is the safe default and never breaks an existing mixed-version cluster.
• mode = "enforce": incompatible peers are rejected with an explicit error that includes the actual peer version and the upgrade suggestion.
• blocked_versions: release versions listed here are always rejected regardless of the mode. This is an emergency backstop for known-bad builds (see the known-incompatible list on the release notes page).

CapabilitiesCopy Anchor Link

Beyond versions, features are negotiated through capability tokens that each component advertises in its ComponentVersion. A feature is enabled only when both peers declare it, so a capability introduced in a newer release is silently disabled until the whole data path upgrades.

ObservabilityCopy Anchor Link

The master exposes compatibility metrics on the Prometheus endpoint (http://<master>:9001/metrics). See the Monitoring Metrics page for the full metric table.

verdict takes one of: compatible, missing_info, blocked, protocol_mismatch, version_too_old, version_unknown.

Release Notes and Known IncompatibilitiesCopy Anchor Link

Each release ships release notes that repeat the compatibility table for that specific version. The known-incompatible list and the release notes template are maintained in the release notes page; keep the compatibility table there in sync whenever a version is added to blocked_versions or a new protocol version is introduced.