Update the docs, api spec

oxidecomputer · Jan 25, 2024 · d47d948 · d47d948
1 parent ef14c4d
commit d47d948
Show file tree

Hide file tree

Showing 4 changed files with 89 additions and 4 deletions.
diff --git a/nexus/src/external_api/http_entrypoints.rs b/nexus/src/external_api/http_entrypoints.rs
@@ -2667,6 +2667,10 @@ async fn instance_serial_console_stream(
     }
 }
 
+/// List the SSH public keys sent to the instance via cloud-init during instance creation
+///
+/// Note that this list is a snapshot in time and will not reflect updates made after
+/// the instance is created.
 #[endpoint {
     method = GET,
     path = "/v1/instances/{instance}/ssh-public-keys",

diff --git a/nexus/tests/output/nexus_tags.txt b/nexus/tests/output/nexus_tags.txt
@@ -55,6 +55,7 @@ instance_network_interface_view          GET      /v1/network-interfaces/{interf
 instance_reboot                          POST     /v1/instances/{instance}/reboot
 instance_serial_console                  GET      /v1/instances/{instance}/serial-console
 instance_serial_console_stream           GET      /v1/instances/{instance}/serial-console/stream
+instance_ssh_public_key_list             GET      /v1/instances/{instance}/ssh-public-keys
 instance_start                           POST     /v1/instances/{instance}/start
 instance_stop                            POST     /v1/instances/{instance}/stop
 instance_view                            GET      /v1/instances/{instance}

diff --git a/nexus/types/src/external_api/params.rs b/nexus/types/src/external_api/params.rs
@@ -1036,9 +1036,12 @@ pub struct InstanceCreate {
     #[serde(default)]
     pub disks: Vec<InstanceDiskAttachment>,
 
-    /// List of public SSH keys (identified by ID or name) to be associated with the instance.
-    /// If not provided, all public keys from the user's profile will be used. If an empty list is
-    /// provided, no public keys will be transmitted to the instance.
+    /// An allowlist of SSH public keys to be transferred to the instance via
+    /// cloud-init during instance creation.
+    ///
+    /// If not provided, all SSH public keys from the user's profile will be sent.
+    /// If an empty list is provided, no public keys will be transmitted to the
+    /// instance.
     pub ssh_keys: Option<Vec<NameOrId>>,
 
     /// Should this instance be started upon creation; true by default.

diff --git a/openapi/nexus.json b/openapi/nexus.json
@@ -2252,6 +2252,83 @@
         "x-dropshot-websocket": {}
       }
     },
+    "/v1/instances/{instance}/ssh-public-keys": {
+      "get": {
+        "tags": [
+          "instances"
+        ],
+        "summary": "List the SSH public keys sent to the instance via cloud-init during instance creation",
+        "description": "Note that this list is a snapshot in time and will not reflect updates made after the instance is created.",
+        "operationId": "instance_ssh_public_key_list",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "instance",
+            "description": "Name or ID of the instance",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/NameOrId"
+            }
+          },
+          {
+            "in": "query",
+            "name": "limit",
+            "description": "Maximum number of items returned by a single call",
+            "schema": {
+              "nullable": true,
+              "type": "integer",
+              "format": "uint32",
+              "minimum": 1
+            }
+          },
+          {
+            "in": "query",
+            "name": "page_token",
+            "description": "Token returned by previous call to retrieve the subsequent page",
+            "schema": {
+              "nullable": true,
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "project",
+            "description": "Name or ID of the project",
+            "schema": {
+              "$ref": "#/components/schemas/NameOrId"
+            }
+          },
+          {
+            "in": "query",
+            "name": "sort_by",
+            "schema": {
+              "$ref": "#/components/schemas/NameOrIdSortMode"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SshKeyResultsPage"
+                }
+              }
+            }
+          },
+          "4XX": {
+            "$ref": "#/components/responses/Error"
+          },
+          "5XX": {
+            "$ref": "#/components/responses/Error"
+          }
+        },
+        "x-dropshot-pagination": {
+          "required": []
+        }
+      }
+    },
     "/v1/instances/{instance}/start": {
       "post": {
         "tags": [
@@ -12355,7 +12432,7 @@
           },
           "ssh_keys": {
             "nullable": true,
-            "description": "List of public SSH keys (identified by ID or name) to be associated with the instance. If not provided, all public keys from the user's profile will be used. If an empty list is provided, no public keys will be transmitted to the instance.",
+            "description": "An allowlist of SSH public keys to be transferred to the instance via cloud-init during instance creation.\n\nIf not provided, all SSH public keys from the user's profile will be sent. If an empty list is provided, no public keys will be transmitted to the instance.",
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/NameOrId"