disks

Creates, updates, deletes, gets or lists a disks resource.

Overview

Name	disks
Type	Resource
Id	linode.linode.disks

Fields

The following fields are returned by SELECT queries:

get

Returns a single Disk object.

Name	Datatype	Description
id	integer	Read-only This disk's ID. You need this value to run other operations that interact with the disk.
created	string (date-time)	Read-only When this disk was created. (example: 2018-01-01T00:01:01)
disk_encryption	string	Read-only Displays if encryption is enabled on this disk. This setting is based on the disk_encryption setting of the Linode. (default: enabled, example: disabled)
filesystem	string	The disk's format or file system. A value of raw indicates no file system, just a raw binary stream. A value of swap indicates a Linux swap area. The values ext3 or ext4 represent these Linux journaling file systems. The value ext2 is the deprecated ext2 Linux file system. Finally, initrd indicates the disk is formatted as an uncompressed initial RAM disk. > 📘 > > The ext2 file system doesn't properly support timestamps and will be removed from Linux support in the near future. Also, initrd is a legacy format that no longer applies to most use cases. As a best practice, use the other supported formats or file systems instead. (raw, swap, ext2, ext3, ext4, initrd) (example: ext4)
label	string	Filterable The name of the disk. This is for display purposes only. (example: Debian 9 Disk)
size	integer	Filterable The size of the disk in MB.
status	string	Read-only The current state of the disk. (ready, not ready, deleting) (example: ready)
updated	string (date-time)	Read-only When this disk was last updated. (example: 2018-01-01T00:01:01)

list

Returns a paginated list of disks associated with this Linode.

Name	Datatype	Description
id	integer	Read-only This disk's ID. You need this value to run other operations that interact with the disk.
created	string (date-time)	Read-only When this disk was created. (example: 2018-01-01T00:01:01)
disk_encryption	string	Read-only Displays if encryption is enabled on this disk. This setting is based on the disk_encryption setting of the Linode. (default: enabled, example: disabled)
filesystem	string	The disk's format or file system. A value of raw indicates no file system, just a raw binary stream. A value of swap indicates a Linux swap area. The values ext3 or ext4 represent these Linux journaling file systems. The value ext2 is the deprecated ext2 Linux file system. Finally, initrd indicates the disk is formatted as an uncompressed initial RAM disk. > 📘 > > The ext2 file system doesn't properly support timestamps and will be removed from Linux support in the near future. Also, initrd is a legacy format that no longer applies to most use cases. As a best practice, use the other supported formats or file systems instead. (raw, swap, ext2, ext3, ext4, initrd) (example: ext4)
label	string	Filterable The name of the disk. This is for display purposes only. (example: Debian 9 Disk)
size	integer	Filterable The size of the disk in MB.
status	string	Read-only The current state of the disk. (ready, not ready, deleting) (example: ready)
updated	string (date-time)	Read-only When this disk was last updated. (example: 2018-01-01T00:01:01)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	linodeId, diskId		View Disk information for a Disk associated with this Linode. Learn more... Learn more...
list	select	linodeId	page, page_size	View Disk information for Disks associated with this Linode. Learn more... Learn more...
create	insert	linodeId, size		Add a new disk to an existing Linode. You can create an empty disk to manually configure it later. You can also target a stored image to build the disk using a pre-configured file system--either through an image you've created or via a StackScript. For added security with all disks, you should supply SSH keys for the disk's root_pass user, using the authorized_keys field. > 📘 > > A Linode can have up to 50 disks. Empty disks - When creating an empty disk, a label is required. - The default file system for an empty disk is ext4. Disks created from an image - A root_pass is required for a disk created from a stored image. - A created disk inherits both the label and the filesystem from the target image, unless you specify otherwise. - We offer an example workflow to create a disk using a stored image. Disks created from a StackScript - You can run List StackScripts to review available StackScripts. - You need to include a StackScript-compatible image when creating the disk. Run Get a StackScript to review available images. Learn more... Learn more...
update	replace	linodeId, diskId		Updates a Disk that you have permission to read_write. Learn more... Learn more...
delete	delete	linodeId, diskId		Deletes a Disk you have permission to read_write. Deleting a Disk is a destructive action and cannot be undone. Learn more... Learn more...
clone	exec	linodeId, diskId		Copies a disk, byte-for-byte, into a new disk on the same Linode. The operation fails if the target doesn't have enough storage space. A Linode can have up to 50 disks. Learn more... Learn more...
reset_password	exec	linodeId, diskId, password		Resets the password of a Disk you have permission to read_write. Learn more... Learn more...
resize	exec	linodeId, diskId, size		Resizes a Disk you have permission to read_write. The Disk must not be in use. If the Disk is in use, the request will succeed but the resize will ultimately fail. For a request to succeed, the Linode must be shut down prior to resizing the Disk, or the Disk must not be assigned to the Linode's active Configuration Profile. If you are resizing the Disk to a smaller size, it cannot be made smaller than what is required by the total size of the files current on the Disk. Learn more... Learn more...

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
diskId	string	ID of the Disk to look up.
linodeId	string	ID of the Linode to look up.
page	integer	The page of a collection to return.
page_size	integer	The number of items to return per page.

