Migrating from Stack v7 to Stack v8 (Ubuntu 24.04)

<supportagent>This is the customer-facing version. Support should refer to the source engineering document: trilogy-group/ey-all — docs/guide-v7-to-v8-migration.md</supportagent>

Stack v8 (Ubuntu 24.04) is offered alongside Stack v7 (Ubuntu 20.04) in the Environment UI. Moving to v8 is opt-in and follows the same pattern as previous stack upgrades: move a staging environment first, validate your application against the new runtime, then move production — with your v7 instances retained so you can roll back.

Read the companion article "Engine Yard Ubuntu 24.04 Technology Stack" for the full component matrix and more details. Two changes in that matrix require application-side work before you opt in, and are the focus of this guide:

The Ruby floor — Ruby 2.7 and 3.0 are not available on v8.
The MySQL 8.4 authentication change — the default authentication plugin changes to caching_sha2_password.

How the move works

Stack v7 stays the default. Environments that do not opt in are unaffected.
Staging first. Move a staging (or cloned) environment to v8 and validate before you move production.
Rollback is built in. Starting the upgrade pins your existing v7 instances to v7 and makes v8 the environment default. You then add v8 instances yourself — the upgrade does not create them for you — and your v7 instances are retained until you confirm the environment is healthy. If anything fails, you cut back to the retained v7 instances.

Stack v8 is enabled per account. Stack v8, its database engines (PostgreSQL 16 / MySQL 8.4), and Passenger 6 are turned on for your account by Engine Yard — they are not visible to every account by default. If Stack v8 (or a v8 database engine) does not appear in the Environment UI, contact Engine Yard Support to have it enabled for your account before proceeding. Until it is enabled, a new environment may show only "No Database" as the database option.

Prerequisites — do these before opting in

0. Confirm Stack v8 is enabled for your account

Before you start, confirm both of the following in the Environment UI. If either is missing, contact Engine Yard Support to request enablement for your account (a one-time step per account):

Stack v8 and your database engine appear as options when creating an environment: Stack v8 in the Stack list, and PostgreSQL 16 or MySQL 8.4 in the Database Stack list. If Stack v8 appears but the only database option is "No Database", the stack is enabled but the engine is not — you need both.
The "Major Upgrade" entry appears under More options on your environment's page. This is the page you use in Step 2, and it is enabled separately from Stack v8 itself.

If you also intend to run Passenger 6 on v8, confirm it appears in the Application Server list — it is enabled separately again. Without it, v8 offers Unicorn and Puma only.

1. Ruby floor: 2.7 and 3.0 must be upgraded first

