Waffle

We use waffle for managing feature access in production.

Why switches and not flags

We prefer to use switches over flags in most cases as switches are:

switches are simple
switches are easy to reason about

Flags can be used if you want to do a gradual rollout a feature over time or to a subset of users.

We have a flag 2fa-enforcement-for-developers-and-special-users in production now.

Creating/Deleting a switch

Switches are added via database migrations. This ensures the switch exists in all environments once the migration is run.

To create or remove a switch, first create an empty migration in the app where your switch will live.

python ./manage.py makemigrations <app> --empty

Creating a switch

add the switch in the migration

from django.db import migrations

from olympia.core.db.migrations import CreateWaffleSwitch

class Migration(migrations.Migration):

    dependencies = [
        ('app', '0001_auto_20220531_2434'),
    ]

    operations = [
        CreateWaffleSwitch('foo')
    ]

Deleting a switch

remove the switch in the migration

from django.db import migrations

from olympia.core.db.migrations import DeleteWaffleSwitch

class Migration(migrations.Migration):

    dependencies = [
        ('app', '0001_auto_20220531_2434'),
    ]

    operations = [
        DeleteWaffleSwitch('foo')
    ]

Using a switch

Use your switch in python code

if waffle.switch_is_active('foo'):
    # do something

Use your switch in jinja2

{% if waffle.switch_is_active('foo') %}
    <p>foo is active</p>
{% endif %}

Testing

Testing the result of a switch being on or off is important to ensure your switch behaves appropriately. We can override the value of a switch easily.

Override for an entire test case

# Override an entire test case class
@override_switch('foo', active=True)
class TestFoo(TestCase):
    def test_bar(self):
        assert waffle.switch_is_active('foo')

    # Override an individual test method
    @override_switch('foo', active=False)
    def test_baz(self):
        assert not waffle.switch_is_active('foo')

Enabling your switch

Once your switch is deployed, you can enable it in a given environment by following these steps.

ssh into a kubernetes pod in the environment you want to enable the switch in. (instructions)
run the CLI command to enable your switch (instructions)

Toggling a switch on

./manage.py waffle_switch foo on

Once you’ve ensured that it works on dev, the typical way of doing things would be to add that manage.py command to the deploy instructions for the relevant tag. The engineer responsible for the tag would run the command on stage, then SRE would run it in production on deploy.

Cleanup

After a switch is enabled for all users and is no longer needed, you can remove it by:

Deleting all code referring to the switch.
adding a migration to remove the flag.