debian-mirror-gitlab/doc/administration/feature_flags.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

172 lines
5.9 KiB
Markdown
Raw Normal View History

2020-05-24 23:13:21 +05:30
---
2022-07-23 23:45:48 +05:30
stage: Systems
2021-11-18 22:05:49 +05:30
group: Distribution
2022-11-25 23:54:43 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2020-05-24 23:13:21 +05:30
description: "GitLab administrator: enable and disable GitLab features deployed behind feature flags"
---
2021-03-11 19:13:27 +05:30
# Enable and disable GitLab features deployed behind feature flags **(FREE SELF)**
2020-05-24 23:13:21 +05:30
GitLab adopted [feature flags strategies](../development/feature_flags/index.md)
to deploy features in an early stage of development so that they can be
incrementally rolled out.
Before making them permanently available, features can be deployed behind
2021-04-29 21:17:54 +05:30
flags for a [number of reasons](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#when-to-use-feature-flags), such as:
2020-05-24 23:13:21 +05:30
- To test the feature.
- To get feedback from users and customers while in an early stage of the development of the feature.
- To evaluate users adoption.
2021-02-22 17:27:13 +05:30
- To evaluate how it impacts the performance of GitLab.
2020-05-24 23:13:21 +05:30
- To build it in smaller pieces throughout releases.
Features behind flags can be gradually rolled out, typically:
1. The feature starts disabled by default.
1. The feature becomes enabled by default.
1. The feature flag is removed.
2022-05-07 20:08:51 +05:30
These features can be enabled and disabled to allow or prevent users from using
2022-11-25 23:54:43 +05:30
them. It can be done by GitLab administrators with access to the
[Rails console](#how-to-enable-and-disable-features-behind-flags) or the
[Feature flags API](../api/features.md).
2020-05-24 23:13:21 +05:30
2021-10-27 15:23:28 +05:30
When you disable a feature flag, the feature is hidden from users and all of the functionality is turned off.
For example, data is not recorded and services do not run.
2020-05-24 23:13:21 +05:30
If you used a certain feature and identified a bug, a misbehavior, or an
2020-06-23 00:09:42 +05:30
error, it's very important that you [**provide feedback**](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Docs%20-%20feature%20flag%20feedback%3A%20Feature%20Name&issue[description]=Describe%20the%20problem%20you%27ve%20encountered.%0A%0A%3C!--%20Don%27t%20edit%20below%20this%20line%20--%3E%0A%0A%2Flabel%20~%22docs%5C-comments%22%20) to GitLab as soon
2020-05-24 23:13:21 +05:30
as possible so we can improve or fix it while behind a flag. When you upgrade
2022-04-04 11:22:00 +05:30
GitLab, the feature flag status may change.
2020-05-24 23:13:21 +05:30
2021-10-27 15:23:28 +05:30
## Risks when enabling features still in development
Features that are disabled by default may change or be removed without notice in a future version of GitLab.
2021-12-11 22:18:48 +05:30
Data corruption, stability degradation, performance degradation, or security issues might occur if
2021-10-27 15:23:28 +05:30
you enable a feature that's disabled by default. Problems caused by using a default
disabled feature aren't covered by GitLab support, unless you were directed by GitLab
to enable the feature.
2021-12-11 22:18:48 +05:30
Security issues found in features that are disabled by default are patched in regular releases
and do not follow our regular [maintenance policy](../policy/maintenance.md#security-releases)
with regards to backporting the fix.
2021-10-27 15:23:28 +05:30
## Risks when disabling released features
In most cases, the feature flag code is removed in a future version of GitLab.
If and when that occurs, from that point onward you can't keep the feature in a disabled state.
2020-05-24 23:13:21 +05:30
## How to enable and disable features behind flags
Each feature has its own flag that should be used to enable and disable it.
The documentation of each feature behind a flag includes a section informing
the status of the flag and the command to enable or disable it.
### Start the GitLab Rails console
2022-08-13 15:12:31 +05:30
The first thing you must do to enable or disable a feature behind a flag is to
2020-05-24 23:13:21 +05:30
start a session on GitLab Rails console.
For Omnibus installations:
```shell
sudo gitlab-rails console
```
For installations from the source:
```shell
sudo -u git -H bundle exec rails console -e production
```
2021-01-03 14:25:43 +05:30
For details, see [starting a Rails console session](operations/rails_console.md#starting-a-rails-console-session).
2020-05-24 23:13:21 +05:30
### Enable or disable the feature
2022-08-13 15:12:31 +05:30
After the Rails console session has started, run the `Feature.enable` or
2020-05-24 23:13:21 +05:30
`Feature.disable` commands accordingly. The specific flag can be found
in the feature's documentation itself.
To enable a feature, run:
```ruby
Feature.enable(:<feature flag>)
```
2021-01-03 14:25:43 +05:30
Example, to enable a fictional feature flag named `my_awesome_feature`:
2020-05-24 23:13:21 +05:30
```ruby
2021-01-03 14:25:43 +05:30
Feature.enable(:my_awesome_feature)
2020-05-24 23:13:21 +05:30
```
To disable a feature, run:
```ruby
Feature.disable(:<feature flag>)
```
2021-01-03 14:25:43 +05:30
Example, to disable a fictional feature flag named `my_awesome_feature`:
2020-05-24 23:13:21 +05:30
```ruby
2021-01-03 14:25:43 +05:30
Feature.disable(:my_awesome_feature)
2020-05-24 23:13:21 +05:30
```
2020-06-23 00:09:42 +05:30
Some feature flags can be enabled or disabled on a per project basis:
```ruby
Feature.enable(:<feature flag>, Project.find(<project id>))
```
2023-01-13 00:05:48 +05:30
For example, to enable the `:my_awesome_feature` feature flag for project `1234`:
2020-06-23 00:09:42 +05:30
```ruby
2023-01-13 00:05:48 +05:30
Feature.enable(:my_awesome_feature, Project.find(1234))
2020-07-28 23:09:34 +05:30
```
2022-08-13 15:12:31 +05:30
`Feature.enable` and `Feature.disable` always return `true`, even if the application doesn't use the flag:
2020-07-28 23:09:34 +05:30
```ruby
2021-01-03 14:25:43 +05:30
irb(main):001:0> Feature.enable(:my_awesome_feature)
2022-08-13 15:12:31 +05:30
=> true
2020-07-28 23:09:34 +05:30
```
2022-04-04 11:22:00 +05:30
When the feature is ready, GitLab removes the feature flag, and the option for
enabling and disabling it no longer exists. The feature becomes available in all instances.
### Check if a feature flag is enabled
To check if a flag is enabled or disabled, use `Feature.enabled?` or `Feature.disabled?`.
For example, for a feature flag named `my_awesome_feature` that is already enabled:
2020-07-28 23:09:34 +05:30
```ruby
2021-01-03 14:25:43 +05:30
Feature.enabled?(:my_awesome_feature)
2020-07-28 23:09:34 +05:30
=> true
2021-01-03 14:25:43 +05:30
Feature.disabled?(:my_awesome_feature)
2020-07-28 23:09:34 +05:30
=> false
2020-06-23 00:09:42 +05:30
```
2021-09-04 01:27:46 +05:30
When the feature is ready, GitLab removes the feature flag, and the option for
enabling and disabling it no longer exists. The feature becomes available in all instances.
2022-04-04 11:22:00 +05:30
### View set feature flags
You can view all GitLab administrator set feature flags:
```ruby
Feature.all
=> [#<Flipper::Feature:198220 name="my_awesome_feature", state=:on, enabled_gate_names=[:boolean], adapter=:memoizable>]
2022-10-11 01:57:18 +05:30
# Nice output
Feature.all.map {|f| [f.name, f.state]}
2022-04-04 11:22:00 +05:30
```
### Unset feature flag
2022-08-13 15:12:31 +05:30
You can unset a feature flag so that GitLab falls back to the current defaults for that flag:
2022-04-04 11:22:00 +05:30
```ruby
Feature.remove(:my_awesome_feature)
=> true
```