Stack v8 supports Ruby 3.1, 3.2, 3.3, and 3.4. Ruby 2.7 and 3.0 are not available on Ubuntu 24.04 (Ruby 2.7.8 will not install, and Ruby 3.0.7's openssl extension does not work at runtime). If your application runs on Ruby 2.7 or 3.0, you must upgrade it to Ruby 3.1 or newer before you opt into Stack v8. Recommended steps:

Upgrade the application to Ruby 3.1+ (3.4 is the v8 default) on your current v7 environment or locally, and get its test suite passing.
Resolve any gem incompatibilities introduced by the Ruby upgrade while still on v7.
Only then proceed with the v8 migration below.

Applications already on Ruby 3.1, 3.2, or 3.3 can move to v8 without a Ruby upgrade.

2. Node.js: 18 must move to 20 LTS or 22

Stack v8 offers Node.js 20 LTS and 22. Node 18 is end-of-life and not available. If your asset build or runtime depends on Node 18 or earlier, move it to Node 20 LTS or 22 and confirm the build before migrating.

3. MySQL 8.4 authentication

If your environment uses a managed MySQL database, note that Stack v8 offers MySQL 8.4 only, and 8.4 changes the default authentication plugin. See the dedicated section below — this is the most common cause of a post-migration connection failure. Audit your MySQL driver and connection settings before the migration window.

4. Custom Chef recipes

If your environment uses custom Chef recipes, review the companion article "Chef recipe compatibility: Stack v7 vs Stack v8." Several system-level changes on Ubuntu 24.04 (the SSH service unit name, IMDSv2, MySQL 8.4 replication SQL, PostgreSQL 16 promotion) require recipe updates. Convert and test custom recipes on a staging environment before moving to production.

5. Database migration planning

Moving a managed database across a major version (MySQL 8.0 to 8.4, or PostgreSQL 14 to 16) is part of the v7 to v8 move. It is a new-instance dump and restore, not an in-place upgrade: a new v8 database instance is provisioned, your data is loaded into it, and your v7 database instance is retained untouched so rollback is simply repointing to it. Cutover downtime depends on the size of your database, while rollback is fast and independent of data size. Contact Engine Yard Support to plan the move and size a maintenance window for it. For the mechanics of restoring or loading a database, see Restore or Load a Database.

6. Instance architecture, if you use Graviton (ARM)

Stack v8 runs on both x86_64 and ARM (AWS Graviton) instance types.

Managed MySQL cannot run on an ARM instance. If you select an ARM instance type (m6g, c7g, t4g and similar) for a database instance with a managed MySQL engine, the environment form is rejected with "ARM instance types are incompatible with MySQL database stacks." This is a long-standing platform restriction and is not specific to v8. It means:

MySQL environments must use an x86_64 database instance. Application instances may still be ARM — the restriction applies only to the database instance and its replicas.
PostgreSQL 16 has no such restriction and runs on ARM database instances. If you intend to use ARM database instances, confirm your intended instance type with Engine Yard Support before you provision, since the ARM database path is newer and less widely exercised than x86_64.

If you use a cluster preset rather than a custom configuration, note that presets apply one instance type to every role, which is why choosing an ARM type for a MySQL environment is rejected outright.

MySQL 8.4 authentication

This is the single most likely customer-visible change when moving to Stack v8, so it is called out separately.

What changed. MySQL 8.4 makes caching_sha2_password the default authentication plugin for new users, and disables mysql_native_password by default.

Why it can break connections. When your database is migrated to v8, the application's database users are recreated on the v8 instance and default to caching_sha2_password. An application will fail to authenticate if it connects with either of the following:

A MySQL client/driver that only supports mysql_native_password (older driver versions).
A connection that does not use TLS (caching_sha2_password requires either TLS or an RSA key exchange for the initial handshake).

How to prepare (before the migration window):

Audit your driver. Confirm your application's MySQL adapter supports caching_sha2_password. For Ruby, use a current mysql2 gem. Upgrade the driver on v7 first if needed.
Confirm TLS. Ensure your application connects to the database over TLS, or is configured for the RSA-key handshake that caching_sha2_password requires without TLS.
Audit existing users. On the v7 database, list users still on the native plugin so you know which will need attention:
```
SELECT user, host, plugin FROM mysql.user WHERE plugin = 'mysql_native_password';
```
Audit the schema for AUTO_INCREMENT on FLOAT/DOUBLE columns. MySQL 8.4 rejects AUTO_INCREMENT on floating-point columns, so a dump of such a table will fail to restore during cutover. This is rare, but check for it while still on v7 and change the affected columns to an integer type before migrating.

Options at migration time:

Preferred: recreate the application's database users on the v8 instance with caching_sha2_password and connect over TLS. This is the supported long-term state.
```
ALTER USER 'app_user'@'%' IDENTIFIED WITH caching_sha2_password BY '<password>';
```
Temporary bridge only: MySQL 8.4 can be started with --mysql-native-password=ON to re-enable the native plugin as a stopgap while you update drivers. This is not a long-term state — mysql_native_password is scheduled for removal in the MySQL 9.x series — so treat it as a migration bridge, not a destination.

Migration procedure

Always run the first migration of a given application on a staging (or cloned) environment. Never make production the first environment you move.

Step 1 — Prepare the application (on v7)

Upgrade Ruby to 3.1+ if on 2.7/3.0.
Move Node to 20 LTS / 22 if on 18 or earlier.
Update the MySQL driver and confirm TLS.
Convert and test any custom Chef recipes.
Get the application's test suite passing on the upgraded runtime while still on v7.

Step 2 — Move a staging environment to v8

The upgrade is started from the Major Upgrade page, not from the environment's normal settings.

On the staging (or cloned) environment's page, open More options and choose Major Upgrade.
The page offers four choices, each pre-set to the environment's current value. All four are submitted together, so decide them before you start:
- Stack — select stable-v8-1.0.
- Ruby — select 3.1, 3.2, 3.3, or 3.4. If the environment is on 2.7 or 3.0 you must change it here.
- Application Server — Unicorn, Puma, or Passenger 6. If the environment currently runs Passenger 5 you must change it, because Passenger 5 does not exist on v8.
- Database — PostgreSQL 16 or MySQL 8.4. You can only stay within the same engine family; the page will not offer a move between PostgreSQL and MySQL.
Click Initiate Upgrade. The button only becomes available once the four selections form a valid v8 combination and at least one differs from the current value.

What this does — and does not do. Initiating the upgrade pins your existing v7 instances to v7 and sets v8 as the environment's default. That is all. It does not provision anything, does not run Chef, and does not touch running instances or serving traffic.

Add the v8 instances yourself. Because the environment default is now v8, instances you add from this point boot on the Ubuntu 24.04 image and converge the v8 configuration, while the pinned v7 instances continue serving.
For a managed database, a new v8 database instance is provisioned and your data is migrated by dump and restore; the v7 database instance is retained. See "Database migration planning" above, and plan the move with Engine Yard Support.

The readiness banner is advisory. The Major Upgrade page shows a Stack v8 readiness check that flags problems such as an unsupported Ruby version or a database outside the v8 matrix. It does not block the upgrade — treat a warning as something to resolve, not as something the system will stop you from ignoring.

Step 3 — Validate on staging

Confirm the application boots and serves reads and writes on v8.
Confirm database connectivity specifically (this is where the authentication change surfaces).
Run the application's smoke tests and any environment-specific checks.
Confirm backups run and restore on v8 (eybackup / eyrestore).

If your database is MySQL, confirm your environment is on stack release stable-v8-1.0.1 or later before running a restore. An earlier release (stable-v8-1.0.0) had a defect that could cause a MySQL restore to fail (and, in a replicated environment, affect the replica). It is fixed in stable-v8-1.0.1. PostgreSQL environments are unaffected.

Step 4 — Move production

Once staging is validated, repeat Step 2 for production during the agreed maintenance window. Size the window to your database's cutover time, planned with Engine Yard Support.

Step 5 — Complete or roll back

On success: complete the upgrade in the Environment UI. This requires all running instances to be on v8. After a soak period, the retained v7 instances (including the v7 database instance) can be deprovisioned.
On failure at any point: roll back by cutting the environment back to the retained v7 instances. The v7 instances — including the v7 database, whose data was never modified — serve the application again. Then drop the new v8 instances. Rollback repoints to untouched instances rather than restoring from a backup, so it does not depend on your data size. It is not instantaneous, though (in testing, on the order of several minutes, most of it terminating the v8 instances), so allow for that rather than assuming it is immediate.

Migration checklist

Stack v8 (and the needed database engine) confirmed enabled for the account, or requested from Engine Yard Support.
Major Upgrade confirmed present under More options (enabled separately from Stack v8).
Passenger 6 confirmed available if you intend to use it (enabled separately again).
Replacement app server chosen if the environment currently runs Passenger 5.
Database instance type confirmed x86_64 if the engine is MySQL.
Environment on stack release stable-v8-1.0.1 or later before running any MySQL restore.
Application upgraded to Ruby 3.1+ (mandatory if currently on 2.7 or 3.0).
Node.js moved to 20 LTS or 22 if currently on 18 or earlier.
MySQL driver confirmed to support caching_sha2_password; TLS confirmed.
Existing mysql_native_password users identified and a plan set (recreate with caching_sha2_password, or a temporary --mysql-native-password=ON bridge).
MySQL schema audited for AUTO_INCREMENT on FLOAT/DOUBLE columns.
Custom Chef recipes reviewed and tested on v8.
Database move and maintenance window planned with Engine Yard Support.
Staging environment moved to v8 and validated (app + DB connectivity + backups).
Production migration scheduled and rollback plan confirmed.

Choose files or drag and drop files

Tags:

Was this article helpful?

Yes

Manuel da Silva
Posted