Organize feature flags

Structure and manage feature flags at scale using namespaces, labels, and multiple SDK keys to improve team collaboration, reduce operational overhead, and maintain clear ownership boundaries.

Effective organization becomes critical as feature flag usage grows across teams, applications, and environments.

Prerequisites

Before organizing feature flags, ensure you have:

Feature flags created across your applications.
Understanding of your team structure and application architecture.
SDK version 6.x or later if implementing multiple SDK keys.
Appropriate access permissions for the flags you need to organize.

Organize flags with namespaces

Use namespaces to create logical groupings based on consistent naming conventions that reflect your organizational structure.

Implement namespace conventions

Establish naming patterns that group related flags by domain, service, or team:

Define your namespace strategy:
- By service: billing.enableCoupons, search.enableAutocomplete
- By team: teamA.newCheckout, teamB.profileRedesign
- By feature area: auth.enable2FA, user.darkMode
Apply consistent prefixes when creating flags:
1. Navigate to Feature management and select Create flag.
2. Enter flag names using your namespace convention: [namespace].[feature-description]
3. Use descriptive, lowercase names with dots separating the namespace from the feature name.

// JavaScript example
const flags = {
    enableDiscounts: new Rox.Flag(),
    enableExpressCheckout: new Rox.Flag()
};

// Register with namespace
Rox.register('checkout', flags);▼

// Java example
public class CheckoutFlags implements RoxContainer {
    public RoxFlag enableDiscounts = new RoxFlag();
    public RoxFlag enableExpressCheckout = new RoxFlag();
}

// Register with namespace
CheckoutFlags checkoutFlags = new CheckoutFlags();
Rox.register("checkout", checkoutFlags);▼

Benefits of namespace organization

Namespaces provide several organizational advantages:

Prevent naming conflicts: Multiple teams can use similar flag names without collision (teamA.enableFeature vs teamB.enableFeature).
Clear ownership: Namespace prefixes immediately identify which team or service owns a flag.
SDK-level management: Perform operations like freezing or unfreezing at the namespace level.
Modular structure: Group flags by logical boundaries that match your application architecture.

Best practices for namespaces

Follow these guidelines for effective namespace implementation:

Use consistent conventions: Establish and document naming standards across your organization.
Keep namespaces simple: Use short, descriptive prefixes that are easy to remember and type.
Align with architecture: Match namespaces to your service boundaries or team structures.
Document ownership: Maintain clear documentation of which teams own which namespaces.

Organize flags with labels

Use labels to provide flexible categorization that complements namespace structure and enables dynamic filtering and reporting.

Add labels to flags

Apply descriptive metadata to flags for enhanced organization:

Navigate to Feature management and locate your flag.
Select the vertical ellipsis icon (⋮) next to the flag name.
Select Edit flag settings.
In the Labels field, add relevant tags:
- Team labels: team:platform, team:mobile
- Lifecycle labels: beta, deprecated, production
- Feature type labels: experimental, performance, ui-change
- Project labels: q1-release, checkout-redesign
Select Update to save the labels.

Use labels for filtering and analysis

Leverage labels for operational efficiency:

Filter flag lists:
1. Navigate to Feature management.
2. Select Filter and choose label-based criteria.
3. Apply multiple label filters to narrow down flag lists.
Analyze flag performance:
1. Group metrics by label to understand performance across teams or feature types.
2. Use labels in dashboards to segment adoption and usage analytics.
3. Track flag lifecycle stages using lifecycle labels.
Manage flag cleanup:
1. Filter for deprecated or inactive labels to identify cleanup candidates.
2. Use project labels to coordinate flag removal after project completion.

Label organization strategies

Design label taxonomies that support your operational needs:

Hierarchical labeling: Use consistent patterns like team:platform, status:beta, priority:high.
Multi-dimensional categorization: Apply multiple labels to enable various filtering views.
Lifecycle tracking: Use labels to track flags through development, testing, and production phases.
Cross-cutting concerns: Label flags that affect multiple services or have security implications.

Manage multiple SDK keys

