Manabie Tech Blog

Have you ever struggle having an overview of the feature toggles across your services and applications, especially when you have a lot on the table? We’ve been there before! In this blog, let’s learn how to create a list of feature toggles in Unleash using file. But first, let’s learn some concept of feature toggle and Unleash

What is feature toggle (feature flag)?

Feature toggle (Feature flag) is a technique that allows you to disable some functionality of your application, through settings, without having to deploy new code.

What is Unleash?

Unleash is a feature toggle system, that gives you a great overview of all feature toggles across all your applications and services. It comes with official client implementations for Java, Node.js, Go, Ruby, Python and .Net.

Why we use file to create feature flags instead of Admin UI?

At Manabie, we manage the addition and removal of feature flags with pull request, so we need a solution to manage the list of feature flags by file. Developers can see and change the list of feature flags by modifying this file, don’t need to access the admin page. The list of feature flags will be updated after we deploy new backend code.

How to use file to manage list of feature flags in Unleash?

To run Unleash locally, we need:

• Node.js (version 14 or later)
• PostgreSQL (version 10 or later)
• Create an unleash user and database.

Start Unleash server

• Create a new folder/directory on your development computer.
• From a terminal/bash shell, install the dependencies:

 npm init
 npm install unleash-server --save

• Create a file called server.js, paste the following into it and save.

const unleash = require('unleash-server');
let options = {
    db: {
        ssl: false,
        host: 'localhost',
        port: 9432,
        database: 'unleash',
        user: 'root',
        password: 'root',
    },
    server: {
        port: 4242,
    },
}
unleash
  .start(options)
  .then((unleash) => {
    console.log(
      `Unleash started on http://localhost:${unleash.app.get('port')}`,
    );
  });

• Run server.js:

node server.js

Once the Unleash server has started, you will see the message:

Unleash started on http://localhost:4242

The first time Unleash starts, it will create a default user which you can use to sign-in to you Unleash instance and add more users with:

• username: admin
• password: unleash4all

This is UI Admin of Unleash:

Use startup import in Unleash to create list of feature flags

You can import a json or yaml file via the configuration option import:

import: {
  file: "feature.yaml",
  keepExisting: true,
  dropBeforeImport: true,
 }

If you want the database to be cleaned before import (all strategies and features will be removed), set the dropBeforeImport parameter. It is also possible to not override existing feature toggles (and strategies) by using the keepExisting parameter.

Note: You should be careful when using drop parameter in production environments, as it will clean current state.

Put import configuration to options in server.js:

const unleash = require('unleash-server');
let options = {
    db: {
        ssl: false,
        host: 'localhost',
        port: 9432,
        database: 'unleash',
        user: 'root',
        password: 'root',
    },
    server: {
        port: 4242,
    },
    import: {
        file: "feature.yaml",
        keepExisting: false,
        dropBeforeImport: true,
    }
}
unleash
    .start(options)
    .then((unleash) => {
        console.log(
            `Unleash started on http://localhost:${unleash.app.get('port')}`,
        );
    });

Structure of file feature.yaml

Create a yaml file with the following structure:

version: 3
features:
  - name: feature_xxxx_v1
    description: 'feature_xxxx_v1'
    type: release
    project: default
    stale: false
    variants: []
  - name: feature_yyyyy_v1
    description: 'feature_xxxx_v1'
    type: release
    project: default
    stale: false
    variants: []
strategies:
  - name: strategy_organization
    description: strategy organization to enable/disable feature using organization ID
    parameters:
      - name: organizations
        type: list
        description: list of organizations
        required: true
    deprecated: false
featureStrategies:
  - featureName: feature_xxxx_v1
    projectId: default
    environment: development
    strategyName: strategy_organization
    parameters: {}
    constraints: []
  - featureName: feature_xxxx_v1
    projectId: default
    environment: production
    strategyName: strategy_organization
    parameters: {}
    constraints: []
  - featureName: feature_yyyyy_v1
    projectId: default
    environment: development
    strategyName: strategy_organization
    parameters: {}
    constraints: []
  - featureName: feature_yyyyy_v1
    projectId: default
    environment: production
    strategyName: strategy_organization
    parameters: {}
    constraints: []
environments:
  - name: default
    type: production
    sortOrder: 1
    enabled: false
    protected: true
  - name: development
    type: development
    sortOrder: 100
    enabled: true
    protected: false
  - name: production
    type: production
    sortOrder: 200
    enabled: true
    protected: false
  - name: staging
    type: production
    sortOrder: 300
    enabled: true
    protected: false
featureEnvironments:
  - enabled: true
    featureName: feature_yyyyy_v1
    environment: development
  - enabled: true
    featureName: feature_yyyyy_v1
    environment: production
  - enabled: true
    featureName: feature_xxxx_v1
    environment: development
  - enabled: true
    featureName: feature_xxxx_v1
    environment: production

In this file, we have:

features: list of feature toggles, a feature toggle includes description, type,variants…. If a toggle has variants, then the variants object can also contain an optional payload property. The payload will contain data about the variant’s payload: what type it is, and what the content is. In this example, there are 2 feature toggles feature_xxxx_v1 and feature_yyyyy_v1.

Note: Unleash uses a fallback variant called “disabled” to indicate that a toggle has no variants. However, you are free to create a variant called “disabled” yourself. In that case you can tell them apart by checking the variant’s enabled property: if the toggle has no variants, enabled will be false. If the toggle is the “disabled” variant that you created, it will have enabled set to true.

strategies: you can define your list of custom strategies. Unleash comes with a few common activation strategies. Some of them require the client to provide the unleash-context, which gives the necessary context for Unleash.In this example, I create a strategy named strategy_organization

environments: list of custom environments.Environments is a new way to organize activation strategy configurations for feature toggles into separate environments. In Unleash, a feature lives across all your environments — after all, the goal is to get the new feature released as soon as possible — but it make sense to configure the activation differently per environment.(Environments are available in Unleash v4.3.x and later)

featureStrategies: relationship between your custom feature flags, strategies, and environments.

featureEnvironments: relationship between your custom feature flags,and environments.

Let’s start unleash server again

Now, feature_xxxx_v1 and feature_yyyyy_v1 has been added to the list:

In addition to the default strategies, strategy_organization has been added to the list:

Strategy of feature_xxxx_v1:

List of environment

Conclusion

And that’s all for now! I just introduced about how to create a list of feature toggles in Unleash using YAML file( can also use JSON file). This approach makes it possible for our developers to manage the list of feature flags in our source code. You can read more about import and export in Unleash here