// Tutorial //

How To Manually Initiate Droplet Upgrade To Latest DigitalOcean Cloud

Published on September 29, 2014
Default avatar
By Mitchell Anicas
Developer and author at DigitalOcean.
How To Manually Initiate Droplet Upgrade To Latest DigitalOcean Cloud

Status: Deprecated

This article is deprecated and no longer maintained.

Reason

These instructions are for an old version of the control panel which are no longer relevant.

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.

Settings and Upgrade

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”:

Event Processing

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!


Want to learn more? Join the DigitalOcean Community!

Join our DigitalOcean community of over a million developers for free! Get help and share knowledge in our Questions & Answers section, find tutorials and tools that will help you grow as a developer and scale your project or business, and subscribe to topics of interest.

Sign up
About the authors
Default avatar
Developer and author at DigitalOcean.

Still looking for an answer?

Was this helpful?
10 Comments

So just as a bit of a warning, I did the migration manually a few days before it was scheduled. It completed in 5 minutes which was fabulous but the site never came up. Turns out that somehow, my selected kernel wasn’t on the machine anymore. It took an hour and a half to figure out that I needed to switch to a kernel that was actually supported and then in the process of doing this update I picked the wrong kernel and the entire machine got stuck in a loopback process.

So be careful!

Wow. I just read all these comments.

I would like to say, that I honestly can’t see how DO could have made these instructions more clear or the process more simple. It was perfectly straightforward, they said quite clearly that you would keep your IP address.

Thank you for doing a great job.

j.h.

Wow. I just read all these comments.

I would like to say, that I honestly can’t see how DO could have made these instructions more clear or the process more simple. It was perfectly straightforward, they said quite clearly that you would keep your IP address.

Thank you for doing a great job.

j.h.

Wow. I just read all these comments.

I would like to say, that I honestly can’t see how DO could have made these instructions more clear or the process more simple. It was perfectly straightforward, they said quite clearly that you would keep your IP address.

Thank you for doing a great job.

j.h.

Wow. I just read all these comments.

I would like to say, that I honestly can’t see how DO could have made these instructions more clear or the process more simple. It was perfectly straightforward, they said quite clearly that you would keep your IP address.

Thank you for doing a great job.

j.h.

Wow. I just read all these comments.

I would like to say, that I honestly can’t see how DO could have made these instructions more clear or the process more simple. It was perfectly straightforward, they said quite clearly that you would keep your IP address.

Thank you for doing a great job.

j.h.

A second issue: after the upgrade concluded, the Power->Power Cycle screen, with an all-so-tempting Power Cycle button, was presented at the end of the upgrade.

After first being deterred by the scary warning about pressing that button potentially leading to data corruption … and by then noticing the Droplet History / events list at the bottom, it was clear that I didn’t need to - and really, REALLY shouldn’t - press that button: that the Droplet had been successfully powered on automatically, at the end of the upgrade process.

But in the immediate aftermath of an upgrade, it’s not unreasonable for a user to be forced to consider whether pressing that button might be needed to manually power up the Droplet.

You may or may not have any control over where the user is left, following the upgrade, but if they can be steered away from that Power Cycle screen, that might be beneficial.

A second issue: after the upgrade concluded, the Power->Power Cycle screen, with an all-so-tempting Power Cycle button, was presented at the end of the upgrade.

After first being deterred by the scary warning about pressing that button potentially leading to data corruption … and by then noticing the Droplet History / events list at the bottom, it was clear that I didn’t need to - and really, REALLY shouldn’t - press that button: that the Droplet had been successfully powered on automatically, at the end of the upgrade process.

But in the immediate aftermath of an upgrade, it’s not unreasonable for a user to be forced to consider whether pressing that button might be needed to manually power up the Droplet.

You may or may not have any control over where the user is left, following the upgrade, but if they can be steered away from that Power Cycle screen, that might be beneficial.

Excellent tutorial, Mitchell!

A possible addition: near the end, after “This will initiate the upgrade process for the specified droplet,” it might be useful to note that your Droplet will be automatically powered on, at the end of the upgrade process. (This is implied by a sentence in the Conclusion, “Once the upgrade is complete, please check that all your services are running as expected,” but it’d be helpful to have this noted outright.)

Migrated manual my 20 GB with 132 days uptime in ~3minutes (that is like 1Gbit migration speed) versus the advertised 20 minutes (1min/GB)