API

Rebuild a Linode

post
https://api.linode.com//linode/instances//rebuild

Rebuild an existing Linode. A rebuild shuts down the Linode, deletes all of its disks and configuration profiles, then deploys a new image to the Linode with the given attributes. Consider these points before rebuilding a Linode:

  • You need to supply an image for use in rebuilding the Linode. This can be a private image you've created or uploaded, or a public image we offer.

  • You need to provide at least one authentication mechanism for disk access: a root_pass, authorized_keys, or authorized_users, with the latter two offering SSH protection.

  • If your target Linode currently uses Metadata ("has_user_data": true), you should include metadata.user_data in the rebuild request to continue using the service.

  • Linode interfaces don't change during a rebuild.

  • During a rebuild, you can enable or disable local disk encryption. If disk encryption is not included in the request, the previous disk_encryption value is used. You can't disable disk encryption if the target Linode is attached to a LKE nodepool.

  • You can resize the Linode to a different plan by including the type parameter, and setting it to a lesser plan. Consider the following points before resizing:

    • You can't have an outstanding balance on your account.

    • Resizing during a rebuild requires significantly more time.

    • If you resize, the Linode will be migrated to a new hardware host, while rebuilding without resizing keeps the same hardware host.

    • If any actions are currently running or queued for the Linode, you need to wait for them to complete.

    • The Linode can't be pending migration.

    • The Linode can't have more disk allocation than the new type supports. If this is the case, you need to delete or resize the disk to be smaller.

    • You can resize a Linode using a separate operation.

    • If you have Block Storage volumes attached to the Linode, you can't resize it to a type that supports fewer volumes. You need to delete volumes from the Linode to meet the limit supported by the smaller type.

Permissions and scopes

To call this operation, you need the following:

  • Identity and access permissions. Your user needs a role with these permissions assigned. Learn more.

    • Permissions: rebuild_linode

  • OAuth scopes. Your user needs these scopes assigned. Learn more.

    • Scopes: linodes:read_write

CLI

linode-cli linodes rebuild 123 \
  --image "linode/debian13" \
  --root_pass aComplex@Password \
  --disk_encryption disabled \
  --authorized_keys "ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer" \
  --authorized_users "myUsername" \
  --authorized_users "secondaryUsername" \
  --booted true \
  --stackscript_id 10079 \
  --stackscript_data '{"gh_username": "linode"}' \
  --type "g6-standard-2" \
  --metadata.userdata "I2Nsb3VkLWNvbmZpZw=="

Learn more

Path Params
string
enum
required

Enum Call either the v4 URL, or v4beta for operations still in Beta.

Allowed:
integer
required

ID of the Linode to rebuild.

Body Params

Common properties for creating and rebuilding Linodes.

authorized_keys
array of strings

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.

📘

You need to set at least one form of authentication to access a Linode disk. This can be authorized_keys, authorized_users, or a root_pass. You can optionally combine authorized_keys with a root_pass for added security.

authorized_keys
authorized_users
array of strings

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

📘

You need to set at least one form of authentication to access a Linode disk. This can be authorized_users, authorized_keys or a root_pass. You can optionally combine authorized_users with a root_pass for added security.

authorized_users
boolean
Defaults to true

Write-only The boot status of the Linode after deployment. This defaults to true if you create the Linode using an image or from a backup. Set this to false to have it remain offline after deployment.

string
enum

Whether disk encryption is applied on this Linode. Local disk encryption ensures that your data is secured. Disk encryption protects against unauthorized data access by keeping the data encrypted if the disk is ever removed from the data center, decommissioned, or disposed of. The platform manages the encryption and decryption for you.

By default, encryption is enabled on all Linodes. If you opted out of encryption or if the Linode was created prior to local disk encryption support, you can encrypt your data using the Rebuild a Linode operation.

Allowed:
string | null
required

The identifier assigned to the disk image to be deployed to the new Linode. You can run the List images operation with authentication to view all available images, and store the id from the applicable one. Official Linode images start with linode/, while any custom images available on your account start with private/. To create a disk from a private/ image, you need read_only or read_write permissions for it. Run the Update a user's grants operation to adjust permissions for a private/ image, or talk to your local account administrator.

string
enum

Defines the maintenance policy for this Linode. This can be one of two policies:

  • linode/migrate. This migrates the Linode to a new host while it remains fully operational, but with some performance degradation. This focuses on maximizing availability.

  • linode/power_off_on. This powers off the Linode at the start of the maintenance event and reboots it once the maintenance finishes. This focuses on maximizing performance.

Review the maintenance policy documentation for more details.

Allowed:
metadata
object

Write-only An object containing user-defined data relevant to the creation of Linodes.

password
required
length between 7 and 128

Write-only This sets the root user's password on a newly created Linode disk when deploying from an image. A root_pass needs to meet a password strength score requirement that is calculated internally by the API. If the strength requirement isn't met, you'll receive a Password does not meet strength requirement error.

📘

You need to set at least one form of authentication to access a Linode disk. This can be a root_pass, authorized_keys, or authorized_users. You can optionally combine a root_pass and either authorized_keys or authorized_users for added security.

stackscript_data
object

This field is required only if the StackScript being deployed requires input data from the user for successful completion. See Declare user-defined fields (UDFs) for more details.

  • This field needs to be formatted in valid JSON.

  • The total length can't exceed 65,535 characters.

integer

An identifier for a StackScript that to be run during deployment of this Linode. A compatible image is required to use a StackScript. To get a list of available StackScripts and their permitted images, run the List StackScripts operation. This field can't be used when deploying from a backup or a private image.

string

The ID of the Linode type to resize to with this request.

Responses

Updated about 1 month ago

Language
Credentials
LoadingLoading…
Response
Choose an example:
application/json

Updated about 1 month ago