Better docs

oxidecomputer · Dec 8, 2023 · f15a451 · f15a451
1 parent 501563b
commit f15a451
Show file tree

Hide file tree

Showing 3 changed files with 36 additions and 11 deletions.
diff --git a/nexus/src/external_api/http_entrypoints.rs b/nexus/src/external_api/http_entrypoints.rs
@@ -569,6 +569,8 @@ async fn silo_quotas_view(
 }
 
 /// Update the resource quotas of a given silo
+///
+/// If a quota value is not specified, it will remain unchanged.
 #[endpoint {
     method = PUT,
     path = "/v1/system/silos/{silo}/quotas",

diff --git a/nexus/types/src/external_api/params.rs b/nexus/types/src/external_api/params.rs
@@ -279,7 +279,10 @@ pub struct SiloCreate {
     /// endpoints.  These should be valid for the Silo's DNS name(s).
     pub tls_certificates: Vec<CertificateCreate>,
 
-    /// Initial quotas for the new Silo
+    /// Limits the amount of provisionable CPU, memory, and storage in the Silo.
+    /// CPU and memory are only consumed by running instances, while storage is
+    /// consumed by any disk or snapshot. A value of 0 means that resource is
+    /// *not* provisionable.
     pub quotas: SiloQuotasCreate,
 
     /// Mapping of which Fleet roles are conferred by each Silo role
@@ -291,14 +294,19 @@ pub struct SiloCreate {
         BTreeMap<shared::SiloRole, BTreeSet<shared::FleetRole>>,
 }
 
+/// The amount of provisionable resources for a Silo
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct SiloQuotasCreate {
+    /// The amount of virtual CPUs available for running instances in the Silo
     pub cpus: i64,
+    /// The amount of RAM (in bytes) available for running instances in the Silo
     pub memory: ByteCount,
+    /// The amount of storage (in bytes) available for disks or snapshots
     pub storage: ByteCount,
 }
 
 impl SiloQuotasCreate {
+    /// All quotas set to 0
     pub fn empty() -> Self {
         Self {
             cpus: 0,
@@ -318,10 +326,15 @@ impl SiloQuotasCreate {
     }
 }
 
+/// Updateable properties of a Silo's resource limits.
+/// If a value is omitted it will not be updated.
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct SiloQuotasUpdate {
+    /// The amount of virtual CPUs available for running instances in the Silo
     pub cpus: Option<i64>,
+    /// The amount of RAM (in bytes) available for running instances in the Silo
     pub memory: Option<ByteCount>,
+    /// The amount of storage (in bytes) available for disks or snapshots
     pub storage: Option<ByteCount>,
 }
 

diff --git a/openapi/nexus.json b/openapi/nexus.json
@@ -6410,6 +6410,7 @@
           "system/silos"
         ],
         "summary": "Update the resource quotas of a given silo",
+        "description": "If a quota value is not specified, it will remain unchanged.",
         "operationId": "silo_quotas_update",
         "parameters": [
           {
@@ -13142,7 +13143,7 @@
             "$ref": "#/components/schemas/Name"
           },
           "quotas": {
-            "description": "Initial quotas for the new Silo",
+            "description": "Limits the amount of provisionable CPU, memory, and storage in the Silo. CPU and memory are only consumed by running instances, while storage is consumed by any disk or snapshot. A value of 0 means that resource is *not* provisionable.",
             "allOf": [
               {
                 "$ref": "#/components/schemas/SiloQuotasCreate"
@@ -13211,17 +13212,29 @@
         ]
       },
       "SiloQuotasCreate": {
+        "description": "The amount of provisionable resources for a Silo",
         "type": "object",
         "properties": {
           "cpus": {
+            "description": "The amount of virtual CPUs available for running instances in the Silo",
             "type": "integer",
             "format": "int64"
           },
           "memory": {
-            "$ref": "#/components/schemas/ByteCount"
+            "description": "The amount of RAM (in bytes) available for running instances in the Silo",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ByteCount"
+              }
+            ]
           },
           "storage": {
-            "$ref": "#/components/schemas/ByteCount"
+            "description": "The amount of storage (in bytes) available for disks or snapshots",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ByteCount"
+              }
+            ]
           }
         },
         "required": [
@@ -13252,15 +13265,18 @@
         ]
       },
       "SiloQuotasUpdate": {
+        "description": "Updateable properties of a Silo's resource limits. If a value is omitted it will not be updated.",
         "type": "object",
         "properties": {
           "cpus": {
             "nullable": true,
+            "description": "The amount of virtual CPUs available for running instances in the Silo",
             "type": "integer",
             "format": "int64"
           },
           "memory": {
             "nullable": true,
+            "description": "The amount of RAM (in bytes) available for running instances in the Silo",
             "allOf": [
               {
                 "$ref": "#/components/schemas/ByteCount"
@@ -13269,6 +13285,7 @@
           },
           "storage": {
             "nullable": true,
+            "description": "The amount of storage (in bytes) available for disks or snapshots",
             "allOf": [
               {
                 "$ref": "#/components/schemas/ByteCount"
@@ -15608,13 +15625,6 @@
         "url": "http://docs.oxide.computer/api/system-networking"
       }
     },
-    {
-      "name": "system/quotas",
-      "description": "Quotas set resource allocation limits for a silo allowing operators to control the amount of resources a silo can consume.",
-      "externalDocs": {
-        "url": "http://docs.oxide.computer/api/system-quotas"
-      }
-    },
     {
       "name": "system/silos",
       "description": "Silos represent a logical partition of users and resources.",