A keep file gives you the flexibility to modify configuration settings in specific files within the /data and /etc directories of your EBS (Amazon Elastic Block Storage) volume.
When Engine Yard’s Chef goes to create configuration files from its recipe templates, it checks the filesystem for certain files prefaced with keep. If such files exist, then the Chef recipe doesn’t create new configuration files; instead it leaves the keep files in place.
For example, if the template is about to write out a configuration file called /data/myservice.conf, Chef first looks for /data/keep.myservice.conf. If this file is found, then Chef skips writing out the template-base configuration file. And, the keep.myservice.conf file is used instead.
Files that can be keep files
These are the files that can be made into keep files.
Note: Only this subset of files in the /etc or /data directories can be made into keep files. Other files in these directories might be overwritten or ignored even if they have been prefaced with “keep”.
- /data/#{appname}/shared/config/database.yml
- /data/nginx/nginx.conf
- /data/nginx/common/proxy.conf
- /data/nginx/common/servers.conf
- /data/nginx/common/fcgi.conf
- /data/nginx/servers/#{appname}.rewrites
- /data/nginx/servers/#{appname}.conf
- /data/nginx/servers/#{appname}.ssl.conf
- /etc/haproxy.cfg
- /etc/conf.d/nginx
- /etc/engineyard/collectd.conf
- /etc/redis/redis.conf
- /etc/monit.d/unicorn_#{appname}.monitrc
- /etc/monit.d/#{name}.#{appname}.monitrc
- /etc/ssh/sshd_config
Important! Risks associated with keep files
There are risks associated with keep files. Use keep files with caution.
Making a keep file effectively “freezes” the file. If your environment changes, either through changes that you apply yourself or when you upgrade to the latest Engine Yard stack, your keep files can become out-of-date and thus compromise your application.
Before making changes to a production environment, review your keep files.
Tip: Where possible, consider using an include file instead of a keep file.
To use keep files for configuration
-
Connect to your instance via SSH.
-
Edit the file and rename (to keep.filename.extension) any of the files listed above.
For example, for an application name “myapp”, configure the nginx server by renaming
/data/nginx/servers/myapp.confto/data/nginx/servers/keep.myapp.conf -
If you make nginx.conf or database.yml into keep files, add a deploy hook to create a symlink.
ln -nfs /data/nginx/keep.nginx.conf /data/nginx/nginx.conf
or
ln -nfs /data/#{appname}/shared/config/keep.database.yml /data/#{appname}/shared/config/database.yml -
Important! If you make any changes to your environment that affect your keep files, update them before rebooting your environment.
More information
| For more information about... | See... |
|---|---|
| SSH | Connect to your instance via SSH. |
| Deploy hooks | Use deploy hooks. |
| Customizing Unicorn configuration (without keep files) | Customize Unicorn. |
If you have feedback or questions about this page, add a comment below. If you need help, submit a ticket with Engine Yard Support.
There is a mention on this page of an 'include file' that we should use instead of a 'keep file' in certain cases but I can't seem to find any information on it when searching through the existing documentation. I might just be blind, though!
I have a few specific entries I would like to add to the generated database.yml file but I would still want the generated file to be produced in case I switch environments. I just want the additional entries added to it. I would assume that 'include.database.yml' would be how it would work but I gave it a shot and it didn't seem to work. Can this article either be updated with the 'include' info or can it have a link to the 'include' documentation?
Thanks!
Hi Phil,
An "include file" refers to one of the files that is automatically included in Nginx configuration. You can see the files that are automatically included in Nginx configuration if you look at the
/data/nginx/nginx.conffile.Referencing the
database.ymlquestion, a "keep file" can be used for this but it is better to use a custom Chef recipe. This allows the file to be generated dynamically if the host of the database should change.If you have further questions, please create a support ticket and we can go a bit deeper.
Thanks,
Evan Machnic
Will /etc/keep.haproxy.conf work on its own, or should we create a simlink in a deploy hook as with /data/nginx/nginx.conf ?
Hi Artem,
tl;dr: nope. Delete the config file (DANGER! DANGER!) and create the symlink.
Longer explanation:
No, /etc/keep.haproxy.conf won't work magically on its own. Honestly, we always try to advise people NOT to use keep files anymore. The reason is that the keep file just tells the platform, "hey, don't overwrite this one here, mmkay?" But the problem with this is that there's no guarantee that said "keep file" will be "kept" if you spin up a new instance. We've also seen things go sideways when upgrades are applied to environments that utilize keep files - say the syntax for something changes, or a command gets deprecated in a new version of something. Boom, there goes your config. Now your site's down. Uncool man, uncool.
So basically if you want to use keepfiles, make a symlink to the actual config file. But to do that you'll need to remove the real config file the platform puts in place prior to creating the symlink. The first part of that statement should give you pause: removing that configuration is a problem because the platform looks at your application server tier and puts that config file in place reflecting each server in your configuration.
In this case, let's say you add an application server to scale horizontally. But your deploy hooks or chef is going to nuke that /etc/haproxy.conf file before forming the symlink to the keepfile. Now you don't have a record of that new machine, meaning you're literally burning money at this point. Unless of course you write your own custom chef to create the haproxy.conf file, reflecting each machine in the configuration. But at that point...why are you using keepfiles anyway? Writing that custom chef basically negates the whole point. :)
Hope this answer was helpful; feel free to ping our support staff at support.cloud.engineyard.com if you need further information.
Thanks J. Austin, I get how it works now.
Yes, I realize the dangers of keeping a stale config, we only want to do that for a temporary workaround.