Add support for serial-over-ssh to vms

components/schemas/vms/sos/VirtualMachineSosConnection.yml

@@ -0,0 +1,16 @@
+title: VirtualMachineSosConnection
+type: object
+description: Connection details for connecting to a virtual machine using serial-over-SSH.
+required:
+  - token
+  - secret
+  - address
+properties:
+  token:
+    $ref: VirtualMachineSosToken.yml
+  secret:
+    type: string
+    description: The secret used to connect.
+  address:
+    type: string
+    description: The serial-over-SSH connection address.

components/schemas/vms/sos/VirtualMachineSosToken.yml

@@ -0,0 +1,41 @@
+title: VirtualMachineSosToken
+type: object
+description: A token used to connect to a virtual machine using serial-over-SSH.
+required:
+  - id
+  - virtual_machine_id
+  - hub_id
+  - creator
+  - events
+  - valid
+properties:
+  id:
+    "$ref": "../../ID.yml"
+  virtual_machine_id:
+    type: string
+    description: The ID of the virtual machine being connected to.
+  hub_id:
+    "$ref": "../../HubID.yml"
+  creator:
+    "$ref": "../../creators/CreatorScope.yml"
+  events:
+    title: SSHTokenEvents
+    type: object
+    description: A collection of timestamps for each event in the serial-over-SSH token's lifetime.
+    required:
+      - created
+      - used
+      - expires
+    properties:
+      created:
+        description: The timestamp of when the serial-over-SSH token was created.
+        "$ref": "../../DateTime.yml"
+      used:
+        description: The timestamp of when the serial-over-SSH token was used.
+        "$ref": "../../DateTime.yml"
+      expires:
+        description: The timestamp of when the serial-over-SSH token expires.
+        "$ref": "../../DateTime.yml"
+  valid:
+    type: boolean
+    description: A boolean where true represents the token as being a valid token to be used for connection.

platform/api.yml

@@ -695,6 +695,8 @@ paths:
     $ref: "./paths/virtual-machines/tasks.yml"
   "/v1/virtual-machines/images/base":
     $ref: "./paths/virtual-machines/images/base.yml"
+  "/v1/virtual-machines/{virtualMachineId}/sos":
+    $ref: paths/virtual-machines/sos/sos.yml
 
   # --Utility
   "/v1/utils/resource/lookup":

platform/paths/virtual-machines/sos/sos.yml

@@ -0,0 +1,69 @@
+get:
+  operationId: "generateVirtualMachineSosCredentials"
+  summary: Generate Virtual Machine Serial-Over-SSH Credentials
+  description: |
+    Generates credentials for connecting to the serial console of a virtual machine via SSH.
+
+    Requires the `virtual-machines-console` capability.
+  tags:
+    - Virtual Machines
+  parameters:
+    - name: virtualMachineId
+      description: The ID of the virtual machine.
+      in: path
+      required: true
+      schema:
+        type: string
+  responses:
+    200:
+      description: Returns a serial-over-sos connection response.
+      content:
+        application/json:
+          schema:
+            type: object
+            required:
+              - data
+            properties:
+              data:
+                $ref: ../../../../components/schemas/vms/sos/VirtualMachineSosConnection.yml
+    default:
+      $ref: ../../../../components/responses/errors/DefaultError.yml
+
+delete:
+  operationId: "expireVirtualMachineSosCredentials"
+  tags:
+    - Virtual Machines
+  parameters:
+    - name: virtualMachineId
+      description: The ID of the virtual machine.
+      in: path
+      required: true
+      schema:
+        type: string
+  summary: Expire Serial-Over-SSH Credentials
+  description: |
+    Instantly expires any serial-over-SSH credentials generated for this virtual machine.
+
+    Requires the `virtual-machines-console` capability.
+  responses:
+    200:
+      description: Returns the number of tokens removed.
+      content:
+        application/json:
+          schema:
+            title: ExpireSSHTokenResponse
+            type: object
+            required:
+              - data
+            properties:
+              data:
+                type: object
+                description: The number of tokens expired.
+                required:
+                  - tokens
+                properties:
+                  tokens:
+                    type: integer
+                    description: The number of tokens expired.
+    default:
+      $ref: ../../../../components/responses/errors/DefaultError.yml