[1/n][Release] Renames and configuration updates

Summary:
This renames a few configuration and command line arguments while keeping compatibility with old options. This also introduces extra documentation on those configuration keys

- `allow-bootstrap` -> `auto-provision`
- `bootstrap-num-partitions` -> `default-num-partitions` (aligns with `default-partition-replication`)
- `[bifrost.replicated-loglet] default_replication-property` -> `default_log_replication`

benchmarks/src/lib.rs

@@ -127,7 +127,7 @@ pub fn flamegraph_options<'a>() -> Options<'a> {
 pub fn restate_configuration() -> Configuration {
     let common_options = CommonOptionsBuilder::default()
         .base_dir(tempfile::tempdir().expect("tempdir failed").into_path())
-        .bootstrap_num_partitions(NonZeroU16::new(10).unwrap())
+        .default_num_partitions(NonZeroU16::new(10).unwrap())
         .build()
         .expect("building common options should work");
 

crates/local-cluster-runner/examples/three_nodes.rs

@@ -35,7 +35,7 @@ async fn main() -> anyhow::Result<()> {
     let mut base_config = Configuration::default();
     base_config.common.log_format = LogFormat::Compact;
     base_config.common.log_filter = "warn,restate=debug".to_string();
-    base_config.common.bootstrap_num_partitions = NonZeroU16::new(4).unwrap();
+    base_config.common.default_num_partitions = NonZeroU16::new(4).unwrap();
     base_config.bifrost.default_provider = Replicated;
 
     let nodes = Node::new_test_nodes(

crates/local-cluster-runner/src/node/mod.rs

@@ -181,7 +181,7 @@ impl Node {
     ) -> Vec<Self> {
         let mut nodes = Vec::with_capacity(usize::try_from(size).expect("u32 to fit into usize"));
 
-        base_config.common.allow_bootstrap = false;
+        base_config.common.auto_provision = false;
         base_config.common.log_disable_ansi_codes = true;
         if !matches!(
             base_config.metadata_server.kind,
@@ -197,7 +197,7 @@ impl Node {
 
             if auto_provision && node_id == 1 {
                 // the first node will be responsible for bootstrapping the cluster
-                effective_config.common.allow_bootstrap = true;
+                effective_config.common.auto_provision = true;
             }
 
             // Create a separate ingress role when running a worker

crates/node/src/lib.rs

@@ -358,7 +358,7 @@ impl Node {
             )?;
         }
 
-        if config.common.allow_bootstrap {
+        if config.common.auto_provision {
             TaskCenter::spawn(TaskKind::SystemBoot, "auto-provision-cluster", {
                 let cluster_configuration = ClusterConfiguration::from_configuration(&config);
                 let metadata_store_client = self.metadata_store_client.clone();
@@ -544,7 +544,7 @@ fn num_partitions_to_u32(num_partitions: NonZeroU16) -> u32 {
 impl ClusterConfiguration {
     pub fn from_configuration(configuration: &Configuration) -> Self {
         ClusterConfiguration {
-            num_partitions: configuration.common.bootstrap_num_partitions,
+            num_partitions: configuration.common.default_num_partitions,
             partition_replication: configuration.admin.default_partition_replication.clone(),
             bifrost_provider: ProviderConfiguration::from_configuration(configuration),
         }

crates/node/src/network_server/grpc_svc_handler.rs

@@ -77,7 +77,7 @@ impl NodeCtlSvcHandler {
                     })
             })
             .transpose()?
-            .unwrap_or(config.common.bootstrap_num_partitions);
+            .unwrap_or(config.common.default_num_partitions);
         let partition_replication = request.partition_replication.try_into()?;
 
         let log_provider = request
@@ -98,7 +98,7 @@ impl NodeCtlSvcHandler {
                 config
                     .bifrost
                     .replicated_loglet
-                    .default_replication_property
+                    .default_log_replication
                     .clone()
             });
 

crates/types/src/config/admin.rs

@@ -67,10 +67,16 @@ pub struct AdminOptions {
     #[cfg_attr(feature = "schemars", schemars(with = "String"))]
     pub log_tail_update_interval: humantime::Duration,
 
-    /// # Default partition replication strategy
+    /// # Default partition replication factor
     ///
-    /// The default partition replication strategy to be used by the cluster controller to place partition
-    /// processors.
+    /// [__PREVIEW FEATURE__]
+    /// The default replication factor for partition processors, this impacts how many replicas
+    /// each partition will have across the worker nodes of the cluster.
+    ///
+    /// Note that this value only impacts the cluster initial provisioning and will not be respected after
+    /// the cluster has been provisioned.
+    ///
+    /// For provisioned clusters, use the `restatectl` utility to update it.
     #[cfg_attr(feature = "schemars", schemars(with = "String"))]
     pub default_partition_replication: PartitionReplication,
 

crates/types/src/config/bifrost.rs

@@ -284,23 +284,32 @@ pub struct ReplicatedLogletOptions {
     /// Value must be between 0 and 1. It will be clamped at `1.0`.
     pub readahead_trigger_ratio: f32,
 
-    /// # Default replication property
+    /// # Default log replication factor
     ///
-    /// Configures the default replication property to be used by the replicated loglet.
+    /// [__PREVIEW FEATURE__]
+    /// Configures the default replication factor to be used by the replicated loglets.
+    ///
+    /// Note that this value only impacts the cluster initial provisioning and will not be respected after
+    /// the cluster has been provisioned.
+    /// For provisioned clusters, use the `restatectl` utility to update it.
     // Also allow to specify the replication property as non-zero u8 value to make it simpler to
     // pass it in via an env variable.
     #[serde_as(
         as = "serde_with::PickFirst<(serde_with::DisplayFromStr, ReplicationPropertyFromNonZeroU8)>"
     )]
-    #[serde(default = "default_replication_property")]
+    #[serde(default = "default_log_replication")]
     #[cfg_attr(feature = "schemars", schemars(with = "String"))]
-    pub default_replication_property: ReplicationProperty,
+    pub default_log_replication: ReplicationProperty,
 
     /// # Default nodeset size
     ///
+    /// [__PREVIEW FEATURE__]
     /// Configures the target nodeset size used by the replicated loglet when generating new
     /// nodesets for logs. Setting this to 0 will let the system choose a reasonable value based on
     /// the effective replication_property at the time of logs reconfiguration.
+    ///
+    /// Note that this value only impacts the cluster initial provisioning and will not be respected after
+    /// the cluster has been provisioned.
     // hide the configuration option from serialization if it is the default
     #[serde(default, skip_serializing_if = "nodeset_size_is_zero")]
     // hide the configuration option by excluding it from the Json schema
@@ -324,7 +333,7 @@ fn nodeset_size_is_zero(i: &NodeSetSize) -> bool {
     *i == NodeSetSize::ZERO
 }
 
-fn default_replication_property() -> ReplicationProperty {
+fn default_log_replication() -> ReplicationProperty {
     ReplicationProperty::new(NonZeroU8::new(1).expect("to be non-zero"))
 }
 
@@ -349,8 +358,8 @@ impl Default for ReplicatedLogletOptions {
             ),
             readahead_records: NonZeroUsize::new(100).unwrap(),
             readahead_trigger_ratio: 0.5,
-            default_replication_property: default_replication_property(),
             default_nodeset_size: NodeSetSize::default(),
+            default_log_replication: default_log_replication(),
         }
     }
 }

crates/types/src/config/cli_option_overrides.rs

@@ -44,6 +44,7 @@ pub struct CommonOptionCliOverride {
 
     /// Node location
     ///
+    /// [PREVIEW FEATURE]
     /// Setting the location allows Restate to form a tree-like cluster topology.
     /// The value is written in the format of "<region>[.zone]" to assign this node
     /// to a specific region, or to a zone within a region.
@@ -74,10 +75,21 @@ pub struct CommonOptionCliOverride {
     #[clap(long, env = "RESTATE_CLUSTER_NAME", global = true)]
     pub cluster_name: Option<String>,
 
-    /// If true, then a new cluster is bootstrapped. This node *must* have an admin
-    /// role and a new nodes configuration will be created that includes this node.
-    #[clap(long, global = true)]
-    pub allow_bootstrap: Option<bool>,
+    /// Auto Cluster Provisioning
+    ///
+    /// If true, then this node is allowed to automatically provision as a new cluster.
+    /// This node *must* have an admin role and a new nodes configuration will be created that includes this node.
+    ///
+    /// auto-provision is allowed by default in development mode and is disabled if restate-server runs with `--production` flag
+    /// to prevent cluster nodes from forming their own clusters, rather than forming a single cluster.
+    ///
+    /// Use `restatectl` to provision the cluster/node if automatic provisioning is disabled.
+    ///
+    /// This can also be explicitly disabled by setting this value to false.
+    ///
+    /// Default: true
+    #[clap(long, global = true, alias = "allow_bootstrap")]
+    pub auto_provision: Option<bool>,
 
     /// The working directory which this Restate node should use for relative paths. The default is
     /// `restate-data` under the current working directory.
@@ -97,24 +109,21 @@ pub struct CommonOptionCliOverride {
     #[clap(long, global = true)]
     pub advertise_address: Option<AdvertisedAddress>,
 
-    /// # Partitions
+    /// Default Number Of Partitions
+    ///
+    /// Number of partitions that will be provisioned during initial cluster provisioning.
+    /// partitions are the logical shards used to process messages. Default is 24.
     ///
-    /// Number of partitions that will be provisioned during cluster bootstrap,
-    /// partitions used to process messages.
+    /// Cannot be higher than `65535` (You should almost never need as many partitions anyway)
     ///
-    /// NOTE: This config entry only impacts the initial number of partitions, the
+    /// NOTE 1: This config entry only impacts the initial number of partitions, the
     /// value of this entry is ignored for bootstrapped nodes/clusters.
     ///
-    /// Cannot be higher than `4611686018427387903` (You should almost never need as many partitions anyway)
-    #[clap(long, global = true)]
-    pub bootstrap_num_partitions: Option<NonZeroU64>,
-
-    /// # Automatically provision number of configured partitions
+    /// NOTE 2: This will be renamed to `default-num-partitions` by default as of v1.3+
     ///
-    /// If this option is set to `false`, then one needs to manually write a partition table to
-    /// the metadata store. Without a partition table, the cluster will not start.
-    #[clap(long, global = true)]
-    pub auto_provision_partitions: Option<bool>,
+    /// Default: 24
+    #[clap(long, global = true, alias = "bootstrap-num-partitions")]
+    pub default_num_partitions: Option<NonZeroU64>,
 
     /// This timeout is used when shutting down the various Restate components to drain all the internal queues.
     #[serde_as(as = "Option<serde_with::DisplayFromStr>")]
@@ -153,7 +162,7 @@ pub struct CommonOptionCliOverride {
     #[clap(long, env = "RESTATE_TRACING_SERVICES_ENDPOINT", global = true)]
     pub tracing_services_endpoint: Option<String>,
 
-    /// # Distributed Tracing JSON Export Path
+    /// Distributed Tracing JSON Export Path
     ///
     /// If set, an exporter will be configured to write traces to files using the Jaeger JSON format.
     /// Each trace file will start with the `trace` prefix.
@@ -166,27 +175,27 @@ pub struct CommonOptionCliOverride {
     #[clap(long, global = true)]
     pub tracing_json_path: Option<PathBuf>,
 
-    /// # Tracing Filter
+    /// Tracing Filter
     ///
     /// Distributed tracing exporter filter.
     /// Check the [`RUST_LOG` documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html) for more details how to configure it.
     #[clap(long, global = true)]
     pub tracing_filter: Option<String>,
 
-    /// # Logging Filter
+    /// Logging Filter
     ///
     /// Log filter configuration. Can be overridden by the `RUST_LOG` environment variable.
     /// Check the [`RUST_LOG` documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html) for more details how to configure it.
     #[clap(long, global = true)]
     pub log_filter: Option<String>,
 
-    /// # Logging format
+    /// Logging format
     ///
     /// Format to use when logging.
     #[clap(long, global = true)]
     pub log_format: Option<LogFormat>,
 
-    /// # Disable ANSI in log output
+    /// Disable ANSI in log output
     ///
     /// Disable ANSI terminal codes for logs. This is useful when the log collector doesn't support processing ANSI terminal codes.
     #[clap(long, global = true)]

crates/types/src/config/common.rs

@@ -55,6 +55,7 @@ pub struct CommonOptions {
 
     /// # Node Location
     ///
+    /// [PREVIEW FEATURE]
     /// Setting the location allows Restate to form a tree-like cluster topology.
     /// The value is written in the format of "<region>[.zone]" to assign this node
     /// to a specific region, or to a zone within a region.
@@ -81,19 +82,27 @@ pub struct CommonOptions {
     /// If set, the node insists on acquiring this node ID.
     pub force_node_id: Option<PlainNodeId>,
 
-    /// # Cluster Name
+    /// # Cluster name
     ///
     /// A unique identifier for the cluster. All nodes in the same cluster should
     /// have the same.
     cluster_name: String,
 
-    /// If true, then a new cluster is bootstrapped. This node *must* have an admin
-    /// role and a new nodes configuration will be created that includes this node.
+    /// # Auto cluster provisioning
     ///
-    /// Bootstrap is allowed by default, unless it is explicitly disabled in config files.
+    /// If true, then this node is allowed to automatically provision as a new cluster.
+    /// This node *must* have an admin role and a new nodes configuration will be created that includes this node.
+    ///
+    /// auto-provision is allowed by default in development mode and is disabled if restate-server runs with `--production` flag
+    /// to prevent cluster nodes from forming their own clusters, rather than forming a single cluster.
+    ///
+    /// Use `restatectl` to provision the cluster/node if automatic provisioning is disabled.
+    ///
+    /// This can also be explicitly disabled by setting this value to false.
     ///
     /// Default: true
-    pub allow_bootstrap: bool,
+    #[serde(alias = "allow-bootstrap")]
+    pub auto_provision: bool,
 
     /// The working directory which this Restate node should use for relative paths. The default is
     /// `restate-data` under the current working directory.
@@ -115,14 +124,20 @@ pub struct CommonOptions {
 
     /// # Partitions
     ///
-    /// Number of partitions that will be provisioned during cluster bootstrap,
-    /// partitions used to process messages.
-    ///
-    /// NOTE: This config entry only impacts the initial number of partitions, the
-    /// value of this entry is ignored for bootstrapped nodes/clusters.
+    /// Number of partitions that will be provisioned during initial cluster provisioning.
+    /// partitions are the logical shards used to process messages.
     ///
     /// Cannot be higher than `65535` (You should almost never need as many partitions anyway)
-    pub bootstrap_num_partitions: NonZeroU16,
+    ///
+    /// NOTE 1: This config entry only impacts the initial number of partitions, the
+    /// value of this entry is ignored for provisioned nodes/clusters.
+    ///
+    /// NOTE 2: This will be renamed to `default-num-partitions` by default as of v1.3+
+    ///
+    /// Default: 24
+    // todo switch to serializing as "default_num_partitions" in version 1.3
+    #[serde(alias = "bootstrap-num-partitions")]
+    pub default_num_partitions: NonZeroU16,
 
     /// # Shutdown grace timeout
     ///
@@ -394,12 +409,12 @@ impl Default for CommonOptions {
             // boot strap the cluster by default. This is very likely to change in the future to be
             // false by default. For now, this is true to make the converged deployment backward
             // compatible and easy for users.
-            allow_bootstrap: true,
+            auto_provision: true,
             base_dir: None,
             metadata_store_client: MetadataStoreClientOptions::default(),
             bind_address: None,
             advertised_address: AdvertisedAddress::from_str(DEFAULT_ADVERTISED_ADDRESS).unwrap(),
-            bootstrap_num_partitions: NonZeroU16::new(24).expect("is not zero"),
+            default_num_partitions: NonZeroU16::new(24).expect("is not zero"),
             histogram_inactivity_timeout: None,
             disable_prometheus: false,
             service_client: Default::default(),

crates/types/src/config/mod.rs

@@ -59,7 +59,7 @@ use crate::nodes_config::Role;
 pub static PRODUCTION_PROFILE_DEFAULTS: LazyLock<Configuration> = LazyLock::new(|| {
     let mut default = Configuration::default();
 
-    default.common.allow_bootstrap = false;
+    default.common.auto_provision = false;
 
     default
 });

crates/types/src/config/worker.rs

@@ -295,7 +295,7 @@ impl StorageOptions {
     pub fn apply_common(&mut self, common: &CommonOptions) {
         self.rocksdb.apply_common(&common.rocksdb);
         if self.num_partitions_to_share_memory_budget.is_none() {
-            self.num_partitions_to_share_memory_budget = Some(common.bootstrap_num_partitions)
+            self.num_partitions_to_share_memory_budget = Some(common.default_num_partitions)
         }
 
         // todo: move to a shared struct and deduplicate

crates/types/src/logs/metadata.rs

@@ -141,7 +141,7 @@ impl ProviderConfiguration {
             configuration
                 .bifrost
                 .replicated_loglet
-                .default_replication_property
+                .default_log_replication
                 .clone(),
             configuration.bifrost.replicated_loglet.default_nodeset_size,
         ))
@@ -496,9 +496,11 @@ pub enum ProviderKind {
     Local,
     /// An in-memory loglet, primarily for testing.
     #[cfg(any(test, feature = "memory-loglet"))]
+    #[cfg_attr(feature = "schemars", schemars(skip))]
     InMemory,
-    /// Replicated loglet implementation. This requires log-server role to run on
-    /// enough nodes in the cluster.
+    /// [__PREVIEW FEATURE__]
+    /// Replicated loglets are restate's native log replication system. This requires
+    /// `log-server` role to run on enough nodes in the cluster.
     Replicated,
 }
 

crates/types/src/nodes_config.rs

@@ -51,7 +51,7 @@ pub enum Role {
     // todo switch to serializing as "metadata-server" in version 1.3
     #[serde(rename(serialize = "metadata-store"))]
     MetadataServer,
-    /// [IN DEVELOPMENT] Serves a log server for replicated loglets
+    /// [PREVIEW FEATURE] Serves a log-server for replicated loglets
     LogServer,
     HttpIngress,
 }