Feature Flags Service

The Feature Flags service provides the necessary APIs to evaluate dynamic feature flags.

The service is always enabled, however, it will return the fallback value if a feature flags provider hasn't been attached. Kibana only registers a provider when running on Elastic Cloud Hosted/Serverless. And even in those scenarios, we expect that some customers might have network restrictions that might not allow the flags to evaluate. The fallback value must provide a non-broken experience to users.

⚠️Feature Flags are considered dynamic configuration and cannot be used for settings that require restarting Kibana. One example of invalid use cases are settings used during the setup lifecycle of the plugin, such as settings that define if an HTTP route is registered or not. Instead, you should always register the route, and return 404 - Not found in the route handler if the feature flag returns a disabled state.

In summary, Feature flagging is best suited for

• Phased rollout of the features (either to a specific customer, a subset of customers, or a % of overall users)
• Feature experimentation

Feature flagging is NOT suitable for

• Applying feature availability for licensing and/or tiers
• Restricting or applying customer entitlement to specific GA features

For a code example, refer to the Feature Flags Example plugin

Key concepts

Feature Flag

A config key that defines a set of variations that will be resolved at runtime when the app calls the evaluation APIs. The variation is decided at runtime based on static binary state (ON -> variationA vs. OFF -> variationB), or via evaluation/segmentation rules.

Variations

All the potential values that a feature flag can return based on the evaluation rules. A feature flag should define at least 2 variations: the ON and the OFF states. The typical use case sets the OFF state to match the fallback value provided to the evaluation APIs, although it's not a hard requirement and Kibana contributors might require special configurations.

Evaluation/Segmentation rules

Set of rules used to evaluate the variation to resolve, based on the evaluation context provided by the app.

The rules can vary from a percentage rollout per evaluation context, or more complex IF...THEN filters and clauses.

Refer to the Evaluation Context guide's examples for some typical scenarios.

Evaluation Context

Kibana reports a set of properties specific to each ECH deployment/Serverless project to help define the segmentation rules. A list of the currently reported context properties can be found in the Evaluation Context guide.

Feature Flag Code References

In the Kibana repo we run a GH Action that links existing Feature Flags to their code references. This helps us figure out which flags have been removed from the code and, which ones are still being used.

:information_source: New flags might take a few moments to be updated with their code references. The job runs on every commit to the main branch of the Kibana repository, so the wait can take from a few minutes to a few hours, depending on the Kibana repo's activity.

Registering a feature flag

At the moment, we follow a manual process to manage our feature flags. Refer to this repo to learn more about our current internal process. Our goal is to achieve a gitops approach eventually. But, at the moment, it's not available.

Deprecation/removal strategy

When your code doesn't use the feature flag anymore, it is recommended to clean up the feature flags. There are a few considerations to take into account when performing this clean-up:

1. Always deprecate first, remove after
2. When to remove?

Always deprecate first, remove after

Just because the CI syncs the state of main to our feature flag provider, there is a high probability that the previous version of the code that still relied on the feature flag is still running out there.

For that reason, the recommendation is to always deprecate before removing the flags. This will keep evaluating the flags, according to the segmentation rules configured for the flag.

When to remove?

After deprecation, we need to consider when it's safe to remove the flag. There are different scenarios that come with different recommendations:

• The segmentation rules of my flag are set up to return the fallback value 100% of the time: it should be safe to remove the flag at any time.
• My flag only made it to Serverless (it never made it to Elastic Cloud Hosted): it should be safe to remove the flag after 2 releases have been rolled out (roughly 2-3 weeks later). This is to ensure that all Serverless projects have been upgraded and that we won't need to rollback to the previous version.
• My flag made it to Elastic Cloud Hosted: if we want to remove the flag, we should approach the affected customers to fix the expected values via config overrides.

In general, the recommendation is to check our telemetry to validate the usage of our flags.

Evaluating feature flags

This service provides 2 ways to evaluate your feature flags, depending on the use case:

1. Single evaluation: performs the evaluation once, and doesn't react to updates. These APIs are synchronous in the browser, and asynchronous in the server.
2. Observed evaluation: observes the flag for any changes so that the code can adapt. These APIs return an RxJS observable.

Also, the APIs are typed, so you need to use the appropriate API depending on the variationType you defined your flag:

Request handler context

Additionally, to make things easier in our HTTP handlers, the Single evaluation APIs are available as part of the core context provided to the handlers:

async (context, request, response) => {
  const { featureFlags } = await context.core;
  return response.ok({
    body: {
      number: await featureFlags.getNumberValue('myPlugin.exampleNumber', 1),
    },
  });
}

Extending the evaluation context

The <DocLink id="kibCloudExperimentsPlugin" section="evaluation-context" text="current evaluation context"/> should have enough information to declare the segmentation rules for your feature flags. However, if your use case requires additional context, feel free to call the API core.featureFlags.setContext() from your plugin.

At the moment, we use 2 levels of context: kibana and organization that we can use for segmentation purposes at different levels. By default, the API appends the context to the kibana scope. If you need to extend the organization scope, make sure to add kind: 'organization' to the object provided to the setContext API.

Config overrides

To help with testing, and to provide an escape hatch in cases where the flag evaluation is not behaving as intended, the Feature Flags Service provides a way to force the values of a feature flag without attempting to resolve it via the provider. In the kibana.yml, the following config sets the overrides:

feature_flags.overrides:
  myPlugin.myFeatureFlag: 'my-forced-value'

[!WARNING] There is no validation regarding the variations nor the type of the flags. Use these overrides with caution.

Dynamic config

When running in our test environments, the overrides can be updated without restarting Kibana via the HTTP PUT kbn:/internal/core/_settings:

PUT kbn:/internal/core/_settings
{
  "feature_flags.overrides": {
    "my-feature-flag": "my-forced-value"
  }
}

[!NOTE] The PUT kbn:/internal/core/_settings endpoint is only available in the test environments. To enable it, add the following to your kibana.yml:

yamlCopy

coreApp.allowDynamicConfigOverrides: true

Usage in Cloud

Feature flags aren't whitelisted in Cloud, meaning that in production environments, users have to go through Support. Support sets feature flags as user setting overrides following a standard process for enabling non-whitelisted settings.