Vultr provides a library of standard ISOs and One-Click Apps for deploying popular operating systems and applications. However, you may need to install an operating system or tool not included in the library, such as a custom build of Kali Linux, OpenBSD, or pfSense. Upload and use your own custom ISO to cover these cases.

This guide explains how to upload a custom ISO to Vultr, deploy new instances with it, attach or detach it from running instances, and manage ISOs using the Vultr API.

Prerequisites

Before you begin, have access to one of the following: the Vultr Console, a Vultr API key, or the Vultr CLI.

Uploading an ISO on Vultr

Upload a custom ISO to Vultr by providing a publicly accessible URL. Once uploaded, the ISO is available in your account and can be used to deploy new instances or attach to existing ones.

Using Vultr Console

1. Log in to the Vultr Console.
2. Click Orchestration in the left sidebar and select ISOs.
3. Click Add ISO +.
4. Enter the ISO URL in the Enter remote URL field. Optionally, enter a name in the Name field.
5. Click Create ISO + to begin the transfer.
6. Wait for the upload to finish. The ISO status changes from Pending to Complete. The time required depends on the size of the ISO and the speed of the source server.

Using Vultr CLI

1. Create an ISO from a public URL. Replace ISO_URL with the public link to your ISO file.

   console Copy

   $ vultr-cli iso create --url ISO_URL
   

   Explain Code

   The response includes details about the ISO. Note the id value for later use.

2. Verify the upload status. Replace ISO_ID with the id value from the previous step.

   console Copy

   $ vultr-cli iso get ISO_ID
   

   Explain Code

   Verify that the STATUS field shows completed before proceeding.

Using Vultr API

1. Create an ISO from a public URL. Replace ISO_URL with the direct link to your ISO file.

   console Copy

   $ curl -sS --fail --compressed "https://api.vultr.com/v2/iso" \
     -X POST \
     -H "Authorization: Bearer ${VULTR_API_KEY}" \
     -H "Content-Type: application/json" \
     --data '{
       "url" : "ISO_URL"
     }' \
     | jq .
   

   Explain Code

   The response includes details about the ISO. Note the id value for later use.

2. Verify the upload status. Replace ISO_ID with the id value from the previous step.

   console Copy

   $ curl -sS --fail --compressed "https://api.vultr.com/v2/iso/ISO_ID" \
     -X GET \
     -H "Authorization: Bearer ${VULTR_API_KEY}" \
     | jq .
   

   Explain Code

   Verify that the status field shows complete before proceeding.

Deploy a New Instance from a Custom ISO

After uploading the ISO, deploy a new instance that boots from it. Complete the operating system installation through the VNC console, then detach the ISO so the instance boots from the installed OS on subsequent reboots.

Using Vultr Console

1. Click Compute in the left sidebar and select Instances.
2. Click Create Instance +.
3. Choose the instance Type that meets your workload requirements.
4. Select the deployment Location.
5. Choose an instance Plan that meets your workload requirements.
6. Click Configure Software.
7. Under Image Selection and Configuration, click the ISO tab and select your Custom ISO from the list.
8. Configure optional Server Settings, such as SSH Keys or a Firewall Group.
9. Enter a Server Hostname and an optional Server Label to identify the instance.
10. Enable any optional Additional Features you want.
11. Review the Deploy Summary and click Deploy to provision the instance.
12. Wait until the instance status changes to Running in the instances list, then click the instance name to open its detail page.
13. Click the View Console icon to open the VNC console and complete the installation.
14. Click the Settings tab, select Custom ISO from the left menu, and click Remove ISO to detach the ISO.

Using Vultr CLI

After deploying the instance with the CLI, open the VNC console in the Vultr Console to complete the OS installation, then detach the ISO.

1. List all available ISOs in your account.

   console Copy

   $ vultr-cli iso list
   

   Explain Code

   Note the id of the ISO you want to use.

2. Create a new instance using the desired ISO. Replace REGION, PLAN, ISO_ID, EXAMPLE_LABEL, and EXAMPLE_HOST with your values.

   console Copy

   $ vultr-cli instance create --region REGION --plan PLAN --iso ISO_ID --label EXAMPLE_LABEL --host EXAMPLE_HOST
   

   Explain Code

3. Log in to the Vultr Console.

4. Click Compute in the left sidebar and select Instances.

5. Select the newly created instance.

6. Click the View Console icon to open the VNC console and complete the installation.

7. Click the Settings tab, select Custom ISO from the left menu, and click Remove ISO to detach the ISO.

Using Vultr API

After creating the instance via the API, open the VNC console in the Vultr Console to complete the OS installation, then detach the ISO via the API.

1. List all available ISOs in your account and note the id of the ISO you want to use.

   console Copy

   $ curl -sS --fail --compressed "https://api.vultr.com/v2/iso" \
     -X GET \
     -H "Authorization: Bearer ${VULTR_API_KEY}" \
     | jq '.isos[] | {id, filename, status}'
   

   Explain Code

2. Create a new instance using the ISO. Replace REGION, PLAN, EXAMPLE_LABEL, ISO_ID, and EXAMPLE_HOST with your values.

   console Copy

   $ curl -sS --fail --compressed "https://api.vultr.com/v2/instances" \
     -X POST \
     -H "Authorization: Bearer ${VULTR_API_KEY}" \
     -H "Content-Type: application/json" \
     --data '{
       "region": "REGION",
       "plan": "PLAN",
       "label": "EXAMPLE_LABEL",
       "iso_id": "ISO_ID",
       "backups": "enabled",
       "hostname": "EXAMPLE_HOST",
       "tags": ["a tag", "another"]
     }' | jq .
   

   Explain Code

   Note the id of the newly created instance from the response.

3. Log in to the Vultr Console.

4. Click Compute in the left sidebar and select Instances.

5. Select the newly created instance.

6. Click the View Console icon to open the VNC console and complete the installation.

7. Detach the ISO so the instance boots from the installed OS. Replace INSTANCE_ID with the instance id from the previous step.

   console Copy

   $ curl -sS --fail --compressed "https://api.vultr.com/v2/instances/INSTANCE_ID/iso/detach" \
     -X POST \
     -H "Authorization: Bearer ${VULTR_API_KEY}"
   

   Explain Code

   Vultr detaches the ISO and reboots the instance automatically.

Conclusion

You have uploaded a custom ISO to Vultr and deployed instances using the Vultr Console, CLI, and API. The instance now boots from the installed operating system, with the custom ISO detached.