Notice: This document was originally published in 2012.
This document provides high level processes for upgrading your environment from Engine Yard Gentoo 2009 to Engine Yard Gentoo 12.11 (stable-v2 to stable-v4). It supports the recent addition of the latest generation AWS instance types such as AWS M3, AWS C3 and AWS C4.
These processes are for more complex environments that use custom Chef. For simple upgrades, see Simple Upgrade from Engine Yard Gentoo 2009 (stable-v2) to 12.11 (stable-v4).
Tip: Use the tools and documentation (which are linked-to in the process steps) to save time.
Get started with Engine Yard Gentoo upgrade
- This article assumes you have an existing Engine Yard Gentoo 2009 (stable-v2) environment.
- Your application must be able to use the component versions as described in the Engine Yard Gentoo 12.11 Tech Stack.
- If your app uses database versions less than MySQL 5.5 and PostgreSQL 9.2, 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.
- You must use 64-bit instances (32-bit instances are not supported on the Engine Yard Gentoo 12.11 (stable-v4) distribution).
Upgrade to Engine Yard Gentoo 12.11
Important: We recommend testing in a staging environment before applying changes in a production environment.
To test your application for Engine Yard Gentoo 12.11
Verify the initial application in staging
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.
Verify cookbooks in staging
Ensure that custom recipes are applied to new production [staging].
Note: This might require changes to your custom recipes due to stack changes. On the Engine Yard Gentoo 12.11 stack, system gems may be in
/usr/bin/) and you might need to update any full paths for calls to bundle, rake, or other system gems (use
/usr/local/bin/rake). Otherwise some recipes and deploy hooks can break.
- Verify that package versions in custom cookbooks are correct (Engine Yard Gentoo 12.11 packages 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 12.11
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 CLBs, you can either move the CLB or update the domain CNAME record(s) to the new ELB(s).
- 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.
These other resources might help you:
|For more information about ...||See ...|
|Upgrade intro and overview||Upgrade Guide|
|Single server (solo) environment upgrades||Upgrade a Single Server (Solo) Environment|
|Multiple server environment upgrades||Upgrade a Multiple Server Environment|
|Simple upgrades from v2 to v4||Simple Upgrade from Engine Yard Gentoo 2009 (stable-v2) to 12.11 (stable-v4)|
|Supported AWS instances on Engine Yard||Amazon Instance Type Support|
|Which version of your stack components you need to use with Engine Yard Gentoo 12.11||Engine Yard Gentoo 12.11 Tech Stack|
If you have feedback or questions about this page, add a comment below. If you need help, submit a ticket with Engine Yard Support.