SELECT examples

get

View Disk information for a Disk associated with this Linode.

Learn more...

Learn more...

SELECT
id,
created,
disk_encryption,
filesystem,
label,
size,
status,
updated
FROM linode.linode.disks
WHERE linodeId = '{{ linodeId }}' -- required
AND diskId = '{{ diskId }}' -- required
;

list

View Disk information for Disks associated with this Linode.

Learn more...

Learn more...

SELECT
id,
created,
disk_encryption,
filesystem,
label,
size,
status,
updated
FROM linode.linode.disks
WHERE linodeId = '{{ linodeId }}' -- required
AND page = '{{ page }}'
AND page_size = '{{ page_size }}'
;

INSERT examples

create

Add a new disk to an existing Linode. You can create an empty disk to manually configure it later. You can also target a stored image to build the disk using a pre-configured file system--either through an image you've created or via a StackScript. For added security with all disks, you should supply SSH keys for the disk's root_pass user, using the authorized_keys field.

> 📘
>
> A Linode can have up to 50 disks.

Empty disks

- When creating an empty disk, a label is required.

- The default file system for an empty disk is ext4.

Disks created from an image

- A root_pass is required for a disk created from a stored image.

- A created disk inherits both the label and the filesystem from the target image, unless you specify otherwise.

- We offer an example workflow to create a disk using a stored image.

Disks created from a StackScript

- You can run List StackScripts to review available StackScripts.

- You need to include a StackScript-compatible image when creating the disk. Run Get a StackScript to review available images.

Learn more...

Learn more...

INSERT INTO linode.linode.disks (
authorized_keys,
authorized_users,
filesystem,
image,
label,
root_pass,
size,
stackscript_data,
stackscript_id,
linodeId
)
SELECT 
'{{ authorized_keys }}',
'{{ authorized_users }}',
'{{ filesystem }}',
'{{ image }}',
'{{ label }}',
'{{ root_pass }}',
{{ size }} /* required */,
'{{ stackscript_data }}',
{{ stackscript_id }},
'{{ linodeId }}'
RETURNING
id,
created,
disk_encryption,
filesystem,
label,
size,
status,
updated
;

Manifest

