Balrog

If you are looking for the general documentation that used to live here, it has been moved into the Balrog repository, and a built version of it is available on Read The Docs.

This page will continue to host information about Balrog that doesn't make sense to put into the repository, such as meeting notes and things related to our hosted versions of Balrog.

Balrog is the software that runs the server side component of the update system used by Firefox and other Mozilla products. It is the successor to AUS (Application Update Service), which did not scale to our current needs nor allow us to adapt to more recent business requirements. Balrog helps us ship updates faster and with much more flexibility than we’ve had in the past.

Infrastructure

Environments

We have a number of different Balrog environments with different purposes:

Environment	App	URL	Deploys	Purpose
Production	Admin	https://aus4-admin.mozilla.org (VPN Required)	Manually by CloudOps	Manage and serve production updates
	Public	https://aus5.mozilla.org and others (see the Client Domains page for details)
Stage	Admin	https://balrog-admin.stage.mozaws.net/ (VPN Required)	When version tags (eg: v2.40) are created	A place to submit staging Releases and verify new Balrog code with automation
	Public	https://aus4.stage.mozaws.net/ https://aus5.stage.mozaws.net/
Dev	Admin	https://balrog-admin.dev.mozaws.net (VPN Required)	Whenever new code is pushed to Balrog's master branch	Manual verification of Balrog code changes in a deployed environment
	Public	https://aus5.dev.mozaws.net/

Support & Escalation

If the issue may be visible to users, please make sure #moc is also notified. They can also assist with the notifications below.

RelEng is the first point of contact for issues. To contact them, follow the standard RelEng escalation path.

If RelEng is unable to correct the issue, they may escalate to CloudOps.

Monitoring & Metrics

Metrics from RDS, EC2, and Nginx are available in the Datadog Dashboard.

We aggregate exceptions from both the public apps and admin app to CloudOps' Sentry instance.

ELB Logs

Balrog publishes logs to S3 buckets which are available for querying in Redash. The relevant tables are:

• balrog_elb_logs_aus{3,4,5} - These tables contain update request records sourced from the ELB logs of the named domain (eg: aus5). If you're looking to do ad-hoc queries of update request (eg: estimate how many users are on a particular version or channel), the balrog_elb_logs_aus5 is probably what you want to query.
• balrog_elb_logs_aus_api - This table contains request logs for the aus-api.mozilla.org domain
• log_balrog_admin_nginx_access - This table contains access logs for the admin app sourced from nginx access logs.
• log_balrog_admin_nginx_error - This table contains error logs for the admin app sourced from nginx error logs.
• log_balrog_admin_syslog_admin_fixed - This table contains syslog output from the admin app's Docker container.
• log_balrog_admin_syslog_agent - This table contains syslog output from the agent's Docker container.
• log_balrog_web_syslog_web_fixed - This table contains syslog output from the public app's Docker containers.

Redash should show you the table schemas in the pane on the left. If not, you can inspect with them with "describe $table".

Backups

Balrog uses the built-in RDS backups. The database in snapshotted nightly, and incremental backups are done throughout the day. If necessary, we have the ability to recover to within a 5 minute window. Database restoration is done by CloudOps, and they should be contacted immediately if needed.

Deploying Changes

Balrog's stage and production infrastructure is managed by the Cloud Operations team. This section describes how to go from a reviewed patch to deploying it in production. You should generally begin this process at least 24 hours before you want the new code live in production. This gives the new code a chance to bake in stage.

At a high level, the deployment process looks like this:

• Verify the new code in dev
• Bake the new code in stage
• Deploy to prod

Each part of this process is described in more detail below.

Is now a good time?

Before you deploy, consider whether or not it's an appropriate time to. Some factors to consider:

• Are we in the middle of an important release such as a chemspill? If so, it's probably not a good time to deploy.
• Is it Friday? You probably don't want to deploy on a Friday except in extreme circumstances.
• Do you have enough time to safely do a push? Most pushes take at most 60 minutes to complete once the production push has begun.

