Tutorial

How To Manually Initiate Droplet Upgrade To Latest DigitalOcean Cloud

Published on September 29, 2014
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!

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about us


About the authors

Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
 
10 Comments


This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

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.

What is the “latest cloud”?

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.

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

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!

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

I decided to manually upgrade my Droplet today so I powered off my Droplet and initiated the upgrade process through the Control Panel.

As described I was presented with the progress information page stating “Upgrade is processing…” and with a progress bar. The progress bar however stopped working and animating at about 1/3rd and stayed that way for about five minutes up to when I decided to refresh the webpage and to take a look at the Droplets history page.

There was nothing about the upgrade process. No “in progress” or “finished” message, nothing. However some of the Droplet pages were changed and new functionality was available so it looked like the upgrade was completed.

I then powered up my Droplet and everything seems to be working just fine. My guess is everything went well, but I would have appreciated a message of some sort telling me everything went according to plan.

My migration stuck :-( Powered off the Droplet, pressed “Upgrade” in the DO web interface. Progress bar only went till 6% and stuck. When I revisited droplet’s page after 5 minutes, it only displays “Event loading” and then reloads in 1 second. Tried in Firefox, Chrome and Safari.

1 hour has passed since migration start. Droplet is down and I still cannot access its control page. No response to the support ticket #794626 that I created as well. Production server of an app with 4–5k daily visits is down for more than 1 hour already, instead of expected and announced 30 minutes downtime :(

I’ve received like 20 emails about this from Digital Ocean, please stop.

Everything went as described… except it completed rather quickly, like half the time than was expected, and no “Upgrade” event was logged in the History.

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel