OpenFeature Plugin for Backstage

This plugin provides a user-friendly UI for managing OpenFeature Feature Flag custom resources (CRDs) in Kubernetes, integrated with Backstage.

Features

• Create, edit, and view FeatureFlag resources
• Form controls for all key properties (flags, variants, targeting rules)
• Support state toggling (ENABLED/DISABLED)
• Save changes back to the underlying YAML/K8s resources
• Validate inputs against the CRD schema

Background

OpenFeature is an open standard for feature flag management. It provides a unified API and SDK for feature flags across different languages and platforms.

This Backstage plugin focuses specifically on managing feature flags that are implemented as Kubernetes Custom Resources, allowing you to:

1. Create and edit feature flags with a user-friendly form interface
2. Manage boolean, string, number, and complex JSON variants
3. Create targeting rules to serve different variants to different users
4. Track changes through your regular Kubernetes management tools and GitOps workflows

Getting Started

For Plugin Development

1. Install dependencies:

   yarn install

2. Start the plugin in development mode:

   yarn start

3. Run linting and type checks:

   yarn lint
   yarn tsc

4. Run tests:

   yarn test

For Usage in Backstage

1. Install the plugin in your Backstage application:

   yarn add @thrivemarket/backstage-plugin-openfeature

2. Add the plugin to your Backstage instance:

   // In packages/app/src/App.tsx
   import { OpenFeatureFeatureFlagPage } from '@thrivemarket/backstage-plugin-openfeature';
   
   // Add to the routes
   <Route path="/feature-flags" element={<OpenFeatureFeatureFlagPage />} />

3. Add the plugin to your sidebar:

   // In packages/app/src/components/Root/Root.tsx
   import ExtensionIcon from '@material-ui/icons/Extension';
   
   // Add to the sidebar items
   <SidebarItem icon={ExtensionIcon} to="feature-flags" text="Feature Flags" />

4. Configure the plugin to use your Kubernetes API (see Configuration section below)

Configuration

Kubernetes Integration

By default, the plugin uses a mock API for demonstration purposes. To connect it to your actual Kubernetes cluster, we offer two implementation options:

Option 1: Using the Backstage Backend (Recommended)

This option uses the Backstage backend to proxy requests to Kubernetes, which provides better security and authentication:

// In packages/app/src/apis.ts
import { 
  createApiFactory,
  discoveryApiRef,
} from '@backstage/core-plugin-api';
import { createBackstageFeatureFlagApi } from '@thrivemarket/backstage-plugin-openfeature';

export const apis = [
  // ... other API factories
  createBackstageFeatureFlagApi(),
];

You'll also need to set up the backend plugin. See the detailed instructions in the kubernetes-integration.md file.

Option 2: Direct Kubernetes Access

This option connects directly to the Kubernetes API (for development or testing):

// In packages/app/src/apis.ts
import { 
  createApiFactory,
  discoveryApiRef,
  identityApiRef,
} from '@backstage/core-plugin-api';
import { createKubernetesFeatureFlagApi } from '@thrivemarket/backstage-plugin-openfeature';

export const apis = [
  // ... other API factories
  createKubernetesFeatureFlagApi(),
];

For complete Kubernetes integration instructions, including configuration, RBAC setup, and CRD installation, see the kubernetes-integration.md file.

Example FeatureFlag Resource

apiVersion: openfeature.dev/v1alpha1
kind: FeatureFlag
metadata:
  name: my-features
  namespace: default
spec:
  flagSpec:
    flags:
      new-checkout:
        defaultVariant: off
        state: ENABLED
        variants:
          on: true
          off: false
        targeting:
          rules:
            - conditions:
                - field: userId
                  operator: in
                  values:
                    - user123
                    - user456
              variant: on
      theme-mode:
        defaultVariant: system
        state: ENABLED
        variants:
          light: "light"
          dark: "dark"
          system: "system"

Project Structure

src/
├── components/              # UI components
│   ├── FeatureFlagEditor.tsx          # Main editor component
│   ├── FlagDefinitionForm.tsx         # Form for individual flag
│   ├── VariantsEditor.tsx             # Editor for flag variants
│   ├── TargetingRulesEditor.tsx       # Editor for targeting rules
│   └── SchemaValidation.tsx           # Validation utilities
├── api/                    # API layer
│   ├── types.ts                       # TypeScript types matching CRD
│   ├── featureFlagApi.ts              # API for CRUD operations
│   └── kubernetes.ts                  # K8s integration
├── plugin.ts               # Plugin registration
└── index.ts                # Entry point

Examples

The examples/crd directory contains:

• The Kubernetes CRD definition for the FeatureFlag resource
• Example FeatureFlag resources

Development Notes

CLAUDE.md

This repository includes a CLAUDE.md file that contains:

• Detailed architecture documentation
• Development commands and utilities
• Code conventions and standards
• Feature flag structure details
• Known issues and workarounds
• Future improvement plans

This file serves as a comprehensive reference for developers working on this plugin.

CI Setup

This project uses GitHub Actions for continuous integration. The CI pipeline performs the following steps:

1. Sets up Node.js 18.x
2. Installs Yarn 1.22.19 globally via npm
3. Configures a simplified Yarn configuration for CI
4. Installs dependencies
5. Runs linting, TypeScript type checking, and tests
6. Builds the plugin

The configuration files for CI can be found in:

• .github/workflows/ci.yml - GitHub Actions workflow configuration
• .yarnrc.yml - Yarn configuration

When working in CI environments, the pipeline uses the system-installed Yarn rather than a vendored version to avoid compatibility issues.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Before submitting:

1. Ensure tests pass with yarn test
2. Run linting with yarn lint
3. Run type checking with yarn tsc
4. Update documentation as needed

License

Apache-2.0