Configuring LaunchDarkly Plugin

Introduction

The LaunchDarkly plugin allows you to view feature flags on entity pages in Roadie. It provides multiple UI components to display feature flags for specific contexts, projects, and environments, helping teams manage and monitor their feature flag deployments directly within their service catalog.

This plugin supports viewing flags for individual contexts, comparing flags across multiple environments, and filtering flags by tags or queries to focus on relevant feature flags for each service.

At a Glance

LaunchDarkly Entity Configuration

Step 1: Create a LaunchDarkly API Token

Roadie requires an API token to connect to LaunchDarkly and retrieve feature flag information.

1. Log into your LaunchDarkly account
2. Navigate to Account Settings → Authorization
3. Create a new API token with read-only permissions
4. Copy the generated token for use in Roadie

You can learn more about generating API tokens by visiting the LaunchDarkly API documentation.

Step 2: Configure Roadie with your LaunchDarkly API Token

1. Navigate to the secrets page in Roadie at /administration/secrets
2. Enter the API token you generated in the secret called LAUNCHDARKLY_API_KEY
3. Save the configuration

Step 3: Annotate Your Entities

Add the following annotations to your catalog-info.yaml files to connect entities with LaunchDarkly feature flags:

Basic Configuration

metadata:
  annotations:
    launchdarkly.com/project-key: default
    launchdarkly.com/environment-key: production
    launchdarkly.com/context: '{"kind":"tenant","key":"roadie","name":"roadie"}'

Advanced Configuration with Filtering

metadata:
  annotations:
    launchdarkly.com/project-key: default
    launchdarkly.com/environment-key: production
    launchdarkly.com/context: '{"kind":"tenant","key":"roadie","name":"roadie"}'
    launchdarkly.com/filter-tags: '["frontend", "api"]'
    launchdarkly.com/filter-query: 'dark-mode'

Step 4: Add UI Components

The LaunchDarkly plugin provides multiple UI components that can be added to entity pages:

EntityLaunchdarklyContextOverviewCard

Displays feature flags for a specific LaunchDarkly context. This card shows flags relevant to the entity’s configured context and is ideal for service-specific flag monitoring.

For the EntityLaunchdarklyContextOverviewCard component launchdarkly.com/project-key, launchdarkly.com/environment-key and launchdarkly.com/context are needed.

This card can be added to component dashboards.

EntityLaunchdarklyCard

Displays LaunchDarkly flags across multiple environments with column toggling capabilities. This component provides a comprehensive view of how flags are configured across different environments (e.g., development, staging, production).

EntityLaunchdarklyCard component supports launchdarkly.com/project-key and launchdarkly.com/filter annotations.

This card can be added to component dashboards.

Annotation Reference

Troubleshooting

Feature flags not appearing

1. Verify API token configuration

   • Check that LAUNCHDARKLY_API_KEY is correctly set in Roadie secrets
   • Ensure the API token has not expired
   • Verify the token has appropriate read permissions

2. Check entity annotations

   • Confirm launchdarkly.com/project-key matches your LaunchDarkly project
   • Verify launchdarkly.com/environment-key exists in your project
   • Ensure JSON context format is valid if using context annotation

3. Validate LaunchDarkly configuration

   • Confirm the project and environment exist in LaunchDarkly. Note that launchdarkly environment name and the environment key may not be the same.
   • Check that feature flags exist in the specified environment
   • Verify network connectivity to LaunchDarkly API

UI components not displaying

1. Check component availability

   • Verify the LaunchDarkly plugin is enabled in your Roadie instance
   • Ensure UI components are properly configured on entity pages
   • Check browser console for JavaScript errors

2. Validate entity conditions

   • Confirm entities have the required LaunchDarkly annotations

Filtering not working

1. Verify filter syntax

   • Ensure filter-tags is a valid JSON array
   • Check that tag names match exactly with LaunchDarkly flag tags
   • Verify filter-query syntax matches LaunchDarkly search capabilities.

2. Check flag configuration

   • Confirm flags have the expected tags in LaunchDarkly
   • Verify flag names contain the query string if using query filtering

References

• LaunchDarkly Plugin on npm
• LaunchDarkly API Documentation
• LaunchDarkly Feature Flag Documentation
• Backstage Entity Annotations