Merge pull request #425 from linode/feature/image-upload

new: Documented POST /images/upload endpoint

Author: bbiggerr

openapi.yaml

@@ -3471,6 +3471,68 @@ paths:
             --description "A longer description \
               of the image" \
             --disk_id 123
+  /images/upload:
+    x-linode-cli-command: images
+    post:
+      servers:
+      - url: https://api.linode.com/v4beta
+      tags:
+      - Images
+      summary: Upload Image
+      description: >
+        Initiates a Machine Image upload.
+
+        This endpoint creates a new private Image object and returns it, along
+        with the URL the image data should be uploaded to.  Images must be uploaded
+        within 24 hours of creation or the upload will be cancelled.  Image uploads
+        should be made as an HTTP PUT request to the returned URL, with a
+        `Content-type: application/octet-stream` header included in the request.
+        Uploaded image data should be in gzip format.  A maximum file size of
+        5GB is supported for upload at this time.
+
+        *NOTE* This endpoint is currently in beta, and is only available to users
+        who are a part of the beta.  You may see a 404 error returned from this
+        endpoint if you are not currently enrolled - open a support ticket to
+        sign up to join the beta when space becomes available.
+      x-linode-cli-action: upload
+      security:
+      - personalAccessToken: []
+      - oauth:
+        - images:read_write
+      requestBody:
+        description: The data
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                region:
+                  type: string
+                  description: The region to upload to.
+                  example: eu-central
+                label:
+                  type: string
+                  description: Label for the new image.
+                  example: my-image-label
+                description:
+                  type: string
+                  description: Description for the image.
+                  example: This is an example image in the docs.
+      responses:
+        '200':
+          description: The new image and upload url.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  upload_url:
+                    type: string
+                    description: The URL to upload the image to.
+                  image:
+                    $ref: '#/components/schemas/ImagePrivate'
+        default:
+          $ref: '#/components/responses/ErrorResponse'
   /images/{imageId}:
     x-linode-cli-command: images
     parameters:
@@ -17277,6 +17339,20 @@ components:
           x-linode-cli-color:
             None: black
             default_: white
+        status:
+          x-linode-cli-display: 7
+          type: string
+          enum:
+          - creating
+          - pending_upload
+          - available
+          description: |
+            The current status of this Image.  Only images in an "available" status
+            can be deployed.  Images in a "creating" status are being created from
+            a Linode Disk, and will become "available" shortly.  Images in a
+            "pending_upload" status are waiting for data to be uploaded for the
+            image, and will become "available" after the upload is complete and
+            processing occurs.
     ImagePublic:
       type: object
       description: Public Image object
@@ -17380,6 +17456,16 @@ components:
           x-linode-cli-color:
             None: black
             default_: white
+        status:
+          x-linode-cli-display: 7
+          type: string
+          enum:
+          - creating
+          - pending_upload
+          - available
+          description: |
+            The current status of this Image.  Only images in an "available" status
+            can be deployed.
     LinodeConfigInterface:
       type: object
       description: >