new: Documented POST /images/upload endpoint

Needed for linode/linode-cli#234

This endpoint is currently in beta, and is not yet available for all
customers.

The CLI needs this endpoint to be documented for the convenience plugin
to build and work correctly, and we do not expect the spec of this
endpoint to change in the future.  I included information about how to
correctly use the endpoint, and how to enroll in the beta, but I am open
to any changes or suggestions.

Author: Dorthu

openapi.yaml

@@ -3471,6 +3471,65 @@ paths:
             --description "A longer description \
               of the image" \
             --disk_id 123
+  /images/upload:
+    x-linode-cli-command: images
+    post:
+      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/Image'
+        default:
+          $ref: '#/components/responses/ErrorResponse'
   /images/{imageId}:
     x-linode-cli-command: images
     parameters: