Prerequisite: This feature is only available on the stable-v5 stack, from release 3.0.40 upwards, and on the stable-v6 and stable-v7 stacks. Refer to the upgrade guide for further details on how to upgrade an environment.
Environment Variables added through the Engine Yard Cloud dashboard can currently serve two purposes:
- To add environment variables configuration to your instances, which can then be sourced by your application.
- To add variables to the instances' dna.json, in order that they can be sourced by Chef recipes for instance configuration.
Adding Environment Variables
There are a few ways to add environment variables to your Rails application. On Engine Yard Cloud, the easiest way is through the Environment Variables link in the More Options section of the environment page, as shown below.
The Environment Variables page will list any existing variables, and new ones can be added using the New Variable button. Enter the Name and Value. For variables that are for Chef use only you can prevent them being passed to the application by prefixing the variable name with EY_.
After adding environment variables, click Apply to push the variables to the environment's instances. For variables intended for Chef usage, these variables will be picked up during the Apply run and the configuration based upon them. For variables for use by the Rails application you need to restart the application for these to be loaded. To do this you can deploy your application using the Deploy button or the Engine Yard CLI once the Apply run has completed and all instances are green.
How does this work?
When you click Apply, the /etc/chef/dna.json environmental configuration file is updated with the added Environment Variables. Next our Chef recipes will create env.cloud located in /data/<appname>/shared/config containing the variables, excluding those with the EY_ prefix. This file is sourced by the scripts that start Unicorn, Passenger, DelayedJob, Resque, and Sidekiq thus making the variables available to the underlying Rails app. In addition Custom Chef recipes can then be told to extract the required variable from the relevant section of the dna.json to populate Chef variables.
A few things need to be taken into account when using environment variables on an application deployed on Engine Yard:
- Environment variables are put in place by Chef scripts. Hence, every time one is added/removed/modified an Apply is needed on the environment.
- Once clicking 'Apply', the environment variables would be available from /data/<appname>/shared/config/env.cloud
- Environment variables are read only on the start of a process. Hence, for new values to be recognized the process has to be restarted. The Engine Yard deployment process restarts DelayedJob, Resque, and Sidekiq workers, but reloads Unicorn, Passenger, and Puma workers. As such, for restarting those workers you'll need to access every app instance and run /engineyard/bin/app_<appname> restart or through the use of the ey cli tool so to automate that command.
- For multi-application environments, the env.cloud is application specific, so you must ensure that you add the Environment Variables to the correct environment and application combination in the Dashboard.
- Please note that the environment variables declared won't be reflected in the rails console. To validate environment variables using the rails console, run
source /data/<appname>/shared/config/env.cloud && bundle exec rails consoleto source the variables during the SSH session.
To address migrations that depend on environment variables, you can populate the migration text field that appears the moment you check migration with the following:
source /data/<appname>/shared/config/env.cloud && rake db:migrate