From aa3bc003e3304a8c2055dbecde1178922425e4ec Mon Sep 17 00:00:00 2001 From: Mark Story Date: Wed, 14 Aug 2024 12:56:58 -0400 Subject: [PATCH] Update flagpole documentation for single-tenant (#1344) Documentation changes to go with getsentry/getsentry#14867 --- src/docs/feature-flags/flagpole.mdx | 36 ++++++++++++++++++----------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/src/docs/feature-flags/flagpole.mdx b/src/docs/feature-flags/flagpole.mdx index b74cbe7840..6aacc505da 100644 --- a/src/docs/feature-flags/flagpole.mdx +++ b/src/docs/feature-flags/flagpole.mdx @@ -1,4 +1,5 @@ # Flagpole + Flagpole is Sentry's internal, options-backed feature flagging library. Features are defined in the [`sentry-options-automator`](https://github.com/getsentry/sentry-options-automator) repository as yaml objects within the [`options/defaults/flagpole.yml`](https://github.com/getsentry/sentry-options-automator/blob/main/options/default/flagpole.yml) file. @@ -96,9 +97,11 @@ Flagpole currently supports the following `operator` types: : The inverse of `equals`, evaluates to `True` if the context property value does not match the provided value. ## Evaluation Contexts + When a feature flag is checked, the caller must provide one or more entity objects for the feature handler to match against. These objects are used to construct an `EvaluationContext`, which is essentially a flat dictionary of keys and primitive values. This context is passed to each feature, which provides this context to each segment and condition to enforce whether the feature should be enabled. ### Context Builders + Each evaluation context is built up in stages via a [`ContextBuilder`](https://github.com/getsentry/sentry/blob/3cbf73a389a4ea006cbad9d8c4b8073effe09393/src/flagpole/evaluation_context.py#L54) object. Each context builder consists of a list of context transformers, which are responsible for creating individual slices of the larger evaluation context. @@ -178,27 +181,38 @@ features.add( feature.: ``` -3. Add the feature name to the `flagpole.flagpole_only_features` list in sentry-options-automator's default [`app.yaml`](https://github.com/getsentry/sentry-options-automator/blob/483737d45dbc68253e926c3f860b5ae33111697b/options/default/app.yaml#L219) file, omitting the `feature.` prefix. + + The feature config should not be merged until the registration commit in step 1 has been fully deployed to all target environments. This is because Options Automator will fail to push options to any environments missing the option registration. + If this happens, make sure to rerun the options deployment once all environments have been updated to ensure your feature is active. + Once the option change is deployed, the feature checks will immediately be active in all environments and regions. -_Note:_ The feature config should not be merged until the registration commit in step 1 has been fully deployed to all target environments. This is because Options Automator will fail to push options to any environments missing the option registration. +## Using flagpole in single-tenants + +To allow your flagpole feature configuration to be used in single-tenant +environments, you'll need to add your feature name to the +`flagpole.allowed_features` list for each tenant. For example, in +`options/regions/acme.yml` add the following: + +```yaml +options: + flagpole.allowed_features: ["organizations:is_sentry"] +``` + +You can also use the `sentry_singletenant` and `sentry_region` context values in +your feature conditions as required. -If this happens, make sure to rerun the options deployment once all environments have been updated to ensure your feature is active. ## Testing a Flagpole feature locally + You can test a flagpole feature flag locally using the GetSentry devserver. Because the feature handler for Flagpole only exists in GetSentry, it's not possible to test flagpole features using the Sentry devserver at this time. -Start by creating a new yaml file containing your feature config. The config -file should contain a top-level `options` object containing your feature object, -and a `flagpole.flagpole_only_features` list option containing the name of the -feature you want to test, without the `feature.` prefix: +Start by creating a new yaml file containing your feature config: ```yaml options: - flagpole.flagpole_only_features: ['organizations:is_sentry'] - 'feature.organizations:is_sentry': created_at: '2024-06-01T00:00:00.000000' enabled: false @@ -213,10 +227,6 @@ options: rollout: 100 ``` -_Note:_ The `flagpole_only_features` option will only be required while -Flagpole is actively being rolled out. - - You can push your feature option to your local devserver using the following `getsentry` CLI command: ```bash