Skip to content
This repository was archived by the owner on Aug 14, 2024. It is now read-only.

Commit aa3bc00

Browse files
authored
Update flagpole documentation for single-tenant (#1344)
Documentation changes to go with getsentry/getsentry#14867
1 parent 1f5b6dd commit aa3bc00

File tree

1 file changed

+23
-13
lines changed

1 file changed

+23
-13
lines changed

src/docs/feature-flags/flagpole.mdx

Lines changed: 23 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
# Flagpole
2+
23
Flagpole is Sentry's internal, options-backed feature flagging library.
34

45
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:
9697
: The inverse of `equals`, evaluates to `True` if the context property value does not match the provided value.
9798

9899
## Evaluation Contexts
100+
99101
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.
100102

101103
### Context Builders
104+
102105
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.
103106

104107
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(
178181
feature.<feature_scope>:<feature_name>
179182
```
180183

181-
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.
184+
<Alert level="info">
185+
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.
186+
If this happens, make sure to rerun the options deployment once all environments have been updated to ensure your feature is active.
187+
</Alert>
182188

183189
Once the option change is deployed, the feature checks will immediately be active in all environments and regions.
184190

185-
_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.
191+
## Using flagpole in single-tenants
192+
193+
To allow your flagpole feature configuration to be used in single-tenant
194+
environments, you'll need to add your feature name to the
195+
`flagpole.allowed_features` list for each tenant. For example, in
196+
`options/regions/acme.yml` add the following:
197+
198+
```yaml
199+
options:
200+
flagpole.allowed_features: ["organizations:is_sentry"]
201+
```
202+
203+
You can also use the `sentry_singletenant` and `sentry_region` context values in
204+
your feature conditions as required.
186205

187-
If this happens, make sure to rerun the options deployment once all environments have been updated to ensure your feature is active.
188206

189207
## Testing a Flagpole feature locally
208+
190209
You can test a flagpole feature flag locally using the GetSentry devserver.
191210
Because the feature handler for Flagpole only exists in GetSentry, it's not possible
192211
to test flagpole features using the Sentry devserver at this time.
193212

194-
Start by creating a new yaml file containing your feature config. The config
195-
file should contain a top-level `options` object containing your feature object,
196-
and a `flagpole.flagpole_only_features` list option containing the name of the
197-
feature you want to test, without the `feature.` prefix:
213+
Start by creating a new yaml file containing your feature config:
198214
```yaml
199215
options:
200-
flagpole.flagpole_only_features: ['organizations:is_sentry']
201-
202216
'feature.organizations:is_sentry':
203217
created_at: '2024-06-01T00:00:00.000000'
204218
enabled: false
@@ -213,10 +227,6 @@ options:
213227
rollout: 100
214228
```
215229

216-
_Note:_ The `flagpole_only_features` option will only be required while
217-
Flagpole is actively being rolled out.
218-
219-
220230
You can push your feature option to your local devserver using the following `getsentry` CLI command:
221231

222232
```bash

0 commit comments

Comments
 (0)