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
- Migrate to Engine Yard Gentoo 2016
- More information
- 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
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.
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
- Ensure that custom recipes are applied to new production [staging].
- Verify that package versions in custom cookbooks are correct (Engine Yard Gentoo 2016packages are usually newer).
- Apply custom recipes and deploy the app again if needed (for deploy hooks).
- 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.
- 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.).
- Dump/restore your current production database to the new staging environment.
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
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.
- Create a new production environment on the new stack (basically the same as above, but for production).
- Re-verify the app in the production environment (same steps as above, again) as needed.
Prepare your production environment
- Schedule downtime for your application, notifying your customers as needed.
(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.
- Enable the maintenance page for both the old and new environments.
- Stop your app at the scheduled down time (including all workers, cron jobs and background jobs).
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.
- Once production traffic has stopped, dump/restore to new production.
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.
- 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.
Bring up your site on internal DNS to verify that all is working.
- You are now ready to point traffic to the new environment.
- If you use ELBs, you can either move the ELB or update the domain CNAME record(s) to the new ELB(s).
If moving an ELB 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.
- If you do not use ELBs, 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).
- If DNS was updated, then set the TTL back to the nominal value.