Create a new version of StartSledAgentRequest

common/src/ledger.rs

@@ -170,7 +170,7 @@ pub trait Ledgerable: DeserializeOwned + Serialize + Send + Sync {
     async fn read_from(log: &Logger, path: &Utf8Path) -> Result<Self, Error> {
         if path.exists() {
             debug!(log, "Reading ledger from {}", path);
-            serde_json::from_str(
+            <Self as Ledgerable>::deserialize(
                 &tokio::fs::read_to_string(&path)
                     .await
                     .map_err(|err| Error::io_path(&path, err))?,
@@ -200,6 +200,10 @@ pub trait Ledgerable: DeserializeOwned + Serialize + Send + Sync {
             .map_err(|err| Error::io_path(&path, err))?;
         Ok(())
     }
+
+    fn deserialize(s: &str) -> Result<Self, serde_json::Error> {
+        serde_json::from_str(s)
+    }
 }
 
 #[cfg(test)]

schema/rss-sled-plan.json

@@ -588,33 +588,46 @@
       "description": "Configuration information for launching a Sled Agent.",
       "type": "object",
       "required": [
-        "dns_servers",
+        "body",
+        "generation",
+        "schema_version"
+      ],
+      "properties": {
+        "body": {
+          "$ref": "#/definitions/StartSledAgentRequestBody"
+        },
+        "generation": {
+          "description": "The current generation number of data as stored in CRDB.\n\nThe initial generation is set during RSS time and then only mutated by Nexus. For now, we don't actually anticipate mutating this data, but we leave open the possiblity.",
+          "type": "integer",
+          "format": "uint64",
+          "minimum": 0.0
+        },
+        "schema_version": {
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0.0
+        }
+      }
+    },
+    "StartSledAgentRequestBody": {
+      "description": "This is the actual app level data of `StartSledAgentRequest`\n\nWe nest it below the \"header\" of `generation` and `schema_version` so that we can perform partial deserialization of `EarlyNetworkConfig` to only read the header and defer deserialization of the body once we know the schema version. This is possible via the use of [`serde_json::value::RawValue`] in future (post-v1) deserialization paths.",
+      "type": "object",
+      "required": [
         "id",
-        "ntp_servers",
+        "is_lrtq_learner",
         "rack_id",
         "subnet",
         "use_trust_quorum"
       ],
       "properties": {
-        "dns_servers": {
-          "description": "The external DNS servers to use",
-          "type": "array",
-          "items": {
-            "type": "string",
-            "format": "ip"
-          }
-        },
         "id": {
           "description": "Uuid of the Sled Agent to be created.",
           "type": "string",
           "format": "uuid"
         },
-        "ntp_servers": {
-          "description": "The external NTP servers to use",
-          "type": "array",
-          "items": {
-            "type": "string"
-          }
+        "is_lrtq_learner": {
+          "description": "Is this node an LRTQ learner node?\n\nWe only put the node into learner mode if `use_trust_quorum` is also true.",
+          "type": "boolean"
         },
         "rack_id": {
           "description": "Uuid of the rack to which this sled agent belongs.",

schema/persistent-sled-agent-request.json → schema/start-sled-agent-request.json

@@ -1,13 +1,27 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "PersistentSledAgentRequest",
+  "title": "StartSledAgentRequest",
+  "description": "Configuration information for launching a Sled Agent.",
   "type": "object",
   "required": [
-    "request"
+    "body",
+    "generation",
+    "schema_version"
   ],
   "properties": {
-    "request": {
-      "$ref": "#/definitions/StartSledAgentRequest"
+    "body": {
+      "$ref": "#/definitions/StartSledAgentRequestBody"
+    },
+    "generation": {
+      "description": "The current generation number of data as stored in CRDB.\n\nThe initial generation is set during RSS time and then only mutated by Nexus. For now, we don't actually anticipate mutating this data, but we leave open the possiblity.",
+      "type": "integer",
+      "format": "uint64",
+      "minimum": 0.0
+    },
+    "schema_version": {
+      "type": "integer",
+      "format": "uint32",
+      "minimum": 0.0
     }
   },
   "definitions": {
@@ -32,37 +46,25 @@
         }
       }
     },
-    "StartSledAgentRequest": {
-      "description": "Configuration information for launching a Sled Agent.",
+    "StartSledAgentRequestBody": {
+      "description": "This is the actual app level data of `StartSledAgentRequest`\n\nWe nest it below the \"header\" of `generation` and `schema_version` so that we can perform partial deserialization of `EarlyNetworkConfig` to only read the header and defer deserialization of the body once we know the schema version. This is possible via the use of [`serde_json::value::RawValue`] in future (post-v1) deserialization paths.",
       "type": "object",
       "required": [
-        "dns_servers",
         "id",
-        "ntp_servers",
+        "is_lrtq_learner",
         "rack_id",
         "subnet",
         "use_trust_quorum"
       ],
       "properties": {
-        "dns_servers": {
-          "description": "The external DNS servers to use",
-          "type": "array",
-          "items": {
-            "type": "string",
-            "format": "ip"
-          }
-        },
         "id": {
           "description": "Uuid of the Sled Agent to be created.",
           "type": "string",
           "format": "uuid"
         },
-        "ntp_servers": {
-          "description": "The external NTP servers to use",
-          "type": "array",
-          "items": {
-            "type": "string"
-          }
+        "is_lrtq_learner": {
+          "description": "Is this node an LRTQ learner node?\n\nWe only put the node into learner mode if `use_trust_quorum` is also true.",
+          "type": "boolean"
         },
         "rack_id": {
           "description": "Uuid of the rack to which this sled agent belongs.",

sled-agent/src/bootstrap/params.rs

@@ -5,8 +5,10 @@
 //! Request types for the bootstrap agent
 
 use anyhow::{bail, Result};
+use async_trait::async_trait;
 use omicron_common::address::{self, Ipv6Subnet, SLED_PREFIX};
 use omicron_common::api::internal::shared::RackNetworkConfig;
+use omicron_common::ledger::Ledgerable;
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use sha3::{Digest, Sha3_256};
@@ -172,9 +174,9 @@ impl TryFrom<UnvalidatedRackInitializeRequest> for RackInitializeRequest {
 pub type Certificate = nexus_client::types::Certificate;
 pub type RecoverySiloConfig = nexus_client::types::RecoverySiloConfig;
 
-/// Configuration information for launching a Sled Agent.
+/// The version of `StartSledAgentRequest` we originally shipped with.
 #[derive(Clone, Debug, Serialize, Deserialize, PartialEq, JsonSchema)]
-pub struct StartSledAgentRequest {
+pub struct StartSledAgentRequestV0 {
     /// Uuid of the Sled Agent to be created.
     pub id: Uuid,
 
@@ -197,13 +199,62 @@ pub struct StartSledAgentRequest {
     pub subnet: Ipv6Subnet<SLED_PREFIX>,
 }
 
+/// Configuration information for launching a Sled Agent.
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, JsonSchema)]
+pub struct StartSledAgentRequest {
+    /// The current generation number of data as stored in CRDB.
+    ///
+    /// The initial generation is set during RSS time and then only mutated
+    /// by Nexus. For now, we don't actually anticipate mutating this data,
+    /// but we leave open the possiblity.
+    pub generation: u64,
+
+    // Which version of the data structure do we have. This is to help with
+    // deserialization and conversion in future updates.
+    pub schema_version: u32,
+
+    // The actual configuration details
+    pub body: StartSledAgentRequestBody,
+}
+
+/// This is the actual app level data of `StartSledAgentRequest`
+///
+/// We nest it below the "header" of `generation` and `schema_version` so that
+/// we can perform partial deserialization of `EarlyNetworkConfig` to only read
+/// the header and defer deserialization of the body once we know the schema
+/// version. This is possible via the use of [`serde_json::value::RawValue`] in
+/// future (post-v1) deserialization paths.
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, JsonSchema)]
+pub struct StartSledAgentRequestBody {
+    /// Uuid of the Sled Agent to be created.
+    pub id: Uuid,
+
+    /// Uuid of the rack to which this sled agent belongs.
+    pub rack_id: Uuid,
+
+    /// Use trust quorum for key generation
+    pub use_trust_quorum: bool,
+
+    /// Is this node an LRTQ learner node?
+    ///
+    /// We only put the node into learner mode if `use_trust_quorum` is also
+    /// true.
+    pub is_lrtq_learner: bool,
+
+    // Note: The order of these fields is load bearing, because we serialize
+    // `SledAgentRequest`s as toml. `subnet` serializes as a TOML table, so it
+    // must come after non-table fields.
+    /// Portion of the IP space to be managed by the Sled Agent.
+    pub subnet: Ipv6Subnet<SLED_PREFIX>,
+}
+
 impl StartSledAgentRequest {
     pub fn sled_address(&self) -> SocketAddrV6 {
-        address::get_sled_address(self.subnet)
+        address::get_sled_address(self.body.subnet)
     }
 
     pub fn switch_zone_ip(&self) -> Ipv6Addr {
-        address::get_switch_zone_address(self.subnet)
+        address::get_switch_zone_address(self.body.subnet)
     }
 
     /// Compute the sha3_256 digest of `self.rack_id` to use as a `salt`
@@ -212,7 +263,57 @@ impl StartSledAgentRequest {
     /// between sleds.
     pub fn hash_rack_id(&self) -> [u8; 32] {
         // We know the unwrap succeeds as a Sha3_256 digest is 32 bytes
-        Sha3_256::digest(self.rack_id.as_bytes()).as_slice().try_into().unwrap()
+        Sha3_256::digest(self.body.rack_id.as_bytes())
+            .as_slice()
+            .try_into()
+            .unwrap()
+    }
+}
+
+impl From<StartSledAgentRequestV0> for StartSledAgentRequest {
+    fn from(v0: StartSledAgentRequestV0) -> Self {
+        StartSledAgentRequest {
+            generation: 0,
+            schema_version: 1,
+            body: StartSledAgentRequestBody {
+                id: v0.id,
+                rack_id: v0.rack_id,
+                use_trust_quorum: v0.use_trust_quorum,
+                is_lrtq_learner: false,
+                subnet: v0.subnet,
+            },
+        }
+    }
+}
+
+#[async_trait]
+impl Ledgerable for StartSledAgentRequest {
+    fn is_newer_than(&self, other: &Self) -> bool {
+        self.generation > other.generation
+    }
+
+    fn generation_bump(&mut self) {
+        // DO NOTHING!
+        //
+        // Generation bumps must only ever come from nexus and will be encoded
+        // in the struct itself
+    }
+
+    // Attempt to deserialize the v1 or v0 version and return
+    // the v1 version.
+    fn deserialize(
+        s: &str,
+    ) -> Result<StartSledAgentRequest, serde_json::Error> {
+        // Try to deserialize the latest version of the data structure (v1). If
+        // that succeeds we are done.
+        if let Ok(val) = serde_json::from_str::<StartSledAgentRequest>(s) {
+            return Ok(val);
+        }
+
+        // We don't have the latest version. Try to deserialize v0 and then
+        // convert it to the latest version.
+        let v0 = serde_json::from_str::<StartSledAgentRequestV0>(s)?;
+        Ok(v0.into())
     }
 }
 
@@ -291,12 +392,15 @@ mod tests {
             version: 1,
             request: Request::StartSledAgentRequest(Cow::Owned(
                 StartSledAgentRequest {
-                    id: Uuid::new_v4(),
-                    rack_id: Uuid::new_v4(),
-                    ntp_servers: vec![String::from("test.pool.example.com")],
-                    dns_servers: vec!["1.1.1.1".parse().unwrap()],
-                    use_trust_quorum: false,
-                    subnet: Ipv6Subnet::new(Ipv6Addr::LOCALHOST),
+                    generation: 0,
+                    schema_version: 1,
+                    body: StartSledAgentRequestBody {
+                        id: Uuid::new_v4(),
+                        rack_id: Uuid::new_v4(),
+                        use_trust_quorum: false,
+                        is_lrtq_learner: false,
+                        subnet: Ipv6Subnet::new(Ipv6Addr::LOCALHOST),
+                    },
                 },
             )),
         };
@@ -308,6 +412,34 @@ mod tests {
         assert!(envelope == deserialized, "serialization round trip failed");
     }
 
+    #[test]
+    fn serialize_start_sled_agent_v0_deserialize_v1() {
+        let v0 = StartSledAgentRequestV0 {
+            id: Uuid::new_v4(),
+            rack_id: Uuid::new_v4(),
+            ntp_servers: vec![String::from("test.pool.example.com")],
+            dns_servers: vec!["1.1.1.1".parse().unwrap()],
+            use_trust_quorum: false,
+            subnet: Ipv6Subnet::new(Ipv6Addr::LOCALHOST),
+        };
+        let serialized = serde_json::to_string(&v0).unwrap();
+        let expected = StartSledAgentRequest {
+            generation: 0,
+            schema_version: 1,
+            body: StartSledAgentRequestBody {
+                id: v0.id,
+                rack_id: v0.rack_id,
+                use_trust_quorum: false,
+                is_lrtq_learner: false,
+                subnet: v0.subnet,
+            },
+        };
+
+        let actual: StartSledAgentRequest =
+            Ledgerable::deserialize(&serialized).unwrap();
+        assert_eq!(expected, actual);
+    }
+
     #[test]
     fn validate_external_dns_ips_must_be_in_internal_services_ip_pools() {
         // Conjure up a config; we'll tweak the internal services pools and