Skip to content

G
gitlab-ce
Commit d2360340 authored by Amy Qualls's avatar Amy Qualls Committed by Clement Ho
Browse files
Options

Move main Operations page to new home 

The /user/project/operations directory is moving to /operations,
and I need to start the move by moving the index page to the new
location.
parent da0d7017
Hide whitespace changes
Inline Side-by-side
Showing with 324 additions and 319 deletions
doc/api/feature_flag_specs.md
View file @ d2360340
......@@ -13,7 +13,7 @@ This API is deprecated and [scheduled for removal in GitLab 14.0](https://gitlab
The API for creating, updating, reading and deleting Feature Flag Specs.
Automation engineers benefit from this API by being able to modify Feature Flag Specs without accessing user interface.
To manage the [Feature Flag](../user/project/operations/feature_flags.md) resources via public API, please refer to the [Feature Flags API](feature_flags.md) document.
To manage the [Feature Flag](../operations/feature_flags.md) resources via public API, please refer to the [Feature Flags API](feature_flags.md) document.
Users with Developer or higher [permissions](../user/permissions.md) can access Feature Flag Specs API.
......@@ -166,7 +166,7 @@ POST /projects/:id/feature_flags/:name/scopes
| `name` | string | yes | The name of the feature flag. |
| `environment_scope` | string | yes | The [environment spec](../ci/environments/index.md#scoping-environments-with-specs) of the feature flag. |
| `active` | boolean | yes | Whether the spec is active. |
| `strategies` | JSON | yes | The [strategies](../user/project/operations/feature_flags.md#feature-flag-strategies) of the feature flag spec. |
| `strategies` | JSON | yes | The [strategies](../operations/feature_flags.md#feature-flag-strategies) of the feature flag spec. |
```shell
curl "https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace/scopes" \
......@@ -249,7 +249,7 @@ PUT /projects/:id/feature_flags/:name/scopes/:environment_scope
| `name` | string | yes | The name of the feature flag. |
| `environment_scope` | string | yes | The URL-encoded [environment spec](../ci/environments/index.md#scoping-environments-with-specs) of the feature flag. |
| `active` | boolean | yes | Whether the spec is active. |
| `strategies` | JSON | yes | The [strategies](../user/project/operations/feature_flags.md#feature-flag-strategies) of the feature flag spec. |
| `strategies` | JSON | yes | The [strategies](../operations/feature_flags.md#feature-flag-strategies) of the feature flag spec. |
```shell
curl "https://gitlab.example.com/api/v4/projects/1/feature_flags/new_live_trace/scopes/production" \
......
doc/api/feature_flags.md
View file @ d2360340
......@@ -9,10 +9,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5.
NOTE: **Note**
This API is behind a [feature flag](../user/project/operations/feature_flags.md#enable-or-disable-feature-flag-strategies).
This API is behind a [feature flag](../operations/feature_flags.md#enable-or-disable-feature-flag-strategies).
If this flag is not enabled in your environment, you can use the [legacy feature flags API](feature_flags_legacy.md).
API for accessing resources of [GitLab Feature Flags](../user/project/operations/feature_flags.md).
API for accessing resources of [GitLab Feature Flags](../operations/feature_flags.md).
Users with Developer or higher [permissions](../user/permissions.md) can access Feature Flag API.
......@@ -146,7 +146,7 @@ POST /projects/:id/feature_flags
| `name` | string | yes | The name of the feature flag. |
| `version` | string | yes | The version of the feature flag. Must be `new_version_flag`. Omit or set to `legacy_flag` to create a [Legacy Feature Flag](feature_flags_legacy.md). |
| `description` | string | no | The description of the feature flag. |
| `strategies` | JSON | no | The feature flag [strategies](../user/project/operations/feature_flags.md#feature-flag-strategies). |
| `strategies` | JSON | no | The feature flag [strategies](../operations/feature_flags.md#feature-flag-strategies). |
| `strategies:name` | JSON | no | The strategy name. |
| `strategies:parameters` | JSON | no | The strategy parameters. |
| `strategies:scopes` | JSON | no | The scopes for the strategy. |
......@@ -204,7 +204,7 @@ PUT /projects/:id/feature_flags/:name
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `name` | string | yes | The name of the feature flag. |
| `description` | string | no | The description of the feature flag. |
| `strategies` | JSON | no | The feature flag [strategies](../user/project/operations/feature_flags.md#feature-flag-strategies). |
| `strategies` | JSON | no | The feature flag [strategies](../operations/feature_flags.md#feature-flag-strategies). |
| `strategies:id` | JSON | no | The feature flag strategy id. |
| `strategies:name` | JSON | no | The strategy name. |
| `strategies:parameters` | JSON | no | The strategy parameters. |
......
doc/api/feature_flags_legacy.md
View file @ d2360340
......@@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
CAUTION: **Deprecation**
This API is deprecated and [scheduled for removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369). Use [this API](feature_flags.md) instead.
API for accessing resources of [GitLab Feature Flags](../user/project/operations/feature_flags.md).
API for accessing resources of [GitLab Feature Flags](../operations/feature_flags.md).
Users with Developer or higher [permissions](../user/permissions.md) can access Feature Flag API.
......@@ -166,7 +166,7 @@ POST /projects/:id/feature_flags
| `scopes` | JSON | no | The feature flag specs of the feature flag. |
| `scopes:environment_scope` | string | no | The environment spec. |
| `scopes:active` | boolean | no | Whether the spec is active. |
| `scopes:strategies` | JSON | no | The [strategies](../user/project/operations/feature_flags.md#feature-flag-strategies) of the feature flag spec. |
| `scopes:strategies` | JSON | no | The [strategies](../operations/feature_flags.md#feature-flag-strategies) of the feature flag spec. |
```shell
curl https://gitlab.example.com/api/v4/projects/1/feature_flags \
......
doc/ci/README.md
View file @ d2360340
......@@ -139,7 +139,7 @@ Its feature set is listed on the table below according to DevOps stages.
| [Building Docker images](docker/using_docker_build.md) | Maintain Docker-based projects using GitLab CI/CD. |
| [Canary Deployments](../user/project/canary_deployments.md) **(PREMIUM)** | Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature. |
| [Deploy Boards](../user/project/deploy_boards.md) **(PREMIUM)** | Check the current health and status of each CI/CD environment running on Kubernetes. |
| [Feature Flags](../user/project/operations/feature_flags.md) **(PREMIUM)** | Deploy your features behind Feature Flags. |
| [Feature Flags](../operations/feature_flags.md) **(PREMIUM)** | Deploy your features behind Feature Flags. |
| [GitLab Pages](../user/project/pages/index.md) | Deploy static websites. |
| [GitLab Releases](../user/project/releases/index.md) | Add release notes to Git tags. |
| [Review Apps](review_apps/index.md) | Configure GitLab CI/CD to preview code changes. |
......
doc/ci/introduction/index.md
View file @ d2360340
......@@ -202,7 +202,7 @@ according to each stage (Verify, Package, Release).
- Continuous Delivery, manually click to deploy your app to production.
- Deploy static websites with [GitLab Pages](../../user/project/pages/index.md).
- Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature with [Canary Deployments](../../user/project/canary_deployments.md). **(PREMIUM)**
- Deploy your features behind [Feature Flags](../../user/project/operations/feature_flags.md). **(PREMIUM)**
- Deploy your features behind [Feature Flags](../../operations/feature_flags.md). **(PREMIUM)**
- Add release notes to any Git tag with [GitLab Releases](../../user/project/releases/index.md).
- View of the current health and status of each CI environment running on Kubernetes with [Deploy Boards](../../user/project/deploy_boards.md). **(PREMIUM)**
- Deploy your application to a production environment in a Kubernetes cluster with [Auto Deploy](../../topics/autodevops/stages.md#auto-deploy).
......
doc/development/documentation/styleguide.md
View file @ d2360340
......@@ -770,7 +770,7 @@ Relative linking enables crosslinks to work:
- in Review Apps, local previews, and `/help`.
- when working on the docs locally, so you can verify that they work as early as possible in the process.
- within the GitLab UI when browsing doc files in their respective repositories. For example, the links displayed at <https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md>.
- within the GitLab UI when browsing doc files in their respective repositories. For example, the links displayed at `https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md`.
To link to internal documentation:
......
doc/development/feature_flags/index.md
View file @ d2360340
# Feature flags in development of GitLab
[Feature Flags](../../user/project/operations/feature_flags.md)
[Feature Flags](../../operations/feature_flags.md)
can be used to gradually roll out changes, be
it a new feature, or a performance improvement. By using feature flags, we can
comfortably measure the impact of our changes, while still being able to easily
......
doc/development/feature_flags/process.md
View file @ d2360340
......@@ -4,7 +4,7 @@
This document only covers feature flags used in the development of GitLab
itself. Feature flags in deployed user applications can be found at
[Feature Flags feature documentation](../../user/project/operations/feature_flags.md).
[Feature Flags feature documentation](../../operations/feature_flags.md).
## Feature flags in GitLab development
......
doc/operations/README.md deleted 100644 → 0
View file @ da0d7017
---
redirect_to: '../administration/operations/index.md'
---
This document was moved to [another location](../administration/operations/index.md).
doc/operations/feature_flags.md 0 → 100644
View file @ d2360340
---
stage: Release
group: Progressive Delivery
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---
# Feature Flags **(PREMIUM)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7433) in GitLab 11.4.
With Feature Flags, you can deploy your application's new features to production in smaller batches.
You can toggle a feature on and off to subsets of users, helping you achieve Continuous Delivery.
Feature flags help reduce risk, allowing you to do controlled testing, and separate feature
delivery from customer launch.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an example of feature flags in action, see [GitLab for Deploys, Feature Flags, and Error Tracking](https://www.youtube.com/embed/5tw2p6lwXxo).
## How it works
GitLab uses [Unleash](https://github.com/Unleash/unleash), a feature
toggle service.
By enabling or disabling a flag in GitLab, your application
can determine which features to enable or disable.
You can create feature flags in GitLab and use the API from your application
to get the list of feature flags and their statuses. The application must be configured to communicate
with GitLab, so it's up to developers to use a compatible client library and
[integrate the feature flags in your app](#integrate-feature-flags-with-your-application).
## Create a feature flag
To create and enable a feature flag:
1. Navigate to your project's **Operations > Feature Flags**.
1. Click the **New feature flag** button.
1. Enter a name that starts with a letter and contains only lowercase letters, digits, underscores (`_`),
or dashes (`-`), and does not end with a dash (`-`) or underscore (`_`).
1. Enter a description (optional, 255 characters max).
1. Enter details about how the flag should be applied:
- In GitLab 13.0 and earlier, add **Environment specs**. For each environment,
include the **Status** (default enabled) and [**Rollout strategy**](#rollout-strategy-legacy)
(defaults to **All users**).
- In GitLab 13.1 and later, add Feature Flag [**Strategies**](#feature-flag-strategies).
For each strategy, include the **Type** (defaults to [**All users**](#all-users))
and **Environments** (defaults to all environments).
1. Click **Create feature flag**.
You can change these settings by clicking the **{pencil}** (edit) button
next to any feature flag in the list.
## Rollout strategy (legacy)
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2.
In GitLab 13.0 and earlier, the **Rollout strategy** setting affects which users will experience
the feature as enabled. Choose the percentage of users that the feature will be enabled
for. The rollout strategy will have no effect if the environment spec is disabled.
It can be set to:
- All users
- [Percent rollout (logged in users)](#percent-rollout-logged-in-users)
- Optionally, you can click the **Include additional user IDs** checkbox and add a list
of specific users IDs to enable the feature for.
- [User IDs](#user-ids)
## Feature flag strategies
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35555) in GitLab 13.0.
> - It's deployed behind a feature flag, disabled by default.
> - It's enabled on GitLab.com.
> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-feature-flag-strategies). **(CORE ONLY)**
You can apply a feature flag strategy across multiple environments, without defining
the strategy multiple times.
GitLab Feature Flags use [Unleash](https://unleash.github.io) as the feature flag
engine. In Unleash, there are [strategies](https://unleash.github.io/docs/activation_strategy)
for granular feature flag controls. GitLab Feature Flags can have multiple strategies,
and the supported strategies are:
- [All users](#all-users)
- [Percent rollout (logged in users)](#percent-rollout-logged-in-users)
- [User IDs](#user-ids)
- [List](#list)
Strategies can be added to feature flags when [creating a feature flag](#create-a-feature-flag),
or by editing an existing feature flag after creation by navigating to **Operations > Feature Flags**
and clicking **{pencil}** (edit).
### All users
Enables the feature for all users. It uses the [`default`](https://unleash.github.io/docs/activation_strategy#default)
Unleash activation strategy.
### Percent rollout (logged in users)
Enables the feature for a percentage of authenticated users. It uses the
[`gradualRolloutUserId`](https://unleash.github.io/docs/activation_strategy#gradualrolloutuserid)
Unleash activation strategy.
For example, set a value of 15% to enable the feature for 15% of authenticated users.
The rollout percentage can be from 0% to 100%.
CAUTION: **Caution:**
If this strategy is selected, then the Unleash client **must** be given a user
ID for the feature to be enabled. See the [Ruby example](#ruby-application-example) below.
### User IDs
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2. [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/34363) to be defined per environment in GitLab 12.6.
Enables the feature for a list of target users. It is implemented
using the Unleash [`userWithId`](https://unleash.github.io/docs/activation_strategy#userwithid)
activation strategy.
Enter user IDs as a comma-separated list of values. For example,
`user@example.com, user2@example.com`, or `username1,username2,username3`, and so on.
CAUTION: **Caution:**
The Unleash client **must** be given a user ID for the feature to be enabled for
target users. See the [Ruby example](#ruby-application-example) below.
### List
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35930) in GitLab 13.1.
Enables the feature for lists of users created with the [Feature Flag User List API](../api/feature_flag_user_lists.md).
Similar to [User IDs](#user-ids), it uses the Unleash [`userWithId`](https://unleash.github.io/docs/activation_strategy#userwithid)
activation strategy.
### Enable or disable feature flag strategies
This feature is under development, but is ready for testing. It's
deployed behind a feature flag that is **disabled by default**.
[GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md)
can enable it for your instance.
To enable it:
```ruby
Feature.enable(:feature_flags_new_version)
```
To disable it:
```ruby
Feature.disable(:feature_flags_new_version)
```
## Disable a feature flag for a specific environment
In [GitLab 13.0 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/8621),
to disable a feature flag for a specific environment:
1. Navigate to your project's **Operations > Feature Flags**.
1. For the feature flag you want to disable, click the Pencil icon.
1. To disable the flag:
- In GitLab 13.0 and earlier: Slide the Status toggle for the environment. Or, to delete the
environment spec, on the right, click the **Remove (X)** icon.
- In GitLab 13.1 and later: For each strategy it applies to, under **Environments**, delete the environment.
1. Click **Save changes**.
## Disable a feature flag for all environments
To disable a feature flag for all environments:
1. Navigate to your project's **Operations > Feature Flags**.
1. For the feature flag you want to disable, slide the Status toggle to **Disabled**.
The feature flag is displayed on the **Disabled** tab.
## Integrate feature flags with your application
To use feature flags with your application, get access credentials from GitLab.
Then prepare your application with a client library.
### Get access credentials
To get the access credentials that your application needs to communicate with GitLab:
1. Navigate to your project's **Operations > Feature Flags**.
1. Click the **Configure** button to view the following:
- **API URL**: URL where the client (application) connects to get a list of feature flags.
- **Instance ID**: Unique token that authorizes the retrieval of the feature flags.
- **Application name**: The name of the running environment. For instance,
if the application runs for a production server, the application name would be
`production` or similar. This value is used for the environment spec evaluation.
NOTE: **Note:**
The meaning of these fields might change over time. For example, we are not sure
if **Instance ID** will be single token or multiple tokens, assigned to the
**Environment**. Also, **Application name** could describe the version of
application instead of the running environment.
### Choose a client library
GitLab implements a single backend that is compatible with Unleash clients.
With the Unleash client, developers can define, in the application code, the default values for flags.
Each feature flag evaluation can express the desired outcome if the flag isn't present in the
provided configuration file.
Unleash currently [offers many SDKs for various languages and frameworks](https://github.com/Unleash/unleash#client-implementations).
### Feature flags API information
For API content, see:
- [Feature Flags API](../api/feature_flags.md)
- [Feature Flag Specs API](../api/feature_flag_specs.md) (Deprecated and [scheduled for removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369).)
- [Feature Flag User Lists API](../api/feature_flag_user_lists.md)
- [Legacy Feature Flags API](../api/feature_flags_legacy.md)
### Golang application example
Here's an example of how to integrate feature flags in a Golang application:
```golang
package main
import (
"io"
"log"
"net/http"
"github.com/Unleash/unleash-client-go"
)
type metricsInterface struct {
}
func init() {
unleash.Initialize(
unleash.WithUrl("https://gitlab.com/api/v4/feature_flags/unleash/42"),
unleash.WithInstanceId("29QmjsW6KngPR5JNPMWx"),
unleash.WithAppName("production"),
unleash.WithListener(&metricsInterface{}),
)
}
func helloServer(w http.ResponseWriter, req *http.Request) {
if unleash.IsEnabled("my_feature_name") {
io.WriteString(w, "Feature enabled\n")
} else {
io.WriteString(w, "hello, world!\n")
}
}
func main() {
http.HandleFunc("/", helloServer)
log.Fatal(http.ListenAndServe(":8080", nil))
}
```
### Ruby application example
Here's an example of how to integrate feature flags in a Ruby application.
The Unleash client is given a user ID for use with a **Percent rollout (logged in users)** rollout strategy or a list of **Target Users**.
```ruby
#!/usr/bin/env ruby
require 'unleash'
require 'unleash/context'
unleash = Unleash::Client.new({
url: 'http://gitlab.com/api/v4/feature_flags/unleash/42',
app_name: 'production',
instance_id: '29QmjsW6KngPR5JNPMWx'
})
unleash_context = Unleash::Context.new
# Replace "123" with the id of an authenticated user.
# Note that the context's user id must be a string:
# https://unleash.github.io/docs/unleash_context
unleash_context.user_id = "123"
if unleash.is_enabled?("my_feature_name", unleash_context)
puts "Feature enabled"
else
puts "hello, world!"
end
```
doc/operations/index.md 0 → 100644
View file @ d2360340
# Project operations
GitLab provides a variety of tools to help operate and maintain
your applications:
- Collect [Prometheus metrics](../user/project/integrations/prometheus_library/index.md).
- Deploy to different [environments](../ci/environments/index.md).
- Connect your project to a [Kubernetes cluster](../user/project/clusters/index.md).
- Manage your infrastructure with [Infrastructure as Code](../user/infrastructure/index.md) approaches.
- Discover and view errors generated by your applications with [Error Tracking](../user/project/operations/error_tracking.md).
- Create, toggle, and remove [Feature Flags](feature_flags.md). **(PREMIUM)**
- [Trace](../user/project/operations/tracing.md) the performance and health of a deployed application. **(ULTIMATE)**
- Change the [settings of the Monitoring Dashboard](../user/project/operations/dashboard_settings.md).
doc/user/project/index.md
View file @ d2360340
......@@ -78,7 +78,7 @@ When you create a project in GitLab, you'll have access to a large number of
timeout (defines the maximum amount of time in minutes that a job is able run), custom path for `.gitlab-ci.yml`, test coverage parsing, pipeline's visibility, and much more
- [Kubernetes cluster integration](clusters/index.md): Connecting your GitLab project
with a Kubernetes cluster
- [Feature Flags](operations/feature_flags.md): Feature flags allow you to ship a project in
- [Feature Flags](../../operations/feature_flags.md): Feature flags allow you to ship a project in
different flavors by dynamically toggling certain functionality **(PREMIUM)**
- [GitLab Pages](pages/index.md): Build, test, and deploy your static
website with GitLab Pages
......
doc/user/project/operations/feature_flags.md
View file @ d2360340
---
stage: Release
group: Progressive Delivery
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
redirect_to: '../../../operations/feature_flags.md'
---
# Feature Flags **(PREMIUM)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7433) in GitLab 11.4.
With Feature Flags, you can deploy your application's new features to production in smaller batches.
You can toggle a feature on and off to subsets of users, helping you achieve Continuous Delivery.
Feature flags help reduce risk, allowing you to do controlled testing, and separate feature
delivery from customer launch.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an example of feature flags in action, see [GitLab for Deploys, Feature Flags, and Error Tracking](https://www.youtube.com/embed/5tw2p6lwXxo).
## How it works
GitLab uses [Unleash](https://github.com/Unleash/unleash), a feature
toggle service.
By enabling or disabling a flag in GitLab, your application
can determine which features to enable or disable.
You can create feature flags in GitLab and use the API from your application
to get the list of feature flags and their statuses. The application must be configured to communicate
with GitLab, so it's up to developers to use a compatible client library and
[integrate the feature flags in your app](#integrate-feature-flags-with-your-application).
## Create a feature flag
To create and enable a feature flag:
1. Navigate to your project's **Operations > Feature Flags**.
1. Click the **New feature flag** button.
1. Enter a name that starts with a letter and contains only lowercase letters, digits, underscores (`_`),
or dashes (`-`), and does not end with a dash (`-`) or underscore (`_`).
1. Enter a description (optional, 255 characters max).
1. Enter details about how the flag should be applied:
- In GitLab 13.0 and earlier, add **Environment specs**. For each environment,
include the **Status** (default enabled) and [**Rollout strategy**](#rollout-strategy-legacy)
(defaults to **All users**).
- In GitLab 13.1 and later, add Feature Flag [**Strategies**](#feature-flag-strategies).
For each strategy, include the **Type** (defaults to [**All users**](#all-users))
and **Environments** (defaults to all environments).
1. Click **Create feature flag**.
You can change these settings by clicking the **{pencil}** (edit) button
next to any feature flag in the list.
## Rollout strategy (legacy)
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2.
In GitLab 13.0 and earlier, the **Rollout strategy** setting affects which users will experience
the feature as enabled. Choose the percentage of users that the feature will be enabled
for. The rollout strategy will have no effect if the environment spec is disabled.
It can be set to:
- All users
- [Percent rollout (logged in users)](#percent-rollout-logged-in-users)
- Optionally, you can click the **Include additional user IDs** checkbox and add a list
of specific users IDs to enable the feature for.
- [User IDs](#user-ids)
## Feature flag strategies
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35555) in GitLab 13.0.
> - It's deployed behind a feature flag, disabled by default.
> - It's enabled on GitLab.com.
> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-feature-flag-strategies). **(CORE ONLY)**
You can apply a feature flag strategy across multiple environments, without defining
the strategy multiple times.
GitLab Feature Flags use [Unleash](https://unleash.github.io) as the feature flag
engine. In Unleash, there are [strategies](https://unleash.github.io/docs/activation_strategy)
for granular feature flag controls. GitLab Feature Flags can have multiple strategies,
and the supported strategies are:
- [All users](#all-users)
- [Percent rollout (logged in users)](#percent-rollout-logged-in-users)
- [User IDs](#user-ids)
- [List](#list)
Strategies can be added to feature flags when [creating a feature flag](#create-a-feature-flag),
or by editing an existing feature flag after creation by navigating to **Operations > Feature Flags**
and clicking **{pencil}** (edit).
### All users
Enables the feature for all users. It uses the [`default`](https://unleash.github.io/docs/activation_strategy#default)
Unleash activation strategy.
### Percent rollout (logged in users)
Enables the feature for a percentage of authenticated users. It uses the
[`gradualRolloutUserId`](https://unleash.github.io/docs/activation_strategy#gradualrolloutuserid)
Unleash activation strategy.
For example, set a value of 15% to enable the feature for 15% of authenticated users.
The rollout percentage can be from 0% to 100%.
CAUTION: **Caution:**
If this strategy is selected, then the Unleash client **must** be given a user
ID for the feature to be enabled. See the [Ruby example](#ruby-application-example) below.
### User IDs
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2. [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/34363) to be defined per environment in GitLab 12.6.
Enables the feature for a list of target users. It is implemented
using the Unleash [`userWithId`](https://unleash.github.io/docs/activation_strategy#userwithid)
activation strategy.
Enter user IDs as a comma-separated list of values. For example,
`user@example.com, user2@example.com`, or `username1,username2,username3`, and so on.
CAUTION: **Caution:**
The Unleash client **must** be given a user ID for the feature to be enabled for
target users. See the [Ruby example](#ruby-application-example) below.
### List
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35930) in GitLab 13.1.
Enables the feature for lists of users created with the [Feature Flag User List API](../../../api/feature_flag_user_lists.md).
Similar to [User IDs](#user-ids), it uses the Unleash [`userWithId`](https://unleash.github.io/docs/activation_strategy#userwithid)
activation strategy.
### Enable or disable feature flag strategies
This feature is under development, but is ready for testing. It's
deployed behind a feature flag that is **disabled by default**.
[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
can enable it for your instance.
To enable it:
```ruby
Feature.enable(:feature_flags_new_version)
```
To disable it:
```ruby
Feature.disable(:feature_flags_new_version)
```
## Disable a feature flag for a specific environment
In [GitLab 13.0 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/8621),
to disable a feature flag for a specific environment:
1. Navigate to your project's **Operations > Feature Flags**.
1. For the feature flag you want to disable, click the Pencil icon.
1. To disable the flag:
- In GitLab 13.0 and earlier: Slide the Status toggle for the environment. Or, to delete the
environment spec, on the right, click the **Remove (X)** icon.
- In GitLab 13.1 and later: For each strategy it applies to, under **Environments**, delete the environment.
1. Click **Save changes**.
## Disable a feature flag for all environments
To disable a feature flag for all environments:
1. Navigate to your project's **Operations > Feature Flags**.
1. For the feature flag you want to disable, slide the Status toggle to **Disabled**.
The feature flag is displayed on the **Disabled** tab.
## Integrate feature flags with your application
To use feature flags with your application, get access credentials from GitLab.
Then prepare your application with a client library.
### Get access credentials
To get the access credentials that your application needs to communicate with GitLab:
1. Navigate to your project's **Operations > Feature Flags**.
1. Click the **Configure** button to view the following:
- **API URL**: URL where the client (application) connects to get a list of feature flags.
- **Instance ID**: Unique token that authorizes the retrieval of the feature flags.
- **Application name**: The name of the running environment. For instance,
if the application runs for a production server, the application name would be
`production` or similar. This value is used for the environment spec evaluation.
NOTE: **Note:**
The meaning of these fields might change over time. For example, we are not sure
if **Instance ID** will be single token or multiple tokens, assigned to the
**Environment**. Also, **Application name** could describe the version of
application instead of the running environment.
### Choose a client library
GitLab implements a single backend that is compatible with Unleash clients.
With the Unleash client, developers can define, in the application code, the default values for flags.
Each feature flag evaluation can express the desired outcome if the flag isn't present in the
provided configuration file.
Unleash currently [offers many SDKs for various languages and frameworks](https://github.com/Unleash/unleash#client-implementations).
### Feature flags API information
For API content, see:
- [Feature Flags API](../../../api/feature_flags.md)
- [Feature Flag Specs API](../../../api/feature_flag_specs.md) (Deprecated and [scheduled for removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369).)
- [Feature Flag User Lists API](../../../api/feature_flag_user_lists.md)
- [Legacy Feature Flags API](../../../api/feature_flags_legacy.md)
### Golang application example
Here's an example of how to integrate feature flags in a Golang application:
```golang
package main
import (
"io"
"log"
"net/http"
"github.com/Unleash/unleash-client-go"
)
type metricsInterface struct {
}
func init() {
unleash.Initialize(
unleash.WithUrl("https://gitlab.com/api/v4/feature_flags/unleash/42"),
unleash.WithInstanceId("29QmjsW6KngPR5JNPMWx"),
unleash.WithAppName("production"),
unleash.WithListener(&metricsInterface{}),
)
}
func helloServer(w http.ResponseWriter, req *http.Request) {
if unleash.IsEnabled("my_feature_name") {
io.WriteString(w, "Feature enabled\n")
} else {
io.WriteString(w, "hello, world!\n")
}
}
func main() {
http.HandleFunc("/", helloServer)
log.Fatal(http.ListenAndServe(":8080", nil))
}
```
### Ruby application example
Here's an example of how to integrate feature flags in a Ruby application.
The Unleash client is given a user ID for use with a **Percent rollout (logged in users)** rollout strategy or a list of **Target Users**.
```ruby
#!/usr/bin/env ruby
require 'unleash'
require 'unleash/context'
unleash = Unleash::Client.new({
url: 'http://gitlab.com/api/v4/feature_flags/unleash/42',
app_name: 'production',
instance_id: '29QmjsW6KngPR5JNPMWx'
})
unleash_context = Unleash::Context.new
# Replace "123" with the id of an authenticated user.
# Note that the context's user id must be a string:
# https://unleash.github.io/docs/unleash_context
unleash_context.user_id = "123"
if unleash.is_enabled?("my_feature_name", unleash_context)
puts "Feature enabled"
else
puts "hello, world!"
end
```
This document was moved to [another location](../../../operations/feature_flags.md).
doc/user/project/operations/index.md
View file @ d2360340
# Project operations
---
redirect_to: '../../../operations/index.md'
---
GitLab provides a variety of tools to help operate and maintain
your applications:
- Collect [Prometheus metrics](../integrations/prometheus_library/index.md).
- Deploy to different [environments](../../../ci/environments/index.md).
- Connect your project to a [Kubernetes cluster](../clusters/index.md).
- Manage your infrastructure with [Infrastructure as Code](../../infrastructure/index.md) approaches.
- Discover and view errors generated by your applications with [Error Tracking](error_tracking.md).
- Create, toggle, and remove [Feature Flags](feature_flags.md). **(PREMIUM)**
- [Trace](tracing.md) the performance and health of a deployed application. **(ULTIMATE)**
- Change the [settings of the Monitoring Dashboard](dashboard_settings.md).
This document was moved to [another location](../../../operations/index.md).
scripts/lint-doc.sh
View file @ d2360340
......@@ -41,7 +41,7 @@ fi
# Do not use 'README.md', instead use 'index.md'
# Number of 'README.md's as of 2020-05-28
NUMBER_READMES=45
NUMBER_READMES=44
FIND_READMES=$(find doc/ -name "README.md" | wc -l)
echo '=> Checking for new README.md files...'
echo
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7