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_linode_disk

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. (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. (example: ready)
updated	string (date-time)	Read-only When this disk was last updated. (example: 2018-01-01T00:01:01)

get_linode_disks

Returns a paginated list of disks associated with this Linode.

Name	Datatype	Description
data	array
page	integer	Read-only The current page.
pages	integer	Read-only The total number of pages.
results	integer	Read-only The total number of results.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_linode_disk	select			View Disk information for a Disk associated with this Linode. Learn more... Learn more...
get_linode_disks	select		page, page_size	View Disk information for Disks associated with this Linode. Learn more... Learn more...
post_add_linode_disk	insert	data__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. - A Linode can have up to 50 disks. - When creating an empty disk, you need to provide a label for it. If you don't include a label, you need to target an image instead. - When you create a disk from an image, you need to set a root_pass for the disk. - The default file system for a new disk is ext4. If you're creating one from an image, the disk inherits the file system of that image, is unless you specify otherwise. - When you deploy a StackScript on a disk: - You can run List StackScripts to review available StackScripts. - You need to include a compatible image when creating the disk. Run Get a StackScript to review compatible images. - You should supply SSH keys for the disk's root user, using the authorized_keys field. - You can include individual users via the authorized_users field. Before you can add a user, it needs an SSH key assigned to its profile. See Add an SSH key for more information. Learn more... Learn more...
put_disk	replace			Updates a Disk that you have permission to read_write. Learn more... Learn more...
delete_disk	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...
post_clone_linode_disk	exec			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...
post_reset_disk_password	exec	password		Resets the password of a Disk you have permission to read_write. Learn more... Learn more...
post_resize_disk	exec	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
page	integer	The page of a collection to return.
page_size	integer	The number of items to return per page.

SELECT examples

get_linode_disk

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;

get_linode_disks

View Disk information for Disks associated with this Linode.

Learn more...

Learn more...

SELECT
data,
page,
pages,
results
FROM linode.linode.disks
WHERE page = '{{ page }}'
AND page_size = '{{ page_size }}';

INSERT examples

post_add_linode_disk

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.

- A Linode can have up to 50 disks.

- When creating an empty disk, you need to provide a label for it. If you don't include a label, you need to target an image instead.

- When you create a disk from an image, you need to set a root_pass for the disk.

- The default file system for a new disk is ext4. If you're creating one from an image, the disk inherits the file system of that image, is unless you specify otherwise.

- When you deploy a StackScript on a disk:

- You can run List StackScripts to review available StackScripts.

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

- You should supply SSH keys for the disk's root user, using the authorized_keys field.

- You can include individual users via the authorized_users field. Before you can add a user, it needs an SSH key assigned to its profile. See Add an SSH key for more information.

Learn more...

Learn more...

INSERT INTO linode.linode.disks (
data__authorized_keys,
data__authorized_users,
data__filesystem,
data__image,
data__label,
data__root_pass,
data__size,
data__stackscript_data,
data__stackscript_id
)
SELECT 
'{{ authorized_keys }}',
'{{ authorized_users }}',
'{{ filesystem }}',
'{{ image }}',
'{{ label }}',
'{{ root_pass }}',
{{ size }} --required,
'{{ stackscript_data }}',
{{ stackscript_id }}
RETURNING
id,
created,
disk_encryption,
filesystem,
label,
size,
status,
updated
;

Manifest

# Description fields are for documentation purposes
- name: disks
  props:
    - name: authorized_keys
      value: array
      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: array
      description: >
        __Write-only__ A list of usernames. If the usernames 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: string
      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: string
      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: string
      description: >
        __Filterable__ The name of the disk. This is for display purposes only.
        
    - name: root_pass
      value: string
      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: integer
      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: object
      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.
        
    - name: stackscript_id
      value: integer
      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

put_disk

Updates a Disk that you have permission to read_write.

Learn more...

Learn more...

REPLACE linode.linode.disks
SET 
data__label = '{{ label }}'
WHERE 

RETURNING
id,
created,
disk_encryption,
filesystem,
label,
size,
status,
updated;

DELETE examples

delete_disk

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;

Lifecycle Methods

post_clone_linode_disk

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.post_clone_linode_disk 
;

post_reset_disk_password

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

Learn more...

Learn more...

EXEC linode.linode.disks.post_reset_disk_password 
@@json=
'{
"password": "{{ password }}"
}';

post_resize_disk

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.post_resize_disk 
@@json=
'{
"size": {{ size }}
}';