Service: Unleash - EyevinnOSC/community GitHub Wiki

Unleash

Unleash (serviceId unleash-unleash) is an open source feature flag management platform for toggling features, running A/B tests and gradual rollouts without redeploying. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance. License: Apache-2.0.

What it can do

  • Create feature flags of type Release, Experiment, Operational, Kill switch or Permission.
  • Use activation strategies such as gradual rollout, UserIDs, IPs, Hostnames or custom strategies, and manage flags across environments such as development, staging and production.
  • Serve backend SDKs (main API) and frontend SDKs (frontend API) with API tokens created at start-up.
  • Connect to applications through the official Unleash SDKs for backend and frontend languages.

Creating an instance

Unleash needs a PostgreSQL database. Create it first and confirm it is running:

  1. Create a PostgreSQL instance (birme-osc-postgresql, see Service: PostgreSQL) with a password. Use describe-service-instance to read its address and port. The URL has the form postgres://postgres:<password>@<host>:<port>/postgres.
  2. Store values as service secrets with create-service-secret (serviceId unleash-unleash): dburl (the PostgreSQL URL), frontendtoken (frontend SDK token) and backendtoken (backend SDK token). Unleash API tokens have the format <project>:<environment>.<secret>, for example default:development.<random-string>.
  3. Create the instance with create-service-instance, serviceId: "unleash-unleash". A {{secrets.NAME}} reference only works as the entire field value.
{
  "name": "myunleash",
  "DatabaseUrl": "{{secrets.dburl}}",
  "InitFrontendApiTokens": "{{secrets.frontendtoken}}",
  "InitBackendApiTokens": "{{secrets.backendtoken}}"
}

Use wait-for-service-ready or get-instance-status, then describe-service-instance for the instance URL. With the OSC CLI:

osc create birme-osc-postgresql mydb -o PostgresPassword="mypassword"
osc create unleash-unleash myunleash \
  -o DatabaseUrl="postgres://postgres:mypassword@<IP>:<PORT>/postgres" \
  -o InitFrontendApiTokens="<frontend-token>" \
  -o InitBackendApiTokens="<backend-token>"

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric, at most 20 characters.
DatabaseUrl Yes string, sensitive PostgreSQL connection URL where Unleash persists feature flags, strategies, users, configuration and audit logs.
InitFrontendApiTokens Yes string, sensitive Comma-separated list of API tokens to initialize for frontend (client-side) SDK authentication, used against the frontend API at /api/frontend/.
InitBackendApiTokens Yes string, sensitive Comma-separated list of API tokens to initialize for backend (server-side) SDK authentication, used against the main API at /api/.

Store the sensitive options as secrets and pass them as {{secrets.NAME}}, as the entire field value. A comma-separated list of several tokens must therefore be stored whole in one secret.

Dependency: PostgreSQL options (birme-osc-postgresql)

Option Required Type Meaning
name Yes string Name of the instance.
PostgresPassword Yes string, sensitive Password for the PostgreSQL superuser.
PostgresUser No string Superuser name. Defaults to postgres.
PostgresDb No string Name of the default database created at start. Defaults to the same name as the user.
PostgresInitDbArgs No string Extra arguments passed to initdb.
PostgresInitDbSql No string SQL executed during database initialization.

Using the instance

Open the instance URL and log in with the default admin credentials admin / unleash4all. Change the password immediately after the first login in the admin settings. Click New feature flag to create a flag.

Backend SDK (Node.js):

const { initialize } = require('unleash-client');

const unleash = initialize({
  url: 'https://<your-instance-url>/api/',
  appName: 'my-app',
  customHeaders: { Authorization: '<your-backend-api-token>' },
});

unleash.on('ready', () => {
  if (unleash.isEnabled('my-feature')) {
    console.log('Feature is enabled!');
  }
});

Frontend SDK (React):

import { FlagProvider } from '@unleash/proxy-client-react';

const config = {
  url: 'https://<your-instance-url>/api/frontend/',
  clientKey: '<your-frontend-api-token>',
  appName: 'my-react-app',
};

function App() {
  return (
    <FlagProvider config={config}>
      <YourComponent />
    </FlagProvider>
  );
}

Replace <your-instance-url> with the instance URL and use the tokens you configured.

Limitations

  • Initial admin credentials are the Unleash defaults; change them on first login.

Resources

⚠️ **GitHub.com Fallback** ⚠️