Migrate From Engine Yard Gentoo 12.11 (Stable-V4) To Gentoo 2016 (Stable-V5) With Custom Chef

This document provides high level processes for upgrading your environment from Engine Yard Gentoo 12.11 to Engine Yard Gentoo 2016 (stable-v4 to stable-v5). It supports updated packages like Passenger 5, Redis 3, and Java 8, among other things.

Tip: Use the tools and documentation (which are linked-to in the process steps) to save time.

Get started with Engine Yard Gentoo 2016 migration

• Prerequisites
• Migrate to Engine Yard Gentoo 2016
• More information

Prerequisites

• This article assumes you have an existing Engine Yard Gentoo 12.11 (stable-v4) environment.
• Your application must be able to use the component versions as described in the Engine Yard Gentoo 2016 Tech Stack.
• If your app uses database versions less than MySQL 5.6.28 and PostgreSQL 9.4.8, you need to upgrade your database as part of the stack upgrade. Test the database upgrade in your development environment before proceeding with the stack upgrade.

Migrate to Engine Yard Gentoo 2016

Important: We recommend testing in a staging environment before applying changes in a production environment.

To test your application for Engine Yard Gentoo 2016

Verify the initial application in staging

1. Create a copy of your environment, selecting the Engine Yard Gentoo 2016 Tech Stack. Choose Passenger 5, Unicorn or Puma for the Application Server.
   
   If custom chef recipes have been applied to the original environment, they will be copied over to the new environment. Unless you added metadata to the recipes, the V4 recipes will fail to compile when applied on the V5 environment. Please convert the recipes for V5 and do an "ey recipes upload" before booting the new environment. For more information, please see our guide to Migrating custom chef from V4 to V5.

   Note: If you need to swap IP addresses, create the environment in the same region.

2. Verify that your initial app deploys as expected on the new stack.

   You might need to comment out deploy hooks if they expect custom Chef recipes.

Verify cookbooks in staging

1. Ensure that custom recipes are applied to new production [staging].
2. Verify that package versions in custom cookbooks are correct (Engine Yard Gentoo 2016 packages are usually newer).
3. Apply custom recipes and deploy the app again if needed (for deploy hooks).
4. Ensure that the app works as expected.

Verify with data in staging

Note: This can take days or even weeks, depending upon the rigor of your QA testing.

1. Be sure your app won't process data as if it were in production (if your app does things like billing a customer, sending email, etc.).
2. Dump/restore your current production database to the new staging environment.

3. Re-verify that your data is good and the app still works.

   You should be comfortable that the recipes are good and you are ready to begin creating a production environment now.

To prepare your production environment for Engine Yard Gentoo 2016

Create the production environment

1. Set TTL (time to live) for your domain to minimal (e.g., 5 minutes).

   Note: You cannot move EIPs or ELBs if you are changing regions.

2. Create a new production environment on the new stack (basically the same as above, but for production).
3. Re-verify the app in the production environment (same steps as above, again) as needed.

Prepare your production environment

1. Schedule downtime for your application, notifying your customers as needed.

2. (Optional) Stop workers, cron and background jobs.

   Warning: If you have queued-up transactions, you should wait until after you have stopped the app instead.

3. Enable the maintenance page for both the old and new environments.
4. Stop your app at the scheduled down time (including all workers, cron jobs and background jobs).

5. Verify that your production traffic has stopped:

   • You should see the maintenance page.
   • If using Unicorns, you can stop them and check for any remaining database connections.
   • If using Passenger, restart Nginx to kill the workers and check for any remaining database connections.
6. Once production traffic has stopped, dump/restore to new production.

7. Ensure that custom recipes are ready to be applied to new production.

   Note: This may require changes to your custom recipes due to stack changes.

8. Apply the updated custom recipes, then deploy your app.

Sanity testing your production environment

Note: This usually takes only minutes because of all the testing in the processes before it.

1. Bring up your site on internal DNS to verify that all is working.

   For example: sudo /etc/hosts

2. You are now ready to point traffic to the new environment.

Final preparation

1. To send traffic to the new environment you can either update your DNS A record over to the new environment's EIP, or retain the EIP by migrating the IP address from your old to new environment.

   By default, the swap IP tool automatically puts both environments into maintenance mode during the swap; it takes them out of maintenance mode after (unless there is an error).

2. [Optional] If you use CLBs, you can either move the CLB or update the domain CNAME record(s) to the new CLB(s). We recommend still updating DNS or migrating the EIP as per step 1, as some DNS records may be pointing to the EIP rather than the CLB.

   If moving an CLB from a v4 to v5 environment, be sure if using the TCP health check to update the port from 81 to 8081 to compensate for the change in Nginx listening port.

3. If DNS was updated, then set the TTL back to the nominal value.

More Information

These other resources might help you:

If you have feedback or questions about this page, add a comment below. If you need help, submit a ticket with Engine Yard Support.