Deploy an image

Here we combine API operations to target an image you captured or uploaded, to deploy it to a new disk in a Linode.

Prerequisites

There are a few things you need to do before you can deploy your stored image:

  1. If necessary, run the Create a Linode operation to set up a new Linode to house your stored image's disk.

  2. Run the List Linode operation. In the response, locate the Linode where you want your image to live, and store its id as your linodeId.

  3. Run the List disks operation, using the linodeId you stored. In the response, verify that the results entry is less than 50. A single Linode can have a maximum of 50 disks.

    {
      "data": [
        {
          "created": "2025-01-01T00:01:01",
          "disk_encryption": "disabled",
          "filesystem": "ext4",
          "id": 25674, <== Store.
          "label": "Debian 11 Disk",
          "size": 48640,
          "status": "ready",
          "updated": "2025-01-01T00:01:01"
        },
        ...
      ],
      "page": 1,
      "pages": 5,
      "results": 20 <== Verify this is less than 50.
    }
    
  4. Run the List images operation. In the response, locate the image you want to deploy, and store its id as your imageId as well as its size.

    {
     "data": [
       {
          "capabilities": [
            "cloud-init"
          ],
          "created": "2025-01-01T00:01:01",
          "created_by": "linode",
          "deprecated": false,
          "description": "Secondary golden image for Debian 11 Linux",
          "eol": "2026-07-01T04:00:00",
          "expiry": null,
          "id": "private/goldenimage2", <== Store.
          "is_public": true,
          "label": "Golden Image 2",
          "regions": [
            {
              "region": "us-mia",
              "status": "available"
            }
          ],
          "size": 48640, <== Store.
          "status": "available",
          ...
        },
        {
        ...
      ],
      "page": 1,
      "pages": 5,
      "results": 10
    } 
    

Deploy your image to a Linode

Here, we'll create a new disk on your target Linode and deploy your image to it.

  1. Run the Create a disk operation, using the linodeId you stored to target that Linode. Include the following in the request:

    • image. Set this to the imageId that you stored.

    • root_pass. You need a root user password for the disk. It's used as base security for the disk. (You can also include authorized_keys and authorized_users for additional security.)

    • size. This is the size of the image you stored.

    • label. Leave this out of the request to use the label that's already set for the target image. Including a label will change it to what you set.

    • filesystem. Leave this out of the request to use the image's existing file system.

    {
      "image": "private/goldenimage2",
      "root_pass": "aComplexP@ssword",
      "size": 48640
    }
    
  2. From the response, store the id as your diskId.

    {
      "created": "2025-09-26T13:36:01",
      "disk_encryption": "disabled",
      "filesystem": "ext4",
      "id": 98765, <== Store.
      "label": "Golden Image 2",
      "size": 48640,
      "status": "not ready",
      "updated": "2025-09-26T13:36:01"
    }
    

👍

You can also target an existing disk in a Linode to house your image.

Check the status

The process takes some time to complete. You can check on it by running the Get a disk, using the diskId you stored after creating it.

When the status is ready, the image is ready for use.

{
  "created": "2025-09-26T13:36:01",
  "disk_encryption": "disabled",
  "filesystem": "ext4",
  "id": 98765,
  "label": "Golden Image 2",
  "size": 48640,
  "status": "ready", <== Your image has been successfully deployed.
  "updated": "2025-09-26T13:36:01"
}

Troubleshooting

If you can't access your new disk through SSH or it doesn't respond to pings, check to see if Network Helper is enabled. If it's disabled, the internal network configuration on your Linode isn't automatically configured. In this case, you can do either of the following:

  • Enable Network Helper and reboot.
  • Manually edit your network configuration files and reboot.