How To Manually Initiate Droplet Upgrade To Latest DigitalOcean Cloud

Introduction

If you have received an email notification from DigitalOcean stating that your Droplet will be upgraded to the most recent version of our cloud soon, you have two options for proceeding:

1. Do nothing and allow the automatic upgrade to occur at the scheduled time
2. Initiate the upgrade event manually, any time before the scheduled automatic upgrade

The main benefit of the second option, initiating the upgrade event manually, is that it allows you to control when the upgrade process will occur. Because your Droplet must be offline during the upgrade, this is the method you should use if you have a preferred maintenance window. Regardless of what you do, your Droplet’s IP address will be preserved.

This tutorial will discuss some of the considerations you should take before upgrading, and show you how to initiate the Droplet upgrade event manually via the DigitalOcean Control Panel and API.

What Occurs During a Cloud Upgrade?

In basic terms, the upgrade process involves moving your Droplet from one physical server to another server that is running the latest version of DigitalOcean’s hypervisor software—what we refer to sometimes as the DigitalOcean “cloud”. The upgrade process requires that your Droplet is powered off until it is completed.

Upgrading to the latest version of our cloud enables your Droplet to utilize the latest features of the datacenter where your Droplet resides, as they become available. Example features include IPv6, Private Networking, and Metadata.

Estimated Downtime

The estimated maximum downtime window for the upgrade process for a Droplet is: up to one minute per GB of storage capacity. For example, if your Droplet has 20GB storage capacity, the entire upgrade should take less than 20 minutes after it is initiated.

Now that you know why you should upgrade and how long the process can potentially take, we will cover how to manually initiate the upgrade through the DigitalOcean Control Panel and API.

Poweroff Droplet

Before initiating the upgrade process, it is recommended that you poweroff your Droplet via the command line. This step will ensure that your Droplet will gracefully shutdown before the upgrade.

SSH into your Droplet as a user with sudo access (substitute your own username and IP address):

ssh user_name@droplet_IP_address

Once you are at the command line, issue the poweroff command:

sudo poweroff

You will be disconnected from your Droplet. Now you are ready to initiate the upgrade process via the Control Panel or API, by following the steps in one of the next two sections—choose whichever one you are most comfortable with.

Upgrade via DigitalOcean Control Panel

Note: This upgrade method is only available once a Droplet is scheduled for an upgrade. If any of your Droplets are scheduled for an upgrade, you will receive an email notification with all of the pertinent details, including Droplet ID(s), name(s), and scheduled date and time of migration.

In your web browser, navigate to the Droplets page at https://cloud.digitalocean.com/ (log in if you are prompted).

Find and click the name of the Droplet that was mentioned in the upgrade email.

Click on the Settings button. Here, you should see the Upgrade tab. Click on it.

Now click on the Upgrade button, then accept the confirmation prompt to manually initiate the Droplet upgrade process. Your Droplet will begin upgrading, and will automatically boot when the process is complete!

Verify Upgrade Status

While the upgrade is processing, your Droplet’s information page will display a message stating “Your event is processing…”, and the Droplet’s event history. The upgrade event will show as “Upgrade”:

Once the upgrade process is complete, the Droplet information page will return to normal and there will be a completed “Upgrade” event in the Droplet History section.

View Upgradable Droplets via API

To view a list of your currently upgradable Droplets, including all Droplets that are scheduled for an upgrade, you may use the Droplet_upgrades API endpoint. The usage of this endpoint is documented here: List Droplet Upgrades.

For example, you may run this curl command to request a list of your Droplets that are eligible for an upgrade:

curl -X GET -H 'Content-Type: application/json' -H 'Authorization: Bearer YOUR_API_TOKEN' "https://api.digitalocean.com/v2/droplet_upgrades" 

This will return a JSON array containing information, such as the Droplet ID and scheduled migration time, about any Droplets that are scheduled for migration. If this array is empty, none of your Droplets need to be migrated.

Upgrade via API

If you would prefer to initiate the upgrade process via the DigitalOcean API, you must know the id of the Droplet that will be migrated. If you received an upgrade notification email, the Droplet ID will be included there—otherwise, you may use the API to look up the IDs of any of your upgradable Droplets, by following the directions in the previous section.

Once you have the Droplet ID, you must use it with the Droplet actions API endpoint, and set the type attribute to “migrate_Droplet”. This usage of the API is described in detail here: Upgrade a Droplet.

For example, if you want to make the API request using curl, you could use this command (substitute your API token and Droplet ID):

curl -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer YOUR_API_TOKEN' -d '{"type":"migrate_droplet"}' "https://api.digitalocean.com/v2/droplets/droplet_id/actions"

This will initiate the upgrade process for the specified Droplet.

Conclusion

If your Droplet was powered off before starting the upgrade process, it will remain powered off when the upgrade is complete—be sure to power it on. Please check that all your services are running as expected.

If you have any issues, please leave them in the comments below!