# Description fields are for documentation purposes
- name: disks
props:
  - name: linodeId
    value: "{{ linodeId }}"
    description: Required parameter for the disks resource.
  - name: authorized_keys
    value:
      - "{{ authorized_keys }}"
    description: |
      __Write-only__ A list of public SSH keys that will be automatically appended to the root user's `~/.ssh/authorized_keys` file when deploying from an Image.
  - name: authorized_users
    value:
      - "{{ authorized_users }}"
    description: |
      __Write-only__ A list of usernames for authorized users. Before you can add a user, it needs an SSH key assigned to its profile. See [Add an SSH key](https://techdocs.akamai.com/linode-api/reference/post-add-ssh-key) for more information. If the usernames already have associated SSH keys, the keys will be appended to the root users `~/.ssh/authorized_keys` file automatically when deploying from an image.
  - name: filesystem
    value: "{{ filesystem }}"
    description: |
      The disk's format or file system. A value of `raw` indicates no file system, just a raw binary stream. A value of `swap` indicates a Linux swap area. The values `ext3` or `ext4` represent these Linux journaling file systems. The value `ext2` is the deprecated ext2 Linux file system. Finally, `initrd` indicates the disk is formatted as an uncompressed initial RAM disk.
      > 📘
      >
      > The `ext2` file system doesn't properly support timestamps and will be removed from Linux support in the near future. Also, `initrd` is a legacy format that no longer applies to most use cases. As a best practice, use the other supported formats or file systems instead.
    valid_values: ['raw', 'swap', 'ext2', 'ext3', 'ext4', 'initrd']
  - name: image
    value: "{{ image }}"
    description: |
      An Image ID to deploy the Linode Disk from.
      Run the [List images](https://techdocs.akamai.com/linode-api/reference/get-images) operation with authentication to view all available Images. Official Linode Images start with `linode/`, while your Account's Images start with `private/`. Creating a disk from a Private Image requires `read_only` or `read_write` permissions for that Image. Run the [Update a user's grants](https://techdocs.akamai.com/linode-api/reference/put-user-grants) operation to adjust permissions for an Account Image.
  - name: label
    value: "{{ label }}"
    description: |
      __Filterable__ The name of the disk. This is for display purposes only.
  - name: root_pass
    value: "{{ root_pass }}"
    description: |
      __Write-only__ This sets the root user's password on a newly created Linode Disk when deploying from an Image.
      - __Required__ when creating a Linode Disk from an Image, including when using a StackScript.
      - Must meet a password strength score requirement that is calculated internally by the API. If the strength requirement is not met, you will receive a `Password does not meet strength requirement` error.
  - name: size
    value: {{ size }}
    description: |
      __Filterable__ The size of the Disk in MB.
      Images require a minimum size. Run the [Get an image](https://techdocs.akamai.com/linode-api/reference/get-image) operation to view its size.
  - name: stackscript_data
    value: "{{ stackscript_data }}"
    description: |
      This field is required only if the StackScript being deployed requires input data from the User for successful completion. See [User Defined Fields (UDFs)](https://www.linode.com/docs/products/tools/stackscripts/guides/write-a-custom-script/#declare-user-defined-fields-udfs) for more details.
      This field is required to be valid JSON.
      Total length cannot exceed 65,535 characters. (opaque JSON object)
  - name: stackscript_id
    value: {{ stackscript_id }}
    description: |
      A StackScript ID that will cause the referenced StackScript to be run during deployment of this Linode. A compatible `image` is required to use a StackScript. To get a list of available StackScript and their permitted Images, run [List StackScripts](https://techdocs.akamai.com/linode-api/reference/get-stack-scripts). This field cannot be used when deploying from a Backup or a Private Image.

REPLACE examples

update

Updates a Disk that you have permission to read_write.

Learn more...

Learn more...

REPLACE linode.linode.disks
SET 
label = '{{ label }}'
WHERE 
linodeId = '{{ linodeId }}' --required
AND diskId = '{{ diskId }}' --required
RETURNING
id,
created,
disk_encryption,
filesystem,
label,
size,
status,
updated;

DELETE examples

delete

Deletes a Disk you have permission to read_write.

Deleting a Disk is a destructive action and cannot be undone.

Learn more...

Learn more...

DELETE FROM linode.linode.disks
WHERE linodeId = '{{ linodeId }}' --required
AND diskId = '{{ diskId }}' --required
;

Lifecycle Methods

clone

Copies a disk, byte-for-byte, into a new disk on the same Linode. The operation fails if the target doesn't have enough storage space. A Linode can have up to 50 disks.

Learn more...

Learn more...

EXEC linode.linode.disks.clone 
@linodeId='{{ linodeId }}' --required, 
@diskId='{{ diskId }}' --required
;

reset_password

Resets the password of a Disk you have permission to read_write.

Learn more...

Learn more...

EXEC linode.linode.disks.reset_password 
@linodeId='{{ linodeId }}' --required, 
@diskId='{{ diskId }}' --required 
@@json=
'{
"password": "{{ password }}"
}'
;

resize

Resizes a Disk you have permission to read_write.

The Disk must not be in use. If the Disk is in use, the request will succeed but the resize will ultimately fail. For a request to succeed, the Linode must be shut down prior to resizing the Disk, or the Disk must not be assigned to the Linode's active Configuration Profile.

If you are resizing the Disk to a smaller size, it cannot be made smaller than what is required by the total size of the files current on the Disk.

Learn more...

Learn more...

EXEC linode.linode.disks.resize 
@linodeId='{{ linodeId }}' --required, 
@diskId='{{ diskId }}' --required 
@@json=
'{
"size": {{ size }}
}'
;