docs(runtime): one instance identity for every shared-state feature

[spiceemma]

spiceai/spiceai#15135 gives every feature that coordinates through shared state one instance identity: SPICE_INSTANCE_ID, else HOSTNAME, else COMPUTERNAME, else the operating system's host name, with an empty variable treated as unset. Schedulers now register under the identity instead of host:port, executors use it as their executor ID, and a shared identity logs one error message across the scheduler, executor, and snapshot writer lease. Before this change, the docs described the identity only for PostgreSQL replication slots (without the host-name fallback) and snapshot leases (as a warning), and did not mention that two schedulers or executors on one host need distinct identities.

Pages changed

• website/docs/reference/spicepod/runtime.md: new "Instance identity" section under runtime.state with the resolution order, the features that use it, and the duplicate-identity error.
• website/docs/features/distributed-query/index.md: new "Instance Identity" section: per-node SPICE_INSTANCE_ID for several nodes on one host, executor restart handling, and the previous host:port behavior.
• website/docs/features/data-acceleration/snapshots.md: identity order and the shared-identity error (now an error, not a warning).
• website/docs/features/cdc/postgres-replication.md: host-name fallback, a note on slots left behind when the identity changes, and an upgrade warning for instances with no identity variable or an empty SPICE_INSTANCE_ID.

Versioned docs

vNext only. git tag --contains 64fb958982990a5be4cb824fe5b371b84d98f5a8 returns no tags, so neither v2.4.0-rc.1 nor v2.4.0-rc.2 includes the change. The upgrade notes name v2.4.0-rc.2 and earlier because rc testers and v2.3.x users moving to the next release see the new slot name and scheduler/executor identities. Versioned 2.3.x text is correct for its release and is unchanged.

Verification

Trunk SHA 9a25991b0384c7fc6b25fc838d6d71ce6f65ea57.

• Reproduced: the environment variable name: pub const SPICE_INSTANCE_ID: &str = "SPICE_INSTANCE_ID"; (crates/util/src/instance_id.rs:27)
• Reproduced: resolution order: const IDENTITY_VARIABLES: [&str; 3] = [SPICE_INSTANCE_ID, "HOSTNAME", "COMPUTERNAME"]; (crates/util/src/instance_id.rs:30), host-name fallback || gethostname::gethostname().to_string_lossy().into_owned(), (crates/util/src/instance_id.rs:35)
• Unverified, code inspection only: an empty variable counts as unset: .find_map(|name| env(name).filter(|value| !value.is_empty())) (crates/util/src/instance_id.rs:53)
• Reproduced: duplicate-identity message text: "Another running instance uses {SPICE_INSTANCE_ID} '{instance_id}' at state location '{location}'. Give each instance its own {SPICE_INSTANCE_ID} (for example the pod name)." (crates/util/src/instance_id.rs:62)
• Unverified, code inspection only: scheduler registers under the identity: let scheduler_id = datafusion.cluster_config.instance_id().to_string(); (crates/runtime/src/cluster/scheduler_registry.rs:187); previously "{advertise_host}:{}", (v2.4.0-rc.2 crates/runtime/src/cluster/scheduler_registry.rs:168)
• Unverified, code inspection only: executor ID is the identity: let executor_id = rt.df.cluster_config.instance_id().to_string(); (crates/runtime/src/cluster/mod.rs:1344); previously let executor_id = format!("{advertise_host}:{advertise_port}"); (v2.4.0-rc.2 crates/runtime/src/cluster/mod.rs:1322)
• Reproduced: executor restart log line: "Executor '{executor_id}' restarted, so the tasks and shuffle output of its earlier run are rescheduled" (crates/runtime/src/cluster/service.rs:647)
• Unverified, code inspection only: snapshot writer lease uses the shared identity: LazyLock::new(|| util::instance_id::instance_id().into()); (crates/runtime-acceleration/src/snapshot/writer_lease.rs:83), logged with tracing::error!( (crates/runtime-acceleration/src/snapshot/writer_lease.rs:639)
• Unverified, code inspection only: rate-control lease names pair identity and a per-process ID: format!("{instance_id}/{}", uuid::Uuid::new_v4()) (crates/data-http-rate-control/src/lib.rs:2041)
• Reproduced: previous slot fallback when no variable was set: .unwrap_or_else(|| "unknown".to_string()) (v2.4.0-rc.2 crates/data_components/src/postgres_replication/config.rs:487)
• Observed, not isolated: old slot suffixes _3f484bfe (no variable) and _38d394c2 (empty SPICE_INSTANCE_ID), and unchanged slot names when a variable is set, from the source PR's unit tests slot_name_without_identity_variables_comes_from_the_host_name, slot_name_with_an_empty_spice_instance_id_uses_the_next_source, and slot_names_from_identity_variables_are_unchanged: feat: one instance identity for every shared-state feature spiceai#15135
• Observed, not isolated: a second scheduler process under one running identity is refused and reported, and a restart after a crash is not reported, from the source PR's tests a_second_running_process_under_one_identity_is_a_duplicate and a_restart_after_a_crash_is_not_a_duplicate: feat: one instance identity for every shared-state feature spiceai#15135
• Unverified, code inspection only: the scheduler logs the duplicate error for a second executor process under a running executor's ID, and reschedules a restarted executor's earlier work instead of waiting for it to be reaped (crates/runtime/src/cluster/service.rs).
• Unverified, code inspection only: HTTP rate control has no duplicate-identity check.
• Unverified, code inspection only: each spiced process holds an exclusive lock on its instance directory (SPICE_CONFIG_DIR), claimed unconditionally at startup (bin/spiced/src/main.rs:202).
• Reproduced: previous identity used a set-but-empty variable: std::env::var("SPICE_INSTANCE_ID"), with no empty-value filter before .ok() on the next line (v2.4.0-rc.2 crates/data_components/src/postgres_replication/config.rs:484)
• build: npm run build in website/ passed locally ([SUCCESS] Generated static files in "build"., exit 0; no broken links or anchors reported)

[github-actions]

✅ Pull with Spice Passed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected
• ✅ Has at least one assignee: spiceemma

[github-actions]

🔍 Pull with Spice Failed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected

Failed checks:

• ❌ At least one assignee is required for this pull request.

Please address these issues and update your pull request.

[github-actions]

🚀 deployed to https://9ecd6e3e.spiceai-org-website.pages.dev

[Copilot]

🟡 Changes recommended

The executor example needs startup corrections, and the upgrade warning misstates which identity configurations change replication slots.

2 open findings

• Empty instance IDs may change slot selection contrary to documented assurance · New
• Two-executor example lacks required addresses, isolation, and concurrency setup · New

What changed in this PR

Documents the shared runtime instance identity introduced by spiceai/spiceai#15135 in vNext documentation.

Changes:

• Defines identity resolution and duplicate-identity reporting.
• Explains cluster registration, executor restarts, and snapshot leases.
• Adds PostgreSQL replication-slot upgrade guidance.

File	Description
website/​docs/​reference/​spicepod/​runtime.md	Adds the shared identity reference.
website/​docs/​features/​distributed-query/​index.md	Documents node identities and same-host execution.
website/​docs/​features/​data-acceleration/​snapshots.md	Updates lease identity and error reporting.
website/​docs/​features/​cdc/​postgres-replication.md	Explains fallback changes and abandoned-slot cleanup.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approved

The documentation matches the referenced behavior, addresses prior feedback, and has no unresolved findings.

0 open findings

2 resolved since last review

• Two-executor example lacks required addresses, isolation, and concurrency setup
• Empty instance IDs may change slot selection contrary to documented assurance

🧠 Review effort: Balanced

[github-actions]

🚀 deployed to https://020704ad.spiceai-org-website.pages.dev