Schema Upgrades

If you need to do a schema change you must ensure that either the current production code can run with your schema change applied, or that your new code can run with the old schema. Code and schema changes cannot be done at the same instant, so you must be able to support one of these scenarios. Generally, additive changes (column or table additions) should do the schema change first, while destructive changes (column or table deletions) should do the schema change second. You can simulate the upgrade with your local Docker containers to verify which is right for you.

A quick way to find out if you have a schema change is to diff the current tip of the master branch against the currently deployed tag, eg:

tag=REPLACEME
git diff $tag

When you file the deployment bug (see below), include a note about the schema change in it. Something like:

This push requires a schema change that needs to be done _prior_ to the new code going out. That can be performed by running the Docker image with the "upgrade-db" command, with DBURI set.

bug 1295678 is an example of a push with a schema change.

Verification in dev

The dev environment automatically deploys new code from the master branch of the Balrog repository (including any necessary schema changes). Before beginning the deployment procedure, you should do some functional testing there. At the very least, you should do explicit testing of all the new code that would be included in the push. Eg: if you're changing the format of a blob, make sure that you can add a new blob of that type, and that the XML response looks correct.

If you have schema changes you must also ensure that the existing deployed code will work with the new schema. To do this, CloudOps will downgrade the dev apps. You should do some routine testing (make some changes to some objects, try some update requests) to ensure that everything works. If you have any issues you CANNOT proceed to production.

Baking in stage

To get the new code in stage you must create a new Release in Github as follows:

1. Tag the repository with a "vX.Y" tag. Eg: "git tag -s vX.Y && git push --tags"
2. Diff against the previous release tag. Eg: "git diff v2.24 v2.25", to double whether or not there's schema changes.
   • Look for anything unexpected, or any schema changes. If schema changes are present, see the above section for instructions on handling them.
3. Create a new Release on Github. This create new Docker images tagged with your version, and deploys them to stage. It may take upwards of 30 minutes for the deployment to happen.

Once the changes are deployed to stage, let them bake for at least 24 hours. You can do additional targeted testing here if you wish, or simply wait for nightlies/releases to prod things along. It's a good idea to watch Sentry for new exceptions that may show up, and Datadog for any notable changes in the shape of the traffic.

Pushing to production

Pushing live requires CloudOps. For non-urgent pushes, you should begin this procedure a few hours in advance to give CloudOps time to notice and respond. For urgent pushes, file the bug immediately and escalate if no action is taken quickly. Either way, you must follow this procedure to push:

1. File a bug to have the new version pushed to production.
   • Wednesdays around 11am Pacific are usually the best day to push to production, because they are generally free of release events, nightlies, and cronjobs. Unless you have a specific need to deploy on a different day, you should request the prod push for a Wednesday between those hours
   • You should link any bugs being deployed is the "Blocks" field.
   • Make sure you substitute the version number and choose the correct options from the bug template.
2. Once the push has happened, verify that the code was pushed to production by checking the __version__ endpoints on the Admin and Public apps.
3. Bump the in-repo version to the next available one to ensure the next push gets a new version.

Meeting Notes

• CloudOps Migration Meeting - June 22, 2016
• Balrog/absearch Information Exchange - June 28, 2016
• CloudOps Migration Meeting - June 29, 2016
• CloudOps Migration Meeting - July 6, 2016
• CloudOps Final Cut Over Planning - July 12, 2016
• Balrog Worker Brainstorming - July 19, 2016
• CloudOps Meeting - July 27, 2016
• CloudOps Meeting - August 10, 2016
• CloudOps Meeting - September 7, 2016
• CloudOps Meeting - September 14, 2016
• CloudOps Meeting - September 21, 2016
• CloudOps Meeting - September 28, 2016
• CloudOps Meeting - October 19, 2016
• CloudOps Meeting - November 2, 2016
• CloudOps Meeting - November 9, 2016
• CloudOps Meeting - January 17, 2017
• CloudOps Meeting - February 22, 2017