You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@datafusion.apache.org by mi...@apache.org on 2026/09/23 09:08:04 UTC

(datafusion-ballista) branch main updated: feat(scheduler): record scheduler id in job starts (#2462)

This is an automated email from the ASF dual-hosted git repository.

milenkovicm pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/datafusion-ballista.git


The following commit(s) were added to refs/heads/main by this push:
     new 97d611d07 feat(scheduler): record scheduler id in job starts (#2462)
97d611d07 is described below

commit 97d611d071317158578877f790eaa290bcffc30f
Author: Ville Brofeldt <33...@users.noreply.github.com>
AuthorDate: Wed Sep 23 02:08:00 2026 -0700

    feat(scheduler): record scheduler id in job starts (#2462)
    
    * feat(history): record scheduler id in job starts
    
    * feat(scheduler): add opaque scheduler id
    
    * test(scheduler): broaden scheduler state coverage
    
    * docs(history): document scheduler id logging
    
    * docs(scheduler): note scheduler id config change
    
    * docs(scheduler): clarify scheduler id semantics
    
    * test(scheduler): share instance id generation
    
    * refactor(scheduler): simplify instance id generation
    
    * refactor(proto): rename scheduler callback endpoint
    
    * refactor(scheduler): use endpoint naming
    
    * test(executor): broaden metadata assertions
    
    * fix(scheduler): update endpoint references
    
    * feat(executor): allow configured executor id
    
    * fix(scheduler): reject duplicate executor ids
    
    * fix(scheduler): reject duplicate pull executor ids
    
    * docs(scheduler): clarify identity uniqueness
    
    * retrigger CI
---
 ballista/core/proto/ballista.proto                 |   6 +-
 ballista/core/src/ids.rs                           |  16 +++
 ballista/core/src/serde/generated/ballista.rs      |   6 +-
 ballista/executor/src/config.rs                    |  35 +++++-
 ballista/executor/src/executor_process.rs          |  83 ++++++++++++-
 ballista/executor/src/executor_server.rs           |  54 +++++----
 ballista/executor/src/standalone.rs                |   4 +-
 ballista/history/src/event.rs                      |   3 +
 ballista/history/src/writer.rs                     |   3 +
 ballista/scheduler/src/api/handlers.rs             |  47 ++++++++
 ballista/scheduler/src/cluster/memory.rs           | 132 +++++++++++++++++----
 ballista/scheduler/src/cluster/mod.rs              |   2 +-
 ballista/scheduler/src/config.rs                   |  61 +++++++++-
 ballista/scheduler/src/history/mod.rs              |   6 +
 ballista/scheduler/src/scheduler_process.rs        |   2 +-
 .../scheduler/src/scheduler_server/event_log.rs    |   2 +
 ballista/scheduler/src/scheduler_server/grpc.rs    |  73 +++++++++---
 ballista/scheduler/src/scheduler_server/mod.rs     |  44 +++++--
 ballista/scheduler/src/state/aqe/mod.rs            |   7 +-
 ballista/scheduler/src/state/execution_graph.rs    |  10 +-
 ballista/scheduler/src/state/executor_manager.rs   |   4 +-
 ballista/scheduler/src/state/mod.rs                |  22 ++--
 ballista/scheduler/src/state/task_manager.rs       |  12 +-
 ballista/scheduler/src/test_utils.rs               |   4 +-
 docs/source/upgrading/55.0.0.md                    |  27 +++++
 docs/source/user-guide/configs.md                  |  15 +--
 docs/source/user-guide/history-server.md           |  14 +++
 docs/source/user-guide/scheduler.md                |  17 +++
 examples/examples/mtls-cluster.rs                  |   2 +-
 29 files changed, 593 insertions(+), 120 deletions(-)

diff --git a/ballista/core/proto/ballista.proto b/ballista/core/proto/ballista.proto
index f311e8b08..dc90b9228 100644
--- a/ballista/core/proto/ballista.proto
+++ b/ballista/core/proto/ballista.proto
@@ -1247,13 +1247,15 @@ message CleanJobDataResult {
 message LaunchTaskParams {
   // Allow to launch a task set to an executor at once
   repeated TaskDefinition tasks = 1;
-  string scheduler_id = 2;
+  // Scheduler callback endpoint in host:port format.
+  string scheduler_endpoint = 2;
 }
 
 message LaunchMultiTaskParams {
   // Allow to launch a task set to an executor at once
   repeated MultiTaskDefinition multi_tasks = 1;
-  string scheduler_id = 2;
+  // Scheduler callback endpoint in host:port format.
+  string scheduler_endpoint = 2;
 }
 
 message LaunchTaskResult {
diff --git a/ballista/core/src/ids.rs b/ballista/core/src/ids.rs
index c10d23b37..625a7979e 100644
--- a/ballista/core/src/ids.rs
+++ b/ballista/core/src/ids.rs
@@ -118,6 +118,15 @@ string_id! {
     JobId
 }
 
+/// Creates an opaque instance identifier for long-lived Ballista components.
+///
+/// Scheduler and executor identities use this UUID-backed format. Job ids use
+/// their own scheduler-local generator because they have different requirements
+/// around compactness and sortability.
+pub fn new_instance_id() -> String {
+    uuid::Uuid::new_v4().to_string()
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -132,4 +141,11 @@ mod tests {
         map.insert(JobId::new("job-123"), 7);
         assert_eq!(map.get("job-123"), Some(&7));
     }
+
+    #[test]
+    fn instance_ids_are_uuid_backed() {
+        let id = new_instance_id();
+
+        uuid::Uuid::parse_str(&id).unwrap();
+    }
 }
diff --git a/ballista/core/src/serde/generated/ballista.rs b/ballista/core/src/serde/generated/ballista.rs
index af5491b91..4b78b7f6c 100644
--- a/ballista/core/src/serde/generated/ballista.rs
+++ b/ballista/core/src/serde/generated/ballista.rs
@@ -1724,16 +1724,18 @@ pub struct LaunchTaskParams {
     /// Allow to launch a task set to an executor at once
     #[prost(message, repeated, tag = "1")]
     pub tasks: ::prost::alloc::vec::Vec<TaskDefinition>,
+    /// Scheduler callback endpoint in host:port format.
     #[prost(string, tag = "2")]
-    pub scheduler_id: ::prost::alloc::string::String,
+    pub scheduler_endpoint: ::prost::alloc::string::String,
 }
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct LaunchMultiTaskParams {
     /// Allow to launch a task set to an executor at once
     #[prost(message, repeated, tag = "1")]
     pub multi_tasks: ::prost::alloc::vec::Vec<MultiTaskDefinition>,
+    /// Scheduler callback endpoint in host:port format.
     #[prost(string, tag = "2")]
-    pub scheduler_id: ::prost::alloc::string::String,
+    pub scheduler_endpoint: ::prost::alloc::string::String,
 }
 #[derive(Clone, Copy, PartialEq, Eq, Hash, ::prost::Message)]
 pub struct LaunchTaskResult {
diff --git a/ballista/executor/src/config.rs b/ballista/executor/src/config.rs
index 9dbd4c78c..a812f487c 100644
--- a/ballista/executor/src/config.rs
+++ b/ballista/executor/src/config.rs
@@ -26,7 +26,7 @@
 // as mentioned in https://github.com/apache/datafusion-ballista/issues/1271
 //
 #![allow(clippy::uninlined_format_args, clippy::unused_unit)]
-use ballista_core::error::BallistaError;
+use ballista_core::{error::BallistaError, ids::new_instance_id};
 
 use crate::executor_process::ExecutorProcessConfig;
 use crate::metrics::ExecutorMetricCollectionPolicy;
@@ -80,6 +80,10 @@ pub struct Config {
         help = "Host name or IP address to register with scheduler so that other executors can connect to this executor. If none is provided, the scheduler will use the connecting IP address to communicate with the executor."
     )]
     pub external_host: Option<String>,
+    /// Identifier for this executor. If unset, a UUID-backed instance identity
+    /// is generated at startup.
+    #[arg(long = "id", help = "Identifier for this executor.")]
+    pub executor_id: Option<String>,
     /// Port for the Arrow Flight service (used for shuffle data transfer).
     #[arg(short = 'p', long, default_value_t = 50051, help = "bind port")]
     pub bind_port: u16,
@@ -250,7 +254,8 @@ impl TryFrom<Config> for ExecutorProcessConfig {
             }
             None => opt.vcores,
         };
-        Ok(ExecutorProcessConfig {
+        let config = ExecutorProcessConfig {
+            executor_id: opt.executor_id.unwrap_or_else(new_instance_id),
             special_mod_log_level: opt.log_level_setting,
             external_host: opt.external_host,
             bind_host: opt.bind_host,
@@ -285,12 +290,18 @@ impl TryFrom<Config> for ExecutorProcessConfig {
             override_create_grpc_client_endpoint: None,
             client_ttl: opt.client_ttl,
             health: crate::health::ExecutorHealth::new(),
-        })
+        };
+
+        config.validate()?;
+
+        Ok(config)
     }
 }
 
 #[cfg(test)]
 mod tests {
+    use crate::executor_process::ExecutorProcessConfig;
+
     use super::parse_memory_pool_fraction;
     use super::parse_memory_pool_size;
 
@@ -341,4 +352,22 @@ mod tests {
             opt.client_ttl
         );
     }
+
+    #[cfg(feature = "build-binary")]
+    #[test]
+    fn cli_executor_id_explicit_value_is_respected() {
+        use clap::Parser;
+        let opt = super::Config::parse_from(["ballista-executor", "--id", "executor-a"]);
+        let cfg = ExecutorProcessConfig::try_from(opt).unwrap();
+        assert_eq!(cfg.executor_id, "executor-a");
+    }
+
+    #[cfg(feature = "build-binary")]
+    #[test]
+    fn cli_executor_id_defaults_to_uuid_when_unset() {
+        use clap::Parser;
+        let opt = super::Config::parse_from(["ballista-executor"]);
+        let cfg = ExecutorProcessConfig::try_from(opt).unwrap();
+        uuid::Uuid::parse_str(&cfg.executor_id).unwrap();
+    }
 }
diff --git a/ballista/executor/src/executor_process.rs b/ballista/executor/src/executor_process.rs
index 32c80afc9..8d4c40f55 100644
--- a/ballista/executor/src/executor_process.rs
+++ b/ballista/executor/src/executor_process.rs
@@ -39,7 +39,6 @@ use tokio::signal;
 use tokio::sync::mpsc;
 use tokio::task::JoinHandle;
 use tokio::{fs, time};
-use uuid::Uuid;
 
 use datafusion::execution::memory_pool::{FairSpillPool, MemoryPool};
 use datafusion::execution::runtime_env::{RuntimeEnv, RuntimeEnvBuilder};
@@ -63,6 +62,7 @@ use ballista_core::utils::{
 };
 use ballista_core::{
     BALLISTA_PROTOCOL_VERSION, BALLISTA_VERSION, ConfigProducer, JobId, RuntimeProducer,
+    ids::new_instance_id,
 };
 
 use crate::client_pool::DefaultBallistaClientPool;
@@ -259,6 +259,8 @@ fn identity_pool_policy() -> MemoryPoolPolicy {
 /// network configuration, scheduler connection details, resource limits,
 /// and optional overrides for customizing executor behavior.
 pub struct ExecutorProcessConfig {
+    /// Identifier for this executor instance.
+    pub executor_id: String,
     /// Local IP address for binding executor services.
     pub bind_host: String,
     /// External hostname/IP advertised to other components for connectivity.
@@ -344,6 +346,17 @@ pub struct ExecutorProcessConfig {
 }
 
 impl ExecutorProcessConfig {
+    /// Validates executor process configuration.
+    pub fn validate(&self) -> ballista_core::error::Result<()> {
+        if self.executor_id.trim().is_empty() {
+            return Err(BallistaError::Configuration(
+                "executor_id must not be empty".to_string(),
+            ));
+        }
+
+        Ok(())
+    }
+
     /// Generates a prefix for log file names based on executor host and port.
     pub fn log_file_name_prefix(&self) -> String {
         format!(
@@ -359,6 +372,7 @@ impl ExecutorProcessConfig {
 impl Default for ExecutorProcessConfig {
     fn default() -> Self {
         Self {
+            executor_id: new_instance_id(),
             bind_host: "127.0.0.1".into(),
             external_host: None,
             port: 50051,
@@ -410,6 +424,8 @@ impl Default for ExecutorProcessConfig {
 pub async fn start_executor_process(
     opt: Arc<ExecutorProcessConfig>,
 ) -> ballista_core::error::Result<()> {
+    opt.validate()?;
+
     let addr = format!("{}:{}", opt.bind_host, opt.port);
     let address = addr.parse().map_err(|e: std::net::AddrParseError| {
         BallistaError::Configuration(e.to_string())
@@ -437,8 +453,7 @@ pub async fn start_executor_process(
         opt.vcores
     };
     let task_scheduling_policy = opt.task_scheduling_policy;
-    // assign this executor an unique ID
-    let executor_id = Uuid::new_v4().to_string();
+    let executor_id = opt.executor_id.clone();
     info!(
         "Ballista Executor v{BALLISTA_VERSION} (DataFusion v{DATAFUSION_VERSION}) starting ..."
     );
@@ -447,7 +462,7 @@ pub async fn start_executor_process(
     info!("Executor vcores (default: available CPU cores): {vcores}");
     info!("Executor scheduling policy: {task_scheduling_policy:?}");
 
-    let executor_meta = structure_executor_metadata(&executor_id, &opt, vcores as u32);
+    let executor_meta = structure_executor_metadata(&opt, vcores as u32);
 
     // put them to session config
     let metrics_collector = Arc::new(LoggingMetricsCollector::default());
@@ -1083,7 +1098,6 @@ pub async fn satisfy_dir_ttl(
 
 /// Structuring executor's metadata to start the main process
 pub fn structure_executor_metadata(
-    executor_id: &str,
     options: &Arc<ExecutorProcessConfig>,
     vcores: u32,
 ) -> ExecutorRegistration {
@@ -1108,7 +1122,7 @@ pub fn structure_executor_metadata(
     }
 
     ExecutorRegistration {
-        id: executor_id.to_string().clone(),
+        id: options.executor_id.clone(),
         host: options.external_host.clone(),
         port: options.port as u32,
         grpc_port: options.grpc_port as u32,
@@ -1136,16 +1150,73 @@ pub fn structure_executor_metadata(
 mod tests {
     use crate::executor_process::is_subdirectory;
     use std::path::{Path, PathBuf};
+    use std::sync::Arc;
 
+    use super::ExecutorProcessConfig;
     use super::clean_shuffle_data_loop;
     use super::remove_job_data;
+    use super::structure_executor_metadata;
+    use ballista_core::BALLISTA_PROTOCOL_VERSION;
     use ballista_core::JobId;
+    use ballista_core::ids::new_instance_id;
+    use ballista_core::serde::protobuf::executor_resource::Resource;
     use std::fs;
     use std::fs::File;
     use std::io::Write;
     use std::time::Duration;
     use tempfile::TempDir;
 
+    #[test]
+    fn executor_metadata_reflects_process_configuration() {
+        let executor_id = new_instance_id();
+        let config = Arc::new(ExecutorProcessConfig {
+            executor_id: executor_id.clone(),
+            external_host: Some("executor.example.com".to_string()),
+            port: 10051,
+            grpc_port: 10052,
+            ..ExecutorProcessConfig::default()
+        });
+
+        let metadata = structure_executor_metadata(&config, 4);
+
+        assert_eq!(metadata.id, executor_id);
+        uuid::Uuid::parse_str(&metadata.id).unwrap();
+        assert_eq!(metadata.host.as_deref(), Some("executor.example.com"));
+        assert_eq!(metadata.port, 10051);
+        assert_eq!(metadata.grpc_port, 10052);
+        assert_eq!(
+            metadata
+                .specification
+                .as_ref()
+                .and_then(|spec| spec.resources.first())
+                .and_then(|resource| resource.resource.as_ref()),
+            Some(&Resource::Vcores(4))
+        );
+        assert!(metadata.os_info.is_some());
+        assert_eq!(
+            metadata.ballista_protocol_version,
+            BALLISTA_PROTOCOL_VERSION
+        );
+    }
+
+    #[test]
+    fn default_executor_id_is_uuid() {
+        let config = ExecutorProcessConfig::default();
+
+        uuid::Uuid::parse_str(&config.executor_id).unwrap();
+    }
+
+    #[test]
+    fn validate_rejects_empty_executor_id() {
+        let config = ExecutorProcessConfig {
+            executor_id: " ".to_string(),
+            ..ExecutorProcessConfig::default()
+        };
+        let err = config.validate().unwrap_err();
+
+        assert!(err.to_string().contains("executor_id"));
+    }
+
     #[tokio::test]
     async fn test_executor_clean_up() {
         let work_dir = TempDir::new().unwrap();
diff --git a/ballista/executor/src/executor_server.rs b/ballista/executor/src/executor_server.rs
index c92caba6e..3313cbe54 100644
--- a/ballista/executor/src/executor_server.rs
+++ b/ballista/executor/src/executor_server.rs
@@ -81,17 +81,19 @@ const HEARTBEAT_FAILURE_TERMINATION_THRESHOLD: u32 = 5;
 type ServerHandle = JoinHandle<Result<(), BallistaError>>;
 type SchedulerClients = Arc<DashMap<String, SchedulerGrpcClient<Channel>>>;
 
-/// Wrap TaskDefinition with its curator scheduler id for task update to its specific curator scheduler later
+/// Wrap TaskDefinition with its scheduler callback endpoint so task updates
+/// return to the scheduler that launched the task.
 #[derive(Debug)]
 struct CuratorTaskDefinition {
-    scheduler_id: String,
+    scheduler_endpoint: String,
     task: TaskDefinition,
 }
 
-/// Wrap TaskStatus with its curator scheduler id for task update to its specific curator scheduler later
+/// Wrap TaskStatus with its scheduler callback endpoint so task updates return
+/// to the scheduler that launched the task.
 #[derive(Debug)]
 struct CuratorTaskStatus {
-    scheduler_id: String,
+    scheduler_endpoint: String,
     task_status: TaskStatus,
 }
 
@@ -293,20 +295,23 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> ExecutorServer<T,
 
     async fn get_scheduler_client(
         &self,
-        scheduler_id: &str,
+        scheduler_endpoint: &str,
     ) -> Result<SchedulerGrpcClient<Channel>, BallistaError> {
-        let scheduler = self.schedulers.get(scheduler_id).map(|value| value.clone());
+        let scheduler = self
+            .schedulers
+            .get(scheduler_endpoint)
+            .map(|value| value.clone());
         // If channel does not exist, create a new one
         if let Some(scheduler) = scheduler {
             Ok(scheduler)
         } else {
-            let scheduler_url = format!("http://{scheduler_id}");
+            let scheduler_url = format!("http://{scheduler_endpoint}");
             let mut endpoint = create_grpc_client_endpoint(scheduler_url, None)?;
 
             if let Some(ref override_fn) = self.override_create_grpc_client_endpoint {
                 endpoint = override_fn(endpoint).map_err(|e| {
                     BallistaError::GrpcConnectionError(format!(
-                        "Failed to customize endpoint for scheduler {scheduler_id}: {e}"
+                        "Failed to customize endpoint for scheduler {scheduler_endpoint}: {e}"
                     ))
                 })?;
             }
@@ -318,7 +323,7 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> ExecutorServer<T,
 
             {
                 self.schedulers
-                    .insert(scheduler_id.to_owned(), scheduler.clone());
+                    .insert(scheduler_endpoint.to_owned(), scheduler.clone());
             }
 
             Ok(scheduler)
@@ -361,7 +366,7 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> ExecutorServer<T,
         };
 
         for mut item in self.schedulers.iter_mut() {
-            let scheduler_id = item.key().clone();
+            let scheduler_endpoint = item.key().clone();
             let scheduler = item.value_mut();
 
             match scheduler
@@ -374,7 +379,7 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> ExecutorServer<T,
                 }
                 Err(e) => {
                     warn!(
-                        "Fail to update heartbeat to scheduler {scheduler_id} due to {e:?}"
+                        "Fail to update heartbeat to scheduler {scheduler_endpoint} due to {e:?}"
                     );
                 }
             }
@@ -501,7 +506,7 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> ExecutorServer<T,
                     .executor_env
                     .tx_task_status
                     .send(CuratorTaskStatus {
-                        scheduler_id: curator_task.scheduler_id,
+                        scheduler_endpoint: curator_task.scheduler_endpoint,
                         task_status,
                     })
                     .await;
@@ -528,7 +533,7 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> ExecutorServer<T,
                     .executor_env
                     .tx_task_status
                     .send(CuratorTaskStatus {
-                        scheduler_id: curator_task.scheduler_id,
+                        scheduler_endpoint: curator_task.scheduler_endpoint,
                         task_status,
                     })
                     .await;
@@ -751,7 +756,7 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> TaskRunnerPool<T,
                 let mut fetched_task_num = 0usize;
                 if let Some(task_status) = maybe_task_status {
                     let task_status_vec = curator_task_status_map
-                        .entry(task_status.scheduler_id)
+                        .entry(task_status.scheduler_endpoint)
                         .or_default();
                     task_status_vec.push(task_status.task_status);
                     fetched_task_num += 1;
@@ -766,7 +771,7 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> TaskRunnerPool<T,
                     match rx_task_status.try_recv() {
                         Ok(task_status) => {
                             let task_status_vec = curator_task_status_map
-                                .entry(task_status.scheduler_id)
+                                .entry(task_status.scheduler_endpoint)
                                 .or_default();
                             task_status_vec.push(task_status.task_status);
                             fetched_task_num += 1;
@@ -785,8 +790,13 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> TaskRunnerPool<T,
                     }
                 }
 
-                for (scheduler_id, tasks_status) in curator_task_status_map.into_iter() {
-                    match executor_server.get_scheduler_client(&scheduler_id).await {
+                for (scheduler_endpoint, tasks_status) in
+                    curator_task_status_map.into_iter()
+                {
+                    match executor_server
+                        .get_scheduler_client(&scheduler_endpoint)
+                        .await
+                    {
                         Ok(mut scheduler) => {
                             if let Err(e) = scheduler
                                 .update_task_status(UpdateTaskStatusParams {
@@ -806,7 +816,7 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> TaskRunnerPool<T,
                         }
                         Err(e) => {
                             error!(
-                                "Fail to connect to scheduler {scheduler_id} due to {e:?}"
+                                "Fail to connect to scheduler {scheduler_endpoint} due to {e:?}"
                             );
                         }
                     }
@@ -871,13 +881,13 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> ExecutorGrpc
     ) -> Result<Response<LaunchTaskResult>, Status> {
         let LaunchTaskParams {
             tasks,
-            scheduler_id,
+            scheduler_endpoint,
         } = request.into_inner();
         let task_sender = self.executor_env.tx_task.clone();
         for task in tasks {
             task_sender
                 .send(CuratorTaskDefinition {
-                    scheduler_id: scheduler_id.clone(),
+                    scheduler_endpoint: scheduler_endpoint.clone(),
                     task: get_task_definition(
                         task,
                         self.executor.runtime_producer.clone(),
@@ -907,7 +917,7 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> ExecutorGrpc
     ) -> Result<Response<LaunchMultiTaskResult>, Status> {
         let LaunchMultiTaskParams {
             multi_tasks,
-            scheduler_id,
+            scheduler_endpoint,
         } = request.into_inner();
         let task_sender = self.executor_env.tx_task.clone();
         let mut failed_jobs: HashSet<String> = HashSet::new();
@@ -937,7 +947,7 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> ExecutorGrpc
             for task in multi_task {
                 task_sender
                     .send(CuratorTaskDefinition {
-                        scheduler_id: scheduler_id.clone(),
+                        scheduler_endpoint: scheduler_endpoint.clone(),
                         task,
                     })
                     .await
diff --git a/ballista/executor/src/standalone.rs b/ballista/executor/src/standalone.rs
index 78e704295..470bf7049 100644
--- a/ballista/executor/src/standalone.rs
+++ b/ballista/executor/src/standalone.rs
@@ -29,6 +29,7 @@ use ballista_core::utils::{GrpcServerConfig, default_config_producer};
 use ballista_core::{
     BALLISTA_PROTOCOL_VERSION, BALLISTA_VERSION,
     error::Result,
+    ids::new_instance_id,
     serde::BallistaCodec,
     serde::protobuf::{ExecutorRegistration, scheduler_grpc_client::SchedulerGrpcClient},
     serde::scheduler::{ExecutorOperatingSystemSpecification, ExecutorSpecification},
@@ -41,7 +42,6 @@ use std::sync::Arc;
 use tempfile::TempDir;
 use tokio::net::TcpListener;
 use tonic::transport::Channel;
-use uuid::Uuid;
 
 /// Creates new standalone executor based on
 /// session_state provided.
@@ -99,7 +99,7 @@ pub async fn new_standalone_executor_from_builder(
     info!("Ballista v{BALLISTA_VERSION} Rust Executor listening on {address:?}");
 
     let executor_meta = ExecutorRegistration {
-        id: Uuid::new_v4().to_string(), // assign this executor a unique ID
+        id: new_instance_id(), // assign this executor a unique ID
         host: Some("localhost".to_string()),
         port: address.port() as u32,
         // TODO Make it configurable
diff --git a/ballista/history/src/event.rs b/ballista/history/src/event.rs
index dcd00af97..fcacc9e66 100644
--- a/ballista/history/src/event.rs
+++ b/ballista/history/src/event.rs
@@ -116,6 +116,9 @@ pub struct JobStart {
     pub queued_at: u64,
     /// When the job was submitted for planning.
     pub submitted_at: u64,
+    /// Identifier for the scheduler that accepted and planned the job, if one
+    /// is recorded.
+    pub scheduler_id: Option<String>,
     /// Rendered logical plan, if one was captured.
     pub logical_plan: Option<String>,
     /// Rendered physical plan, if one was captured.
diff --git a/ballista/history/src/writer.rs b/ballista/history/src/writer.rs
index 9ea8a5048..e643e3b32 100644
--- a/ballista/history/src/writer.rs
+++ b/ballista/history/src/writer.rs
@@ -305,6 +305,7 @@ mod tests {
                 job_name: "q1".into(),
                 queued_at: 1,
                 submitted_at: 2,
+                scheduler_id: None,
                 logical_plan: None,
                 physical_plan: None,
             }),
@@ -370,6 +371,7 @@ mod tests {
                 job_name: "q1".into(),
                 queued_at: 1,
                 submitted_at: 2,
+                scheduler_id: None,
                 logical_plan: None,
                 physical_plan: None,
             }),
@@ -415,6 +417,7 @@ mod tests {
                 job_name: "q1".into(),
                 queued_at: 1,
                 submitted_at: 2,
+                scheduler_id: None,
                 logical_plan: None,
                 physical_plan: None,
             }),
diff --git a/ballista/scheduler/src/api/handlers.rs b/ballista/scheduler/src/api/handlers.rs
index 1b195a92d..2bfa29fd7 100644
--- a/ballista/scheduler/src/api/handlers.rs
+++ b/ballista/scheduler/src/api/handlers.rs
@@ -45,6 +45,8 @@ use std::sync::Arc;
 #[derive(Debug, serde::Serialize, utoipa::ToSchema)]
 pub struct SchedulerStateResponse {
     pub started: u128,
+    /// Scheduler identity exposed in scheduler state.
+    pub scheduler_id: String,
     pub version: &'static str,
     pub datafusion_version: &'static str,
     pub substrait_support: bool,
@@ -184,6 +186,7 @@ pub async fn get_scheduler_state<
 ) -> impl IntoResponse {
     let response = SchedulerStateResponse {
         started: data_server.start_time,
+        scheduler_id: data_server.scheduler_id.clone(),
         version: BALLISTA_VERSION,
         datafusion_version: DATAFUSION_VERSION,
         substrait_support: cfg!(feature = "substrait"),
@@ -685,6 +688,50 @@ pub async fn get_job_config<
 mod tests {
     use super::*;
 
+    #[tokio::test]
+    async fn scheduler_state_reflects_server_configuration() {
+        use crate::config::SchedulerConfig;
+        use crate::metrics::default_metrics_collector;
+        use crate::test_utils::test_cluster_context;
+        use axum::response::IntoResponse;
+        use ballista_core::serde::BallistaCodec;
+        use datafusion::DATAFUSION_VERSION;
+        use datafusion_proto::protobuf::{LogicalPlanNode, PhysicalPlanNode};
+
+        let config = SchedulerConfig::default()
+            .with_scheduler_id("scheduler-a")
+            .with_advertise_flight_endpoint(Some("flight.example.com:50055".into()))
+            .with_enable_embedded_flight_proxy(true);
+        let expected_scheduling_policy = config.scheduling_policy.to_string();
+        let server: Arc<SchedulerServer<LogicalPlanNode, PhysicalPlanNode>> =
+            Arc::new(SchedulerServer::new(
+                "localhost:50050".to_owned(),
+                test_cluster_context(),
+                BallistaCodec::default(),
+                Arc::new(config),
+                default_metrics_collector().unwrap(),
+            ));
+
+        let response = get_scheduler_state(State(server)).await.into_response();
+        assert_eq!(response.status(), StatusCode::OK);
+
+        let body = axum::body::to_bytes(response.into_body(), usize::MAX)
+            .await
+            .unwrap();
+        let body: serde_json::Value = serde_json::from_slice(&body).unwrap();
+
+        assert!(body["started"].is_number());
+        assert_eq!(body["scheduler_id"], "scheduler-a");
+        assert_eq!(body["version"], BALLISTA_VERSION);
+        assert_eq!(body["datafusion_version"], DATAFUSION_VERSION);
+        assert_eq!(body["scheduling_policy"], expected_scheduling_policy);
+        assert_eq!(
+            body["advertise_flight_endpoint"],
+            "flight.example.com:50055"
+        );
+        assert_eq!(body["enable_embedded_flight_proxy"], true);
+    }
+
     mod get_webtui {
         use super::*;
         use crate::config::SchedulerConfig;
diff --git a/ballista/scheduler/src/cluster/memory.rs b/ballista/scheduler/src/cluster/memory.rs
index 3baef1ddd..f14ae4a81 100644
--- a/ballista/scheduler/src/cluster/memory.rs
+++ b/ballista/scheduler/src/cluster/memory.rs
@@ -125,7 +125,28 @@ impl ClusterState for InMemoryClusterState {
         let executor_id = metadata.id.clone();
         log::debug!("registering executor: {}", executor_id);
 
-        self.save_executor_metadata(metadata).await?;
+        if spec.executor_id != executor_id {
+            return Err(BallistaError::Configuration(format!(
+                "executor data id {} does not match metadata id {executor_id}",
+                spec.executor_id
+            )));
+        }
+
+        match self.executors.entry(executor_id.clone()) {
+            dashmap::mapref::entry::Entry::Occupied(_) => {
+                return Err(BallistaError::Configuration(format!(
+                    "executor_id {executor_id} is already registered"
+                )));
+            }
+            dashmap::mapref::entry::Entry::Vacant(entry) => {
+                entry.insert(metadata);
+                self.cluster_event_sender
+                    .send(&ClusterStateEvent::RegisteredExecutor {
+                        executor_id: executor_id.to_string(),
+                    });
+            }
+        };
+
         self.save_executor_heartbeat(ExecutorHeartbeat {
             executor_id: executor_id.clone(),
             timestamp: timestamp_secs(),
@@ -148,15 +169,6 @@ impl ClusterState for InMemoryClusterState {
             },
         );
 
-        // RegisteredExecutor event is not pushed from here,
-        // in order to align between push and pull policy
-        // event is pushed from `save_executor_metadata`
-        //
-        // self.cluster_event_sender
-        //     .send(&ClusterStateEvent::RegisteredExecutor {
-        //         executor_id: executor_id.to_string(),
-        //     });
-
         Ok(())
     }
 
@@ -167,15 +179,21 @@ impl ClusterState for InMemoryClusterState {
         //       insert time. This information may be useful when reporting executor
         //       status and heartbeat is not available (in case of `TaskSchedulingPolicy::PullStaged`)
         let executor_id = metadata.id.clone();
-        if self
-            .executors
-            .insert(executor_id.clone(), metadata)
-            .is_none()
-        {
-            self.cluster_event_sender
-                .send(&ClusterStateEvent::RegisteredExecutor {
-                    executor_id: executor_id.to_string(),
-                });
+        match self.executors.entry(executor_id.clone()) {
+            dashmap::mapref::entry::Entry::Occupied(entry) => {
+                if entry.get() != &metadata {
+                    return Err(BallistaError::Configuration(format!(
+                        "executor_id {executor_id} is already registered"
+                    )));
+                }
+            }
+            dashmap::mapref::entry::Entry::Vacant(entry) => {
+                entry.insert(metadata);
+                self.cluster_event_sender
+                    .send(&ClusterStateEvent::RegisteredExecutor {
+                        executor_id: executor_id.to_string(),
+                    });
+            }
         }
 
         //
@@ -535,7 +553,8 @@ mod test {
     use ballista_core::error::Result;
     use ballista_core::serde::protobuf::JobStatus;
     use ballista_core::serde::scheduler::{
-        ExecutorMetadata, ExecutorOperatingSystemSpecification, ExecutorSpecification,
+        ExecutorData, ExecutorMetadata, ExecutorOperatingSystemSpecification,
+        ExecutorSpecification,
     };
     use ballista_core::utils::{default_config_producer, default_session_builder};
     use datafusion::prelude::SessionConfig;
@@ -730,6 +749,79 @@ mod test {
         Ok(())
     }
 
+    #[tokio::test]
+    async fn register_executor_rejects_duplicate_id() -> Result<()> {
+        let cluster_state = InMemoryClusterState::default();
+
+        let metadata = ExecutorMetadata {
+            id: "id123".to_string(),
+            host: "executor-a".to_string(),
+            port: 50055,
+            grpc_port: 50050,
+            specification: ExecutorSpecification::default().with_vcores(2),
+            os_info: ExecutorOperatingSystemSpecification::default(),
+        };
+        let executor_data = ExecutorData {
+            executor_id: metadata.id.clone(),
+            total_vcores: 2,
+            available_vcores: 2,
+        };
+
+        cluster_state
+            .register_executor(metadata.clone(), executor_data.clone())
+            .await?;
+
+        let err = cluster_state
+            .register_executor(metadata.clone(), executor_data)
+            .await
+            .unwrap_err();
+
+        assert!(err.to_string().contains("id123 is already registered"));
+        assert_eq!(
+            cluster_state.get_executor_metadata("id123").await?,
+            metadata
+        );
+
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn save_executor_metadata_rejects_duplicate_id() -> Result<()> {
+        let cluster_state = InMemoryClusterState::default();
+
+        let metadata = ExecutorMetadata {
+            id: "id123".to_string(),
+            host: "executor-a".to_string(),
+            port: 50055,
+            grpc_port: 50050,
+            specification: ExecutorSpecification::default().with_vcores(2),
+            os_info: ExecutorOperatingSystemSpecification::default(),
+        };
+
+        cluster_state
+            .save_executor_metadata(metadata.clone())
+            .await?;
+        cluster_state
+            .save_executor_metadata(metadata.clone())
+            .await?;
+
+        let mut duplicate = metadata.clone();
+        duplicate.host = "executor-b".to_string();
+
+        let err = cluster_state
+            .save_executor_metadata(duplicate)
+            .await
+            .unwrap_err();
+
+        assert!(err.to_string().contains("id123 is already registered"));
+        assert_eq!(
+            cluster_state.get_executor_metadata("id123").await?,
+            metadata
+        );
+
+        Ok(())
+    }
+
     #[tokio::test]
     async fn test_in_memory_session_notification() -> Result<()> {
         let state = InMemoryJobState::new(
diff --git a/ballista/scheduler/src/cluster/mod.rs b/ballista/scheduler/src/cluster/mod.rs
index 736734441..dbcff2201 100644
--- a/ballista/scheduler/src/cluster/mod.rs
+++ b/ballista/scheduler/src/cluster/mod.rs
@@ -108,7 +108,7 @@ impl BallistaCluster {
 
     /// Creates a new `BallistaCluster` from scheduler configuration.
     pub async fn new_from_config(config: &SchedulerConfig) -> Result<Self> {
-        let scheduler = config.scheduler_name();
+        let scheduler = config.scheduler_id.clone();
 
         let session_builder = config
             .override_session_builder
diff --git a/ballista/scheduler/src/config.rs b/ballista/scheduler/src/config.rs
index 0d7f7949b..ee071c303 100644
--- a/ballista/scheduler/src/config.rs
+++ b/ballista/scheduler/src/config.rs
@@ -29,7 +29,9 @@ use crate::SessionBuilder;
 use crate::cluster::DistributionPolicy;
 use crate::scheduler_server::JobIdGenerator;
 use ballista_core::extension::EndpointOverrideFn;
-use ballista_core::{ConfigProducer, JobId, config::TaskSchedulingPolicy};
+use ballista_core::{
+    ConfigProducer, JobId, config::TaskSchedulingPolicy, ids::new_instance_id,
+};
 use datafusion_proto::logical_plan::LogicalExtensionCodec;
 use datafusion_proto::physical_plan::PhysicalExtensionCodec;
 use log::{info, warn};
@@ -101,6 +103,10 @@ pub struct Config {
         help = "Namespace for the ballista cluster that this executor will join."
     )]
     pub namespace: String,
+    /// Identifier for this scheduler. If unset, a UUID-backed instance identity
+    /// is generated at startup.
+    #[arg(long = "id", help = "Identifier for this scheduler.")]
+    pub scheduler_id: Option<String>,
     /// Local host name or IP address to bind to.
     #[arg(
         long,
@@ -313,6 +319,8 @@ pub struct SchedulerConfig {
     /// Namespace of this scheduler. Schedulers using the same cluster storage and namespace
     /// will share global cluster state.
     pub namespace: String,
+    /// Identifier for this scheduler instance.
+    pub scheduler_id: String,
     /// The external hostname of the scheduler
     pub external_host: String,
     /// The bind host for the scheduler's gRPC service
@@ -422,6 +430,7 @@ impl Default for SchedulerConfig {
     fn default() -> Self {
         Self {
             namespace: String::default(),
+            scheduler_id: new_instance_id(),
             external_host: "localhost".into(),
             bind_port: 50050,
             bind_host: "127.0.0.1".into(),
@@ -473,6 +482,12 @@ impl SchedulerConfig {
     /// Suspicious combinations are logged as warnings rather than rejected,
     /// since small values are legitimate for fail-fast setups and tests.
     pub fn validate(&self) -> ballista_core::error::Result<()> {
+        if self.scheduler_id.trim().is_empty() {
+            return Err(ballista_core::error::BallistaError::Configuration(
+                "scheduler_id must not be empty".to_string(),
+            ));
+        }
+
         if self.no_executors_grace_period_seconds != 0
             && self.no_executors_grace_period_seconds < self.executor_timeout_seconds
         {
@@ -522,8 +537,8 @@ impl SchedulerConfig {
         Ok(())
     }
 
-    /// Returns the scheduler name in host:port format.
-    pub fn scheduler_name(&self) -> String {
+    /// Returns the scheduler callback endpoint in host:port format.
+    pub fn scheduler_endpoint(&self) -> String {
         format!("{}:{}", self.external_host, self.bind_port)
     }
 
@@ -538,6 +553,12 @@ impl SchedulerConfig {
         self
     }
 
+    /// Sets the unique identifier for this scheduler instance.
+    pub fn with_scheduler_id(mut self, scheduler_id: impl Into<String>) -> Self {
+        self.scheduler_id = scheduler_id.into();
+        self
+    }
+
     /// Sets the external hostname for this scheduler.
     pub fn with_hostname(mut self, hostname: impl Into<String>) -> Self {
         self.external_host = hostname.into();
@@ -785,6 +806,7 @@ impl TryFrom<Config> for SchedulerConfig {
 
         let config = SchedulerConfig {
             namespace: opt.namespace,
+            scheduler_id: opt.scheduler_id.unwrap_or_else(new_instance_id),
             external_host: opt.external_host,
             bind_port: opt.bind_port,
             bind_host: opt.bind_host,
@@ -861,6 +883,24 @@ mod tests {
         );
     }
 
+    #[cfg(feature = "build-binary")]
+    #[test]
+    fn cli_scheduler_id_explicit_value_is_respected() {
+        use clap::Parser;
+        let opt = Config::parse_from(["scheduler", "--id", "scheduler-a"]);
+        let cfg = SchedulerConfig::try_from(opt).unwrap();
+        assert_eq!(cfg.scheduler_id, "scheduler-a");
+    }
+
+    #[cfg(feature = "build-binary")]
+    #[test]
+    fn cli_scheduler_id_defaults_to_uuid_when_unset() {
+        use clap::Parser;
+        let opt = Config::parse_from(["scheduler"]);
+        let cfg = SchedulerConfig::try_from(opt).unwrap();
+        uuid::Uuid::parse_str(&cfg.scheduler_id).unwrap();
+    }
+
     #[cfg(feature = "build-binary")]
     #[test]
     fn cli_grace_period_defaults_to_executor_timeout_when_unset() {
@@ -892,6 +932,21 @@ mod tests {
         SchedulerConfig::default().validate().unwrap();
     }
 
+    #[test]
+    fn default_scheduler_id_is_uuid() {
+        let cfg = SchedulerConfig::default();
+
+        uuid::Uuid::parse_str(&cfg.scheduler_id).unwrap();
+    }
+
+    #[test]
+    fn validate_rejects_empty_scheduler_id() {
+        let cfg = SchedulerConfig::default().with_scheduler_id(" ");
+        let err = cfg.validate().unwrap_err();
+
+        assert!(err.to_string().contains("scheduler_id"));
+    }
+
     #[cfg(feature = "build-binary")]
     #[test]
     fn cli_bare_advertise_endpoint_enables_embedded_proxy() {
diff --git a/ballista/scheduler/src/history/mod.rs b/ballista/scheduler/src/history/mod.rs
index d705bffee..d3249bdde 100644
--- a/ballista/scheduler/src/history/mod.rs
+++ b/ballista/scheduler/src/history/mod.rs
@@ -543,6 +543,7 @@ async fn get_executors_empty() -> Json<Vec<()>> {
 async fn get_state() -> Json<serde_json::Value> {
     Json(serde_json::json!({
         "started": 0,
+        "scheduler_id": "history-server",
         "version": BALLISTA_VERSION,
         "datafusion_version": DATAFUSION_VERSION,
         "substrait_support": false,
@@ -551,6 +552,7 @@ async fn get_state() -> Json<serde_json::Value> {
         "graphviz_support": false,
         "spark_support": false,
         "scheduling_policy": "history-server",
+        "enable_embedded_flight_proxy": false,
     }))
 }
 
@@ -720,6 +722,7 @@ mod tests {
         let value: serde_json::Value = serde_json::from_slice(&bytes).unwrap();
         for field in [
             "started",
+            "scheduler_id",
             "version",
             "datafusion_version",
             "substrait_support",
@@ -728,9 +731,12 @@ mod tests {
             "graphviz_support",
             "spark_support",
             "scheduling_policy",
+            "enable_embedded_flight_proxy",
         ] {
             assert!(value.get(field).is_some(), "missing field: {field}");
         }
+        assert_eq!(value["scheduler_id"], "history-server");
+        assert_eq!(value["enable_embedded_flight_proxy"], false);
     }
 
     /// Job ids are random 7-character strings, so ordering the list by id puts
diff --git a/ballista/scheduler/src/scheduler_process.rs b/ballista/scheduler/src/scheduler_process.rs
index 449493c93..772c5b0c6 100644
--- a/ballista/scheduler/src/scheduler_process.rs
+++ b/ballista/scheduler/src/scheduler_process.rs
@@ -74,7 +74,7 @@ pub async fn create_scheduler<
     let metrics_collector = default_metrics_collector()?;
 
     let mut scheduler_server = SchedulerServer::new(
-        config.scheduler_name(),
+        config.scheduler_endpoint(),
         cluster,
         codec,
         config,
diff --git a/ballista/scheduler/src/scheduler_server/event_log.rs b/ballista/scheduler/src/scheduler_server/event_log.rs
index 83b0bb264..d2634790a 100644
--- a/ballista/scheduler/src/scheduler_server/event_log.rs
+++ b/ballista/scheduler/src/scheduler_server/event_log.rs
@@ -49,6 +49,7 @@ pub(crate) fn job_start_event(
         job_name: graph.job_name().to_string(),
         queued_at,
         submitted_at,
+        scheduler_id: graph.scheduler_id().map(str::to_owned),
         logical_plan: graph.logical_plan().map(|p| p.to_string()),
         // Same rendering the `get_job` handler uses for `PlanFormat::Default`.
         physical_plan: Some(
@@ -373,6 +374,7 @@ mod tests {
         assert!(json.contains("\"job_name\":\"job_name\""));
         assert!(json.contains("\"queued_at\":5"));
         assert!(json.contains("\"submitted_at\":10"));
+        assert!(json.contains("\"scheduler_id\":\"scheduler_id\""));
         // `job_start_event` renders the graph's pre-staging physical plan
         // (`graph.physical_plan()`), unlike `job_end_event`'s embedded job
         // DTO which shows the plan reconstructed from stages.
diff --git a/ballista/scheduler/src/scheduler_server/grpc.rs b/ballista/scheduler/src/scheduler_server/grpc.rs
index e6c785bc1..c1be5c075 100644
--- a/ballista/scheduler/src/scheduler_server/grpc.rs
+++ b/ballista/scheduler/src/scheduler_server/grpc.rs
@@ -82,6 +82,19 @@ fn check_protocol_version(metadata: &ExecutorRegistration) -> Result<(), Status>
     )))
 }
 
+fn executor_registration_error(e: BallistaError) -> Status {
+    let msg = format!("Fail to do executor registration due to: {e}");
+    error!("{msg}");
+    match e {
+        BallistaError::Configuration(message)
+            if message.contains("already registered") =>
+        {
+            Status::already_exists(msg)
+        }
+        _ => Status::internal(msg),
+    }
+}
+
 #[tonic::async_trait]
 impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> SchedulerGrpc
     for SchedulerServer<T, U>
@@ -123,14 +136,11 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> SchedulerGrpc
                     specification: metadata.specification.unwrap().into(),
                     os_info: metadata.os_info.unwrap().into(),
                 };
-                if let Err(e) = self
-                    .state
+                self.state
                     .executor_manager
                     .save_executor_metadata(metadata)
                     .await
-                {
-                    warn!("Could not save executor metadata: {e:?}");
-                }
+                    .map_err(executor_registration_error)?;
             }
 
             self.update_task_status(&executor_id, task_status)
@@ -219,11 +229,9 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> SchedulerGrpc
                 os_info: metadata.os_info.unwrap().into(),
             };
 
-            self.do_register_executor(metadata).await.map_err(|e| {
-                let msg = format!("Fail to do executor registration due to: {e}");
-                error!("{msg}");
-                Status::internal(msg)
-            })?;
+            self.do_register_executor(metadata)
+                .await
+                .map_err(executor_registration_error)?;
 
             Ok(Response::new(RegisterExecutorResult { success: true }))
         } else {
@@ -278,11 +286,9 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> SchedulerGrpc
                     os_info: metadata.os_info.unwrap().into(),
                 };
 
-                self.do_register_executor(metadata).await.map_err(|e| {
-                    let msg = format!("Fail to do executor registration due to: {e}");
-                    error!("{msg}");
-                    Status::internal(msg)
-                })?;
+                self.do_register_executor(metadata)
+                    .await
+                    .map_err(executor_registration_error)?;
             } else {
                 return Err(Status::invalid_argument(format!(
                     "The registration spec for executor {executor_id} is not included"
@@ -902,7 +908,7 @@ mod test {
 
     use datafusion_proto::protobuf::LogicalPlanNode;
     use datafusion_proto::protobuf::PhysicalPlanNode;
-    use tonic::Request;
+    use tonic::{Code, Request};
 
     #[cfg(feature = "substrait")]
     use {
@@ -929,7 +935,16 @@ mod test {
     use crate::test_utils::await_condition;
     use crate::test_utils::test_cluster_context;
 
-    use super::{SchedulerGrpc, SchedulerServer};
+    use super::{SchedulerGrpc, SchedulerServer, executor_registration_error};
+
+    #[test]
+    fn duplicate_executor_registration_maps_to_already_exists() {
+        let status = executor_registration_error(BallistaError::Configuration(
+            "executor_id id123 is already registered".to_string(),
+        ));
+
+        assert_eq!(status.code(), Code::AlreadyExists);
+    }
 
     #[tokio::test]
     async fn test_pull_work() -> Result<(), BallistaError> {
@@ -969,7 +984,7 @@ mod test {
         // no response task since we told the scheduler we didn't want to accept one
         assert!(response.tasks.is_empty());
         let state: SchedulerState<LogicalPlanNode, PhysicalPlanNode> =
-            SchedulerState::new_with_default_scheduler_name(
+            SchedulerState::new_with_default_scheduler_endpoint(
                 cluster.clone(),
                 BallistaCodec::default(),
             );
@@ -1001,7 +1016,7 @@ mod test {
         // still no response task since there are no tasks in the scheduler
         assert!(response.tasks.is_empty());
         let state: SchedulerState<LogicalPlanNode, PhysicalPlanNode> =
-            SchedulerState::new_with_default_scheduler_name(
+            SchedulerState::new_with_default_scheduler_endpoint(
                 cluster.clone(),
                 BallistaCodec::default(),
             );
@@ -1019,6 +1034,26 @@ mod test {
         assert_eq!(stored_executor.specification.vcores, 2);
         assert_eq!(stored_executor.host, "http://localhost:8080".to_owned());
 
+        let mut conflicting_exec_meta = exec_meta.clone();
+        conflicting_exec_meta.host = Some("http://localhost:8081".to_owned());
+        let request: Request<PollWorkParams> = Request::new(PollWorkParams {
+            metadata: Some(conflicting_exec_meta),
+            num_free_vcores: 1,
+            task_status: vec![],
+        });
+        let err = match scheduler.poll_work(request).await {
+            Ok(_) => panic!("duplicate executor id should fail poll_work"),
+            Err(err) => err,
+        };
+
+        assert_eq!(err.code(), Code::AlreadyExists);
+        let stored_executor = state
+            .executor_manager
+            .get_executor_metadata("abc")
+            .await
+            .expect("getting executor");
+        assert_eq!(stored_executor.host, "http://localhost:8080".to_owned());
+
         Ok(())
     }
 
diff --git a/ballista/scheduler/src/scheduler_server/mod.rs b/ballista/scheduler/src/scheduler_server/mod.rs
index 98e668d04..b606ec6c6 100644
--- a/ballista/scheduler/src/scheduler_server/mod.rs
+++ b/ballista/scheduler/src/scheduler_server/mod.rs
@@ -40,7 +40,7 @@ use crate::cluster::{BallistaCluster, ClusterStateEventStream, JobStateEventStre
 use crate::config::SchedulerConfig;
 use crate::metrics::SchedulerMetricsCollector;
 use ballista_core::serde::scheduler::{ExecutorData, ExecutorMetadata};
-use log::{debug, warn};
+use log::{debug, info, warn};
 
 use crate::scheduler_server::event::{QueryStageSchedulerEvent, SubmitPlan};
 use crate::scheduler_server::query_stage_scheduler::QueryStageScheduler;
@@ -127,8 +127,10 @@ impl JobIdGenerator for DefaultJobGenerator {
 /// - Tracking job progress and handling failures
 #[derive(Clone)]
 pub struct SchedulerServer<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> {
-    /// Unique name identifying this scheduler instance.
-    pub scheduler_name: String,
+    /// Unique identifier for this scheduler instance.
+    pub scheduler_id: String,
+    /// Scheduler callback endpoint in host:port format.
+    pub scheduler_endpoint: String,
     /// Timestamp when this scheduler was started.
     pub start_time: u128,
     /// Shared scheduler state for job and executor management.
@@ -147,45 +149,61 @@ pub struct SchedulerServer<T: 'static + AsLogicalPlan, U: 'static + AsExecutionP
 impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> SchedulerServer<T, U> {
     /// Creates a new `SchedulerServer` with the given configuration.
     pub fn new(
-        scheduler_name: String,
+        scheduler_endpoint: String,
         cluster: BallistaCluster,
         codec: BallistaCodec<T, U>,
         config: Arc<SchedulerConfig>,
         metrics_collector: Arc<dyn SchedulerMetricsCollector>,
     ) -> Self {
+        let scheduler_id = config.scheduler_id.clone();
         let state = Arc::new(SchedulerState::new(
             cluster,
             codec,
-            scheduler_name.clone(),
+            scheduler_id.clone(),
+            scheduler_endpoint.clone(),
             config.clone(),
         ));
 
-        Self::from_state(scheduler_name, state, config, metrics_collector)
+        Self::from_state(
+            scheduler_id,
+            scheduler_endpoint,
+            state,
+            config,
+            metrics_collector,
+        )
     }
 
     /// Creates a new `SchedulerServer` with a custom task launcher.
     #[allow(dead_code)]
     pub fn new_with_task_launcher(
-        scheduler_name: String,
+        scheduler_endpoint: String,
         cluster: BallistaCluster,
         codec: BallistaCodec<T, U>,
         config: Arc<SchedulerConfig>,
         metrics_collector: Arc<dyn SchedulerMetricsCollector>,
         task_launcher: Arc<dyn TaskLauncher>,
     ) -> Self {
+        let scheduler_id = config.scheduler_id.clone();
         let state = Arc::new(SchedulerState::new_with_task_launcher(
             cluster,
             codec,
-            scheduler_name.clone(),
+            scheduler_id.clone(),
             config.clone(),
             task_launcher,
         ));
 
-        Self::from_state(scheduler_name, state, config, metrics_collector)
+        Self::from_state(
+            scheduler_id,
+            scheduler_endpoint,
+            state,
+            config,
+            metrics_collector,
+        )
     }
 
     fn from_state(
-        scheduler_name: String,
+        scheduler_id: String,
+        scheduler_endpoint: String,
         state: Arc<SchedulerState<T, U>>,
         config: Arc<SchedulerConfig>,
         metrics_collector: Arc<dyn SchedulerMetricsCollector>,
@@ -215,8 +233,12 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> SchedulerServer<T
             .clone()
             .unwrap_or_else(|| Arc::new(DefaultJobGenerator::default()));
 
+        info!("Scheduler id: {scheduler_id}");
+        info!("Scheduler callback endpoint: {scheduler_endpoint}");
+
         Self {
-            scheduler_name,
+            scheduler_id,
+            scheduler_endpoint,
             start_time: timestamp_millis() as u128,
             state,
             query_stage_event_loop,
diff --git a/ballista/scheduler/src/state/aqe/mod.rs b/ballista/scheduler/src/state/aqe/mod.rs
index eae9380b9..8ede8b112 100644
--- a/ballista/scheduler/src/state/aqe/mod.rs
+++ b/ballista/scheduler/src/state/aqe/mod.rs
@@ -97,8 +97,7 @@ mod test;
 /// when they are returned from [AdaptivePlanner].
 #[derive(Debug, Clone)]
 pub(crate) struct AdaptiveExecutionGraph {
-    /// Curator scheduler name. Can be `None` is `ExecutionGraph` is not currently curated by any scheduler
-    #[allow(dead_code)] // not used at the moment, will be used later
+    /// Scheduler currently curating this job, if known.
     scheduler_id: Option<String>,
     /// Adaptive Planner to be used with this execution graph
     planner: AdaptivePlanner,
@@ -699,6 +698,10 @@ impl ExecutionGraph for AdaptiveExecutionGraph {
         self.session_id.as_str()
     }
 
+    fn scheduler_id(&self) -> Option<&str> {
+        self.scheduler_id.as_deref()
+    }
+
     fn session_config(&self) -> Arc<SessionConfig> {
         self.session_config.clone()
     }
diff --git a/ballista/scheduler/src/state/execution_graph.rs b/ballista/scheduler/src/state/execution_graph.rs
index ead4ef53d..54c62fbeb 100644
--- a/ballista/scheduler/src/state/execution_graph.rs
+++ b/ballista/scheduler/src/state/execution_graph.rs
@@ -114,6 +114,9 @@ pub trait ExecutionGraph: Debug {
     /// Returns the session ID associated with this job.
     fn session_id(&self) -> &str;
 
+    /// Returns the scheduler that accepted and planned this job, if known.
+    fn scheduler_id(&self) -> Option<&str>;
+
     /// Returns the session config associated with this job.
     fn session_config(&self) -> Arc<SessionConfig>;
 
@@ -283,8 +286,7 @@ pub trait ExecutionGraph: Debug {
 /// all stages on job submission time
 #[derive(Clone)]
 pub struct StaticExecutionGraph {
-    /// Curator scheduler name. Can be `None` is `ExecutionGraph` is not currently curated by any scheduler
-    #[allow(dead_code)] // not used at the moment, will be used later
+    /// Scheduler currently curating this job, if known.
     scheduler_id: Option<String>,
     /// ID for this job
     job_id: JobId,
@@ -675,6 +677,10 @@ impl ExecutionGraph for StaticExecutionGraph {
         self.session_id.as_str()
     }
 
+    fn scheduler_id(&self) -> Option<&str> {
+        self.scheduler_id.as_deref()
+    }
+
     fn session_config(&self) -> Arc<SessionConfig> {
         self.session_config.clone()
     }
diff --git a/ballista/scheduler/src/state/executor_manager.rs b/ballista/scheduler/src/state/executor_manager.rs
index 5ba270e1e..27baf61de 100644
--- a/ballista/scheduler/src/state/executor_manager.rs
+++ b/ballista/scheduler/src/state/executor_manager.rs
@@ -427,7 +427,7 @@ impl ExecutorManager {
         &self,
         executor_id: &str,
         multi_tasks: Vec<MultiTaskDefinition>,
-        scheduler_id: String,
+        scheduler_endpoint: String,
     ) -> Result<HashSet<JobId>> {
         let mut client = self
             .get_client(executor_id, &self.grpc_client_config)
@@ -435,7 +435,7 @@ impl ExecutorManager {
         let res = client
             .launch_multi_task(protobuf::LaunchMultiTaskParams {
                 multi_tasks,
-                scheduler_id,
+                scheduler_endpoint,
             })
             .await?
             .into_inner();
diff --git a/ballista/scheduler/src/state/mod.rs b/ballista/scheduler/src/state/mod.rs
index a23db7af2..b544a2be2 100644
--- a/ballista/scheduler/src/state/mod.rs
+++ b/ballista/scheduler/src/state/mod.rs
@@ -114,7 +114,8 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> SchedulerState<T,
     pub fn new(
         cluster: BallistaCluster,
         codec: BallistaCodec<T, U>,
-        scheduler_name: String,
+        scheduler_id: String,
+        scheduler_endpoint: String,
         config: Arc<SchedulerConfig>,
     ) -> Self {
         Self {
@@ -125,7 +126,8 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> SchedulerState<T,
             task_manager: TaskManager::new(
                 cluster.job_state(),
                 codec.clone(),
-                scheduler_name,
+                scheduler_id,
+                scheduler_endpoint,
                 config.clone(),
             ),
             session_manager: SessionManager::new(cluster.job_state()),
@@ -134,21 +136,27 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> SchedulerState<T,
         }
     }
 
-    /// Creates a new `SchedulerState` with default scheduler name (for testing only).
+    /// Creates a new `SchedulerState` with the default scheduler endpoint (for testing only).
     #[cfg(test)]
-    pub fn new_with_default_scheduler_name(
+    pub fn new_with_default_scheduler_endpoint(
         cluster: BallistaCluster,
         codec: BallistaCodec<T, U>,
     ) -> Self {
         let config = Arc::new(SchedulerConfig::default());
-        SchedulerState::new(cluster, codec, "localhost:50050".to_owned(), config)
+        SchedulerState::new(
+            cluster,
+            codec,
+            config.scheduler_id.clone(),
+            "localhost:50050".to_owned(),
+            config,
+        )
     }
 
     #[allow(dead_code)]
     pub(crate) fn new_with_task_launcher(
         cluster: BallistaCluster,
         codec: BallistaCodec<T, U>,
-        scheduler_name: String,
+        scheduler_id: String,
         config: Arc<SchedulerConfig>,
         dispatcher: Arc<dyn TaskLauncher>,
     ) -> Self {
@@ -160,7 +168,7 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> SchedulerState<T,
             task_manager: TaskManager::with_launcher(
                 cluster.job_state(),
                 codec.clone(),
-                scheduler_name,
+                scheduler_id,
                 dispatcher,
                 config.clone(),
             ),
diff --git a/ballista/scheduler/src/state/task_manager.rs b/ballista/scheduler/src/state/task_manager.rs
index 7d67b8d8b..0ed587f4e 100644
--- a/ballista/scheduler/src/state/task_manager.rs
+++ b/ballista/scheduler/src/state/task_manager.rs
@@ -74,12 +74,12 @@ pub trait TaskLauncher: Send + Sync + 'static {
 }
 
 struct DefaultTaskLauncher {
-    scheduler_id: String,
+    scheduler_endpoint: String,
 }
 
 impl DefaultTaskLauncher {
-    pub fn new(scheduler_id: String) -> Self {
-        Self { scheduler_id }
+    pub fn new(scheduler_endpoint: String) -> Self {
+        Self { scheduler_endpoint }
     }
 }
 
@@ -109,7 +109,7 @@ impl TaskLauncher for DefaultTaskLauncher {
             );
         }
         let res = executor_manager
-            .launch_multi_task(&executor.id, tasks, self.scheduler_id.clone())
+            .launch_multi_task(&executor.id, tasks, self.scheduler_endpoint.clone())
             .await?;
         Ok(res)
     }
@@ -187,6 +187,7 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> TaskManager<T, U>
         state: Arc<dyn JobState>,
         codec: BallistaCodec<T, U>,
         scheduler_id: String,
+        scheduler_endpoint: String,
         config: Arc<SchedulerConfig>,
     ) -> Self {
         Self {
@@ -194,7 +195,7 @@ impl<T: 'static + AsLogicalPlan, U: 'static + AsExecutionPlan> TaskManager<T, U>
             codec,
             scheduler_id: scheduler_id.clone(),
             active_job_cache: Arc::new(DashMap::new()),
-            launcher: Arc::new(DefaultTaskLauncher::new(scheduler_id)),
+            launcher: Arc::new(DefaultTaskLauncher::new(scheduler_endpoint)),
             task_max_failures: config.task_max_failures,
             stage_max_failures: config.stage_max_failures,
         }
@@ -1238,6 +1239,7 @@ mod tests {
             job_state,
             BallistaCodec::default(),
             "test-scheduler".to_string(),
+            "localhost:50050".to_string(),
             Arc::new(SchedulerConfig::default()),
         );
 
diff --git a/ballista/scheduler/src/test_utils.rs b/ballista/scheduler/src/test_utils.rs
index 50b810e73..d6209df92 100644
--- a/ballista/scheduler/src/test_utils.rs
+++ b/ballista/scheduler/src/test_utils.rs
@@ -69,7 +69,7 @@ pub const TPCH_TABLES: &[&str] = &[
     "part", "supplier", "partsupp", "customer", "orders", "lineitem", "nation", "region",
 ];
 
-const TEST_SCHEDULER_NAME: &str = "localhost:50050";
+const TEST_SCHEDULER_ENDPOINT: &str = "localhost:50050";
 
 /// Sometimes we need to construct logical plans that will produce errors
 /// when we try and create physical plan. A scan using `ExplodingTableProvider`
@@ -126,7 +126,7 @@ pub async fn await_condition<Fut: Future<Output = Result<bool>>, F: Fn() -> Fut>
 /// Creates a test cluster context with in-memory state.
 pub fn test_cluster_context() -> BallistaCluster {
     BallistaCluster::new_memory(
-        TEST_SCHEDULER_NAME,
+        TEST_SCHEDULER_ENDPOINT,
         Arc::new(default_session_builder),
         Arc::new(default_config_producer),
     )
diff --git a/docs/source/upgrading/55.0.0.md b/docs/source/upgrading/55.0.0.md
index 82ff7af67..4b504dafb 100644
--- a/docs/source/upgrading/55.0.0.md
+++ b/docs/source/upgrading/55.0.0.md
@@ -139,6 +139,33 @@ image is bumped to match rather than sitting idle in a ready state.
 
 ### API changes
 
+#### `SchedulerConfig` now carries a scheduler identifier
+
+`SchedulerConfig` has a new `scheduler_id: String` field used as the scheduler's
+unique identity in scheduler state and history event logs. Its autogenerated
+default follows the same UUID-backed instance identity used for executor ids. It
+is stored separately from the scheduler callback endpoint built from
+`external_host` and `bind_port`. `SchedulerConfig::scheduler_name()` is renamed
+to `SchedulerConfig::scheduler_endpoint()`. Code that constructs
+`SchedulerConfig` with a struct literal must provide this field. Prefer the
+existing constructors/builders where possible; use
+`SchedulerConfig::with_scheduler_id(...)` when an embedding needs a stable
+scheduler id. The scheduler CLI accepts `--id`.
+
+`ExecutorProcessConfig` similarly has a new `executor_id: String` field used as
+the executor's unique identity when it registers with the scheduler. The
+executor CLI accepts `--id`; if unset, executor startup generates the same
+UUID-backed instance identity as before. Code that constructs
+`ExecutorProcessConfig` with a struct literal must provide this field or use the
+existing default. Active executors registered with the same scheduler must have
+unique ids; duplicate active ids are rejected and can be reused after the
+previous executor is removed from scheduler state.
+
+The generated protobuf fields
+`LaunchTaskParams.scheduler_id` and `LaunchMultiTaskParams.scheduler_id` are
+renamed to `scheduler_endpoint` because they carry scheduler callback endpoints.
+The protobuf field number remains `2`.
+
 #### Shuffle fetch addresses byte ranges, not just partitions
 
 The shuffle fetch action carried a bool saying whether the producer used the
diff --git a/docs/source/user-guide/configs.md b/docs/source/user-guide/configs.md
index 72dafc54e..55b1ed687 100644
--- a/docs/source/user-guide/configs.md
+++ b/docs/source/user-guide/configs.md
@@ -191,10 +191,11 @@ _Example: Specifying configuration options when starting the scheduler_
 ./ballista-scheduler --scheduler-policy push-staged --event-loop-buffer-size 1000000 --task-distribution round-robin
 ```
 
-| key                                          | type   | default     | description                                                                                                                |
-| -------------------------------------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
-| scheduler-policy                             | Utf8   | pull-staged | Sets the task scheduling policy for the scheduler, possible values: pull-staged, push-staged.                              |
-| event-loop-buffer-size                       | UInt32 | 10000       | Sets the event loop buffer size. for a system of high throughput, a larger value like 1000000 is recommended.              |
-| task-distribution                            | Utf8   | bias        | Sets the task distribution policy for the scheduler, possible values: bias, round-robin                                    |
-| finished-job-data-clean-up-interval-seconds  | UInt64 | 300         | Sets the delayed interval for cleaning up finished job data, mainly the shuffle data, 0 means the cleaning up is disabled. |
-| finished-job-state-clean-up-interval-seconds | UInt64 | 3600        | Sets the delayed interval for cleaning up finished job state stored in the backend, 0 means the cleaning up is disabled.   |
+| key                                          | type   | default        | description                                                                                                                                                                          |
+| -------------------------------------------- | ------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| id                                           | Utf8   | generated UUID | Sets the scheduler identity exposed in scheduler state and history event logs. The default matches executor UUID-backed instance ids. Executor callbacks use the scheduler endpoint. |
+| scheduler-policy                             | Utf8   | pull-staged    | Sets the task scheduling policy for the scheduler, possible values: pull-staged, push-staged.                                                                                        |
+| event-loop-buffer-size                       | UInt32 | 10000          | Sets the event loop buffer size. for a system of high throughput, a larger value like 1000000 is recommended.                                                                        |
+| task-distribution                            | Utf8   | bias           | Sets the task distribution policy for the scheduler, possible values: bias, round-robin                                                                                              |
+| finished-job-data-clean-up-interval-seconds  | UInt64 | 300            | Sets the delayed interval for cleaning up finished job data, mainly the shuffle data, 0 means the cleaning up is disabled.                                                           |
+| finished-job-state-clean-up-interval-seconds | UInt64 | 3600           | Sets the delayed interval for cleaning up finished job state stored in the backend, 0 means the cleaning up is disabled.                                                             |
diff --git a/docs/source/user-guide/history-server.md b/docs/source/user-guide/history-server.md
index 93ba6274e..639529c2a 100644
--- a/docs/source/user-guide/history-server.md
+++ b/docs/source/user-guide/history-server.md
@@ -39,6 +39,20 @@ to:
 ballista-scheduler --event-log-dir /var/lib/ballista/history
 ```
 
+Each `JobStart` event records the unique scheduler id for the scheduler that
+created it. If you do not set an id, the scheduler generates the same
+UUID-backed instance identity used for executor ids at startup; set `--id` when
+you want a stable value for a deployment, test, or local debugging session:
+
+```shell
+ballista-scheduler \
+  --event-log-dir /var/lib/ballista/history \
+  --id scheduler-a
+```
+
+Use unique scheduler ids when collecting event logs from multiple schedulers so
+history records can be attributed to the scheduler that produced them.
+
 The scheduler writes one file per job, in
 [JSON Lines](https://jsonlines.org/) format. While the job runs, records are
 appended to `<job_id>.eventlog.running`; when it reaches a terminal state
diff --git a/docs/source/user-guide/scheduler.md b/docs/source/user-guide/scheduler.md
index 03aa92fc3..c32da1f04 100644
--- a/docs/source/user-guide/scheduler.md
+++ b/docs/source/user-guide/scheduler.md
@@ -19,6 +19,23 @@
 
 # Ballista Scheduler
 
+## Scheduler Identity
+
+Each scheduler has a unique identifier used in cluster state, `/api/state`, and
+history event logs. Set it explicitly with `--id` when you want a stable value;
+otherwise the scheduler generates the same UUID-backed instance identity used
+for executor ids at startup. Use unique scheduler ids when multiple schedulers
+write to shared history or cluster state.
+
+Executor ids follow the same model: each active executor registered with the
+same scheduler needs a unique id. Set it explicitly with `--id` when you want a
+stable value; otherwise the executor generates one at startup. A second active
+executor using an id that is already registered is rejected; the id can be
+reused after the previous executor is removed from scheduler state.
+
+Executors report task status to the scheduler callback endpoint, which is built
+from `--external-host` and `--bind-port`.
+
 ## Fetching Query Results
 
 By default a client fetches the result partitions of a query directly from the executors that
diff --git a/examples/examples/mtls-cluster.rs b/examples/examples/mtls-cluster.rs
index 08c4690b0..eba3d1d1b 100644
--- a/examples/examples/mtls-cluster.rs
+++ b/examples/examples/mtls-cluster.rs
@@ -321,7 +321,7 @@ async fn run_scheduler() -> Result<(), Box<dyn std::error::Error>> {
 
     let mut scheduler: SchedulerServer<LogicalPlanNode, PhysicalPlanNode> =
         SchedulerServer::new(
-            config.scheduler_name(),
+            config.scheduler_endpoint(),
             cluster,
             codec,
             Arc::new(config),


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datafusion.apache.org
For additional commands, e-mail: commits-help@datafusion.apache.org