Jump to content

Help:Cloud VPS instance operating system migration

From Wikitech

Cloud VPS instances use the Debian operating system. New "stable" Debian major releases are traditionally released every other year, with combined stable security and LTS security support for 5 years since the release. To be responsible internet citizens and to protect the Cloud VPS system, the Cloud VPS admin team requires that all Cloud VPS instances use an operating system version with security support available. Details about current deprecation cycles can be seen on the News page.

If your workload is compatible with Toolforge, consider migrating there instead of rebuilding on Cloud VPS. Toolforge manages the underlying operating system, reducing future maintenance and upgrade work for maintainers.

The Cloud VPS administrators recommends migrating by rebuilding instances on a newer operating system rather than performing an in-place operating system upgrade. A rebuild provides an opportunity to start from a clean, supported environment and often reduces the risk of issues caused by legacy configuration or package drift. Regularly re-building instances is also an opportunity to roll out more modern instance options (for example, new and more reliable networking backends) without disrupting running instances.

This page also describes an option where an existing instance is upgraded "in-place". This mechanism is generally not supported, but might be necessary in some special circumstances. Please contact us before performing any in-place upgrades.

Re-building instances

In this approach, a new instance is created using a supported operating system. Application data and configuration are then migrated from the old instance to the new instance.

Because Cloud VPS projects host a wide variety of applications and services, the exact migration procedure will vary by project.

Step 1: create a new instance

Log in to Horizon and create a new instance using a supported operating system image, ideally the latest version available.

When creating the new instance:

  • Choose an appropriate instance flavor (likely the same as that of the instance to be replaced, eg. g3.cores4.ram8.disk20).
  • Configure security groups and networking as needed. Generally this means applying the same security groups to the new instance as are on the old one.
  • Verify that you can log in successfully.

Step 2: create a temporary cinder volume

Create a Cinder volume large enough to hold any data that must be transferred between instances.

If your project does not have sufficient volume quota available, request a temporary quota increase.

Step 3: attach the volume to the existing instance

Attach the newly created volume to the existing instance.

Verify that the volume is visible to the operating system and can be mounted.

Step 4: copy data to the volume

Copy any required application data, uploaded files, backups, or other persistent content from the old instance to the attached volume.

The exact process will vary depending on the workload being migrated.

Examples may include:

  • Application data
  • User uploads
  • Database backups
  • Configuration files
  • Generated content

Step 5: detach the volume from the old instance

Once the data transfer is complete, unmount the volume if necessary and detach it from the old instance.

Step 6: attach the volume to the new instance

Attach the volume to the newly created Bookworm or Trixie instance.

Mount the volume and restore or integrate the transferred data as required by your application.

Better yet, point installed software on the new instance at data on the cinder volume so that it's still portable for any future migrations.

Step 7: validate the migration

Before retiring the old instance, verify that:

  • Services start correctly.
  • Web applications are accessible.
  • Scheduled jobs run as expected.
  • Databases and other dependencies function normally.
  • Users can access the application without issues.

Step 8: retire the old instance

After verifying the new instance is functioning correctly, shut down and delete the old instance to free project resources.

In-place upgrades

In-place upgrades are generally not supported, but might be necessary in some special circumstances. Please contact us before performing any in-place upgrades.

An in-place upgrade may be appropriate for some workloads, but it generally carries more risk than rebuilding a new instance.

Each Debian release is identified by a codename (for example, Debian 13 is known as "trixie"). You will need to known the codenames of the currently running release and the release you are upgrading to. Skipping releases is not supported.

Step 1: verify the current operating system

Confirm what the instance is running (eg. Debian Bullseye): 

$ cat /etc/os-release

Look for: 

VERSION_CODENAME=bullseye

Step 2: fully update Bullseye

Install all available Bullseye updates before beginning the operating system upgrade: 

$ sudo apt update
$ sudo apt upgrade
$ sudo apt full-upgrade
$ sudo reboot

Step 3: update package sources

Modify the APT package sources to reference the target release.

For example, replace: 

bullseye

with: 

bookworm

in /etc/apt/sources.list in and any files in /etc/apt/sources.list.d/. Update or remove third-party repositories as appropriate.

Step 4: upgrade packages

Update package metadata and perform the distribution upgrade: 

$ sudo apt update
$ sudo apt upgrade
$ sudo apt dist-upgrade

During the upgrade you may be prompted to:

  • Replace configuration files.
  • Restart services.
  • Resolve package conflicts.

Review prompts carefully before proceeding.

Step 5: reboot

Reboot the instance after the upgrade completes: 

$ sudo reboot

Step 6: Verify the Upgrade

Confirm that the operating system is now running the expected release: 

$ cat /etc/os-release

For example: 

VERSION_CODENAME=bookworm

Step 7: validate services

Verify that all applications and services continue to function correctly after the upgrade.

Pay particular attention to:

  • Web applications
  • Databases
  • Background workers
  • Scheduled jobs
  • Application-specific dependencies

Communication and support

Support and administration of the WMCS resources is provided by Wikimedia Foundation staff and Wikimedia movement volunteers. Please reach out with questions and join the conversation:

Discuss and receive general support
  • Chat in real time in the IRC channel #wikimedia-cloud connect or the bridged Telegram group
  • Discuss via email after you have subscribed to the cloud@ mailing list
Stay aware of critical changes and plans
Track work tasks and report bugs

Use a subproject of the #Cloud-Services Phabricator project to track confirmed bug reports and feature requests about the Cloud Services infrastructure itself

Read stories and WMCS blog posts

Read posts about Cloud Services on the Wikimedia Technical Blog. (Older posts can be read from the Cloud Services Blog.)

Retrieved from "https://wikitech.wikimedia.org/w/index.php?title=Help:Cloud_VPS_instance_operating_system_migration&oldid=2444572"