Initialize and run multiple SDK instances in one application, with each instance having its own SDK key and environment. The instances are fully isolated. Use multiple SDK keys when you need to read or compare flags across environments without redeploying, to support multi-tenant routing, or to combine server-side and client-side evaluations in one application.

When to use multiple SDK keys

Use multiple SDK keys when your application needs to evaluate flags across more than one environment or context, for example:

Multi-tenant isolation: Route evaluations per tenant or customer to different environments.
Regional isolation: Evaluate against region-specific environments.
Cross-team feature sets: Load flags and targeting rules from multiple projects so teams retain ownership and RBAC while the application evaluates both.

Prerequisites for multiple SDK keys

Review these requirements before implementing multiple SDK keys. They apply to all supported platforms:

SDK v6.x or later for your platform.
One SDK key per application-environment you plan to use.
The flags you plan to evaluate exist in each application and environment being queried.
Network access to CloudBees Unify endpoints from your runtime.

How multiple SDK keys operate

The SDK models multiple keys, isolates data and operations, supports runtime context switching, and lets each instance register multiple containers with namespaces:

One instance per key: Each SDK instance is initialized with a single SDK key and evaluates flags only for that environment.
Isolation: Caches, network connections and streams, fetch and polling, callbacks and listeners, and telemetry are independent per instance.
Context switching: You choose the instance per request, user, or tenant; that instance auto-fetches and applies flag updates.
Lifecycle: Initialize, fetch and stream, and shut down each instance separately.
Backward compatibility: The legacy singleton and static API still works. You can mix it with instance-based clients to adopt multiple keys incrementally; prefer instance-scoped APIs when using multiple keys.

Set up multiple SDK keys

These steps provide an SDK-agnostic overview of the process. For concrete code, refer to the example applications and SDK references in Code examples and references.

Retrieve the SDK keys for the environments you’ll use.
Initialize a separate SDK instance for each key.
Decide how to route requests to instances; for example, by tenant, region, or environment selector.
Perform register, fetch, and stream setup on each instance as required by your SDK.
Evaluate flags using the selected instance, passing a consistent user or context object for accurate targeting.
Tag logs or metrics for each instance, and shut down instances you no longer need.

Recommended practices for multiple SDK keys

Use these practices to maintain clear isolation between instances, consistent evaluations, and reliable operations:

Instance management: Store instance references for reuse, and use consistent naming conventions for SDK keys.
Flag naming: Use prefixes to distinguish flags from different configurations, for example prod_enableFeature vs staging_enableFeature.
Custom properties: Set custom properties on the specific instance. Avoid using static custom property methods with multiple SDK keys.
Error handling: Set up configuration fetched handlers for each instance, and monitor for network errors per instance.

Troubleshoot multiple SDK key issues

Use this list to quickly diagnose and resolve common multiple SDK key issues:

Wrong environment evaluated: Ensure you select the intended SDK instance before evaluation.
No updates applied: Confirm register, fetch, or streaming is configured for that specific instance.
Callbacks not firing: Attach listeners to the same instance that performs fetch or streaming.
Unexpected differences: Compare flag definitions, targeting rules, and salts across environments.
High network activity: Reduce the number of active instances, or adjust polling or stream settings.

Code examples and references

Combine organizational strategies

Integrate namespaces, labels, and multiple SDK keys for comprehensive flag management.

Unified organization approach

Design a coherent system that leverages all organizational tools:

Establish naming conventions that work across namespaces and labels.
Create label taxonomies that complement namespace structure.
Document instance patterns for multi-SDK key usage.
Train teams on consistent application of organizational strategies.

Example integrated setup

Consider this comprehensive organization pattern:

Namespace structure: - auth. - Authentication service flags - billing. - Billing service flags - ui.* - User interface flags

Label taxonomy: - Team labels: team:backend, team:frontend - Lifecycle labels: status:development, status:production - Priority labels: priority:critical, priority:standard

Multi-instance strategy: - Production instance for live traffic evaluation - Staging instance for testing and validation - Tenant-specific instances for multi-tenant applications

This integrated approach provides clear boundaries, flexible categorization, and context-appropriate evaluation while maintaining operational simplicity.