From c5ab7204a4468b7f25370a5e68688c6c11f5fb14 Mon Sep 17 00:00:00 2001 From: Will Smith Date: Tue, 20 Apr 2021 08:03:23 -0400 Subject: [PATCH 1/4] new: Documented POST /images/upload endpoint Needed for https://github.com/linode/linode-cli/pull/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. --- openapi.yaml | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 926a2f034..e0d8d4364 100644 --- a/openapi.yaml +++ b/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: From 831ab6ef97dc487c7d91cbd1effa3700113d9c01 Mon Sep 17 00:00:00 2001 From: Will Smith Date: Tue, 20 Apr 2021 08:24:09 -0400 Subject: [PATCH 2/4] Fixed spec errors --- openapi.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index e0d8d4364..76632bc51 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -3474,7 +3474,8 @@ paths: /images/upload: x-linode-cli-command: images post: - tags: Images + tags: + - Images summary: Upload Image description: > Initiates a Machine Image upload. @@ -3527,7 +3528,7 @@ paths: type: string description: The URL to upload the image to. image: - $ref: '#/components/schemas/Image' + $ref: '#/components/schemas/ImagePrivate' default: $ref: '#/components/responses/ErrorResponse' /images/{imageId}: From 9767e2cb2bbaa71141eee94a897f3dc9b8e46e09 Mon Sep 17 00:00:00 2001 From: Will Smith Date: Tue, 20 Apr 2021 09:04:40 -0400 Subject: [PATCH 3/4] new: Document new Image.status field This field was added recently to indicate if an Image is ready to be deployed. --- openapi.yaml | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 76632bc51..1c96e3050 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -17330,6 +17330,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 @@ -17433,6 +17447,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: > From 1c74203452a1fbc4a335834a8a7f959751e885d1 Mon Sep 17 00:00:00 2001 From: Will Smith Date: Tue, 20 Apr 2021 11:24:18 -0400 Subject: [PATCH 4/4] Document this as in beta --- openapi.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 1c96e3050..3ac7ccd30 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -3474,6 +3474,8 @@ paths: /images/upload: x-linode-cli-command: images post: + servers: + - url: https://api.linode.com/v4beta tags: - Images summary: Upload Image