Configuration
Config files are just ERB templates. There are some special variables that need to be set at the top of the config template file that control what happens when the template is transformed:
| @path | The output path to write the transformed config file to |
| @read_cmd | The command to use for reading the original config file from, e.g. “crontab -l” |
| @write_cmd | The command to use for piping the transformed config file to, e.g. “crontab -” |
| @post | The command to run after generating the config file ONLY if it has changed |
| @delayed_post | Similar to @post, but only run once at the end of all generation |
| @owner | The owner the output file should have, e.g. “root” |
| @group | The group the output file should have, e.g. “system” |
| @perms | The permissions the output file should have, e.g. 0644 |
| @additive | Sets transformation to be additive, only replaces between given delimiters, e.g. @additive = [“## start”, “## end”] |
| @skip | Skips file generation if the value is true |
| @backup | Skips backup of original file during generation if the value is false |
Of the above, the only variables that are required are @path or both of @read_cmd and @write_cmd
In addition, within the config templates you have access to the rubber configuration objects rubber_env (rubber*.yml) and rubber_instances (instance*.yml). This makes it possible to write config files in such a way that adding more instances gets handled automatically – e.g. the proxy destinations in the nginx.conf need to get updated when we add more app server instances. Look at existing config files for examples of using these two configuration objects.
Configuration files are transformed in alphabetic directory order, and the directories are transformed in the following order:
- Configuration files that exist in config/rubber/common will be transformed for all hosts.
- Configuration files that exist in config/rubber/role/ will only be transformed on the hosts that are members of role_name.
- Configuration files that exist in config/rubber/host/ will only be transformed on the hosts with a hostname of host_name.
All the variables used in the config files (and the rubber runtime) are determined by combining all the settings in rubber.yml as well as the settings in rubber-MODULE.yml which contains settings specific to each MODULE (nginx, mongrel, etc). The rubber-MODULE.yml files are read in in alphabetical order.
When combining host/role/environment/global variables in rubber*.yml, scalar (strings, ints) values are overidden by more specific values, that is for the same variable name in all three, the one in host takes precendence followed by environment, then role then global. Non-scalar values (sequences, maps) are merged when combining roles, with keys in maps getting overridden by the more specific ones when there is a conflict. There currently is no way to override a non-scalar for a more specific group, but I actually haven’t needed that capability yet. You can also refer to other variables within the file like so ‘foo: “#{app_name}”’. You are also allowed to execute arbitrary ruby code in the #{} blocks.
One exception to the above is environment-specific configuration files. Any file named with the format `rubber-[environment]-env.yml` will only be loaded for a given Rubber Environment. For example, a file called `rubber-staging-env.yml` will be loaded when `RUBBER_ENV` is set to `staging`, but not for any other environment.
Rubber provides a rails initializer to make it easy to get at configuration values from within your application. It provides the accessors Rubber.config to contain all the configuration values (rubber*.yml) and Rubber.instances to contain a list of the cloud instances (roles, ips, etc). These variables work just like rubber_env/rubber_instances do in your configuration template, and honor your host and role overrides. That is, say your rubber.yml looks like:
foo: bar
hosts:
somehost:
foo: differenthost
roles:
somerole:
foo: differentroleThen if your code is running on host ‘somehost’, RUBBER_CONFIG.foo will have a value of ‘differenthost’, whilst running on any other host it would have a value of ‘bar’. Likewise for roles, if running on a machine in role ‘somerole’, then its value will be ‘differentrole’. If ‘somehost’ also happens to be in role ‘somerole’, the host override wins, and the value would be ‘differenthost’
If Rubber is in your Gemfile, these variables will be available.
If using Rubber as a plugin in Rails 2.x, these variables will be available by default. If running rubber as a gem in Rails 2.x, you’ll need to add a “config.gem ‘rubber’” to your environment.rb.
If not running in Rails, you’ll need to add code to your application initializer that is similar to what the Rails initializer does:
require "rubber"
Rubber::initialize(RAILS_ROOT, RAILS_ENV)