Bedrock Configurator
This is the documentation for the configuration system for Bedrock instances. We have two distinct types
of configuration values: static and dynamic. Static configurations are those that are loaded at app startup in
the bedrock/settings/base.py
file primarily. They require an app restart to pick up new values and get their
values from either the environment or a .env file in the app root directory.
The second kind of configuration is one that can change while the app is running. At the moment the only use of
these is waffle switches and funnelcake configuration. These can be loaded from the same places as static configs
(environment and .env) but also from the database. So you can continue using your .env
file locally to test
settings, but we can distribute said settings to our running instances via the database update process. This is why
we've separated these values into separate files.
Static configurations are stored in the config
directory in this repo and can only be updated via a push to the app-name
branch (as described below). The dynamic configs however will automatically roll out after a change is merged to the master
branch.
Quick Start
Dynamic Configs
So you want to flip a waffle switch in production? Great! Do this:
- Clone the
mozmeao/www-config
repo. - Fork the repo into your Github account.
- Edit the
waffle_configs/bedrock-prod.env
file to add the name and value you need. You'd add a line likeSWITCH_WE_DO_PHRASING=on
to set that key and value in the settings database for prod. Or you can find the line that already has the variable you need and change the value if it already exists. - Commit the change.
- Push the change to a branch on your fork.
- Submit a pull-request against the
mozmeao/www-config
repo. - Ask for a review in the
#www
IRC channel or in the PR itself. - Once the PR is reviewed and merged it will automatically roll out to our production instances in 5 to 10 minutes.
Static Configs
Let's say you want to change a static config value in prod. Follow the following procedure:
- Clone the
mozmeao/www-config
repo. - Fork the repo into your Github account.
- Edit the
configs/bedrock-prod.env
file to add the name and value you need. You'd add a line likeSTAFF_NAMES=Woodhouse
to set that key and value in the environment for prod. Or you can find the line that already has the variable you need and change the value if it already exists. - Commit the change.
- Push the change to a branch on your fork.
- Submit a pull-request against the
mozmeao/www-config
repo. - Ask for a review in the
#www
IRC channel or in the PR itself. - Once the PR is reviewed and merged it can be applied:
git pull origin master && ./set-config bedrock-prod
. (This assumesorigin
is your remote name for themozmeao
repo. If not, set an environmental variable with that name. For example, if you have named yourmozmeao
remoteupstream
, you'd runMOZ_GIT_REMOTE=upstream ./set-config bedrock-prod
.)
How it Works
This repo is designed to hold the non-secret environment variable configuration options for the various instances of Bedrock. The idea is that you edit the *.env
file associated with the bedrock Deis app you'd like to update (e.g. bedrock-prod.env
). This would be submitted as a pull-request to the www-config
repo, the PR would then be reviewed and merged to master
. Once the config in the master
branch was ready to apply, that revision of master
would be pushed to a branch named after the Deis app name that needed updating (e.g. bedrock-prod
). This would start the process of applying the configuration to our Deis clusters in sequence, and running our headless
tests against them in turn.
If the change to be applied needed to be done as quickly as possible, for example if something is broken, you can alternately push master
to a similar branch as above but prefixed with fast/
(e.g. fast/bedrock-prod
). This will do the same thing as above but every Deis cluster will be pushed and tested simultaneously (or in parallel, instead of in series).
There is a script in the repo to help with this called ./set-config
. It allows you to do the following:
$ ./set-config bedrock-stage
This will push your currently checked out revision of the configurations to the app name passed to it. You can also invoke it with -f
or --fast
and it will cause the configurations to be applied in parallel as mentioned above.
$ ./set-config -f bedrock-prod
Editing the Configs
The configurations are in the configs
and waffle_configs
directories in the repo. They are simple environment files in the format usable by Foreman. The final list of variables to apply for static values will be the mix of 3 possible files.
configs/global.env
: applied to every app.configs/{cluster-name}.env
: applied to every app in{cluster-name}
(e.g.frankfurt
). Seejenkins/regions.yml
for more on the clusters.configs/{app-name}.env
: applied to the app named for the file in every cluster.
You'll almost always only need to edit the file for a particular app, but the others are available should you need them.
You can also delete a static environment variable from an app. Simply set the value of the variable to nothing or whitespace:
# configs to set
DUDE=Abides
# configs to delete
WALTER=
In the above example, if the app had WALTER=bowling
set, then this would remove the WALTER
environment variable from the app
via the deis config:unset
command. It is recommended to keep deleted variables grouped together at the bottom of the env files.
Deleting a dynamic value (those in the waffle_config
directory) is simply deleting the line from the file. The full list of configurations are refreshed every time for those values.