機能フラグ

13.5でGitLab PremiumからGitLab Freeに移行しました。

機能フラグを使えば、アプリケーションの新機能を小ロットで本番環境にデプロイできます。機能のオン・オフをユーザーのサブセットに切り替えることができ、継続的デリバリーの実現に役立ちます。機能フラグを使用することで、管理されたテストを実施し、機能デリバリを顧客からのリリースから切り離すことができるため、リスクを低減できます。

機能フラグのアクションの例については、機能フラグの設定、インストルメンテーション、および使用を参照してください。

クリックスルー・デモで機能フラグを調べることもできます。

note
GitLab製品の開発に貢献するには、代わりにこの機能フラグのコンテンツをご覧ください。

どのように動作するか

GitLabはUnleashという機能切り替えサービスを使っています。

GitLabのフラグを有効/無効にすることで、アプリケーションはどの機能を有効/無効にするかを決定することができます。

GitLabで機能フラグを作成し、アプリケーションからAPIを使って機能フラグのリストとそのステータスを取得することができます。アプリケーションはGitLabと通信するように設定する必要があるので、互換性のあるクライアント・ライブラリを使い、機能フラグをアプリにインテグレーションするのは開発者次第です。

機能フラグの作成

機能フラグを作成し、有効にします：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. デプロイ > 機能フラグを選択します。
  3. 新規機能フラグを選択します。
  4. 文字で始まり、小文字、数字、アンダースコア（_）、ダッシュ（）の_みを含み_-、ダッシュ（-）またはアンダースコア（-）で終わらない-_名前を入力します。
  5. オプション。説明を入力します（最大255文字）。
  6. 機能フラグの追加 ストラテジーフラグの適用方法を定義します。ストラテジーごとに、Type（デフォルトは すべてのユーザーと環境(デフォルトはすべての環境) を指定します。）
  7. 機能フラグを作成] を選択します。

これらの設定を変更するには、リストの機能フラグの横にある [編集({pencil})]を選択します。

機能フラグの最大数

GitLab 13.5 で導入されました。

セルフマネージド GitLab インスタンスでは、プロジェクトあたりの機能フラグの最大数は 200 です。GitLab SaaSの場合、最大数はティアによって決まります：

ティアプロジェクトごとの機能フラグ (SaaS)プロジェクトごとの機能フラグ（自主管理）
無料50200
Premium150200
究極200200

機能フラグ戦略

  • GitLab 13.0から導入されました。
  • 機能フラグの後ろにデプロイされ、デフォルトでは無効になっています。
  • GitLab 13.2ではデフォルトで有効になりました。
  • 本番環境での使用をお勧めします。
  • GitLab.comで有効になっています。

機能フラグ戦略を何度も定義することなく、複数の環境に適用することができます。

GitLab機能フラグはUnleashを機能フラグエンジンとして使います。Unleashでは、機能フラグを細かく制御するためのストラテジーがあります。GitLab機能フラグは複数のストラテジを持つことができ、サポートされているストラテジは以下の通りです：

ストラテジーは、機能フラグを作成する際、または作成後に既存の機能フラグを編集する際に、Deploy > Feature flagsに移動し、Edit({pencil})を選択することで追加できます。

すべてのユーザー

すべてのユーザーに対して機能を有効にします。標準 (default) Unleash アクティベーション戦略を使用します。

ロールアウト率

GitLab 13.5 で導入されました。

動作の一貫性を設定することで、ページビューのパーセンテージに対して機能を有効にします。この一貫性は粘着性とも呼ばれます。Gradual Rollout (flexibleRollout) Unleash アクティベーション戦略を使用します。

一貫性は、以下のように設定できます：

  • ユーザーID：ユーザーID：セッションIDを無視して、各ユーザーIDで一貫した動作を行います。
  • セッションID：各セッションIDは、ユーザーIDを無視して一貫した動作をします。
  • ランダム：一貫した動作は保証されません。この機能は、ページビューの選択された割合に対してランダムに有効になります。ユーザーIDとセッションIDは無視されます。
  • 利用可能なID：ユーザーのステータスに基づいて一貫した動作が試みられます：
    • ユーザーがログインしている場合、ユーザーIDに基づいて一貫した動作を行います。
    • ユーザーが匿名の場合は、セッションIDに基づいて動作を一貫させます。
    • ユーザーIDまたはセッションIDがない場合は、ページビューの選択されたパーセンテージに対してランダムに機能が有効になります。

例えば、ページビューの15%に対して機能を有効にするには、利用可能IDに基づいて15%という値を設定します。認証ユーザーの場合は、ユーザーIDに基づいて設定されます。セッションIDを持つ匿名ユーザーの場合は、ユーザーIDを持たないため、代わりにセッションIDに基づきます。セッションIDが提供されない場合は、ランダムに戻ります。

ロールアウトのパーセンテージは0%から100%の間で指定できます。

ユーザーIDに基づく一貫性の選択は、ユーザーロールアウトのパーセンテージと同じように機能します。

caution
ランダム]を選択すると、個々のユーザーに対して一貫性のないアプリケーション動作が提供されます。

ユーザーの割合

認証されたユーザーの割合で機能を有効にします。Unleash アクティベーション戦略gradualRolloutUserIdを使用します。

たとえば、認証ユーザーの 15% に対して機能を有効にするには、値を 15% に設定します。

ロールアウトのパーセンテージは0%から100%の間で指定できます。

Stickiness (同じユーザーに対する一貫したアプリケーションの動作) は、認証されたユーザーに対しては保証されますが、匿名ユーザーに対しては保証されません。

ユーザーIDに基づく一貫性を持つパーセントロールアウトも同じ動作をします。パーセンテージロールアウトを使用することをお勧めします。

caution
パーセントロールアウトを選択した場合は、UnleashクライアントにユーザーIDを付与する必要があります。以下のRubyの例を参照してください。

ユーザーID

対象ユーザーのリストに対して機能を有効にします。Unleash UserIDs (userWithId) アクティベーション戦略を使って実装されています。

ユーザー ID をカンマ区切りの値のリストとして入力します（user@example.com, user2@example.com やusername1,username2,username3など）。ユーザー ID は、アプリケーション・ユーザーの識別子です。GitLabユーザーである必要はありません。

caution
Unleashクライアントが対象ユーザーに対して機能を有効にするには、ユーザーIDを指定する必要があります。以下のRubyの例をご覧ください。

ユーザーリスト

GitLab 13.1で導入されました。

機能フラグUIや 機能フラグユーザーリストAPIで作成されたユーザーリストに対して機能を有効にします。ユーザーIDと同様に、Unleash UsersIDs (userWithId) のアクティビティを使用します。

ユーザーに対して特定の機能を無効にすることはできませんが、ユーザーリストに対して有効にすることで同様の結果を得ることができます。

使用例：

  • Full-user-list =User1A, User1B, User2A, User2B, User3A, User3B, ...
  • Full-user-list-excluding-B-users =User1A, User2A, User3A, ...

ユーザーリストの作成

ユーザーリストを作成するには

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. デプロイ > 機能フラグを選択します。
  3. ユーザーリストの表示]を選択します。
  4. 新しいユーザーリストを選択します。
  5. リストの名前を入力します。
  6. 作成を選択します。

リストの横にある編集（{鉛筆}）を選択すると、リストのユーザーIDを表示できます。リストを表示中に編集（{鉛筆}）を選択すると、リストの名前を変更できます。

ユーザリストへのユーザの追加

GitLab 13.3 で導入されました。

ユーザーをユーザーリストに追加するには

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. デプロイ > 機能フラグを選択します。
  3. ユーザーを追加したいリストの横にある編集（{pencil}）を選択します。
  4. ユーザーの追加]を選択します。
  5. ユーザーIDをカンマ区切りの値のリストとして入力します。例えば、user@example.com, user2@example.com 、またはusername1,username2,username3など。
  6. Add（追加）を選択します。

ユーザーリストからユーザーを削除します。

GitLab 13.3 で導入されました。

ユーザーリストからユーザーを削除するには：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. デプロイ > 機能フラグを選択します。
  3. 変更したいリストの横にある編集（{pencil}）を選択します。
  4. 削除したいIDの横にある削除({remove}) を選択します。

コード参照の検索

GitLab 14.4で導入されました。

クリーンアップ中に機能フラグをコードから削除するには、そのフラグを参照しているプロジェクトを見つけてください。

機能フラグのコード参照を検索するには：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. デプロイ > 機能フラグを選択します。
  3. 削除したい機能フラグを編集します。
  4. その他のアクション（{ellipsis_v}）を選択します。
  5. コードリファレンスの検索を選択します。

特定の環境で機能フラグを無効にします。

GitLab 13.0以前では、特定の環境で機能フラグを無効にすることができます：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. デプロイ > 機能フラグを選択します。
  3. 無効にしたい機能フラグについて、編集（{pencil}）を選択します。

  4. フラグを無効にするには

    • GitLab 13.0以前では：環境のStatusトグルをスライドさせます。または、環境仕様を削除するには、右側のRemove(X) を選択します。
    • GitLab 13.1 以降の場合：適用される各ストラテジーについて、[Environments]で環境を削除します。
  5. 変更を保存を選択します。

すべての環境で機能フラグを無効にします。

すべての環境で機能フラグを無効にするには、次のようにします：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. デプロイ > 機能フラグを選択します。
  3. 無効にしたい機能フラグについて、[Status]トグルを[Disabled]にスライドします。

機能フラグは「無効」タブに表示されます。

機能フラグとアプリケーションのインテグレーション

機能フラグをアプリケーションで使うには、GitLabからアクセス認証情報を取得します。それから、クライアントライブラリを使ってアプリケーションを準備しましょう。

アクセス認証情報を取得

アプリケーションが GitLab と通信するために必要なアクセス認証情報を取得します：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. デプロイ > 機能フラグを選択します。
  3. Configure（設定）を選択すると、以下が表示されます：
    • API URL：クライアント（アプリケーション）が機能フラグのリストを取得するために接続する URL。
    • インスタンスID：機能フラグの取得を作成者に許可するユニークなトークン。

    • Application name (アプリケーション名): アプリケーションが動作する環境の名前 (アプリケーション自体の名前ではありません)。

      たとえば、アプリケーションが運用サーバーで動作する場合、アプリケーション名はproduction などになります。この値は環境仕様の評価に使われます。

これらのフィールドの意味は、時間の経過とともに変わる可能性があります。たとえば、インスタンス IDが単一のトークンなのか、環境に割り当てられた複数のトークンなのかはわかりません。また、Application nameは実行環境の代わりにアプリケーションのバージョンを表す可能性があります。

クライアントライブラリの選択

GitLabはUnleashクライアントと互換性のある単一のバックエンドを実装しています。

Unleashクライアントでは、開発者はアプリケーションコードでフラグのデフォルト値を定義することができます。各機能フラグの評価では、提供された設定ファイルにフラグが存在しない場合に望ましい結果を表すことができます。

Unleashは現在、さまざまな言語やフレームワーク用のSDKを提供しています。

機能フラグAPI情報

APIの内容については

囲碁アプリケーションの例

機能フラグをGoアプリケーションにインテグレーションする例を示します：

package main

import (
    "io"
    "log"
    "net/http"

    "github.com/Unleash/unleash-client-go/v3"
)

type metricsInterface struct {
}

func init() {
    unleash.Initialize(
        unleash.WithUrl("https://gitlab.com/api/v4/feature_flags/unleash/42"),
        unleash.WithInstanceId("29QmjsW6KngPR5JNPMWx"),
        unleash.WithAppName("production"), // Set to the running environment of your application
        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アプリケーションの例

機能フラグをRubyアプリケーションにインテグレーションする例を示します。

Unleashクライアントには、パーセントロールアウト（ログインユーザー）ロールアウト戦略またはターゲットユーザーのリストで使用するユーザーIDが与えられます。

#!/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', # Set to the running environment of your application
  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

Unleash プロキシの例

Unleash Proxyバージョン0.2では、プロキシは機能フラグに対応しています。プロジェクトの機能フラグに接続するDockerコンテナを実行するには、以下のコマンドを実行します：

docker run \
  -e UNLEASH_PROXY_SECRETS=<secret> \
  -e UNLEASH_URL=<project feature flags URL> \
  -e UNLEASH_INSTANCE_ID=<project feature flags instance ID> \
  -e UNLEASH_APP_NAME=<project environment> \
  -e UNLEASH_API_TOKEN=<tokenNotUsed> \
  -p 3000:3000 \
  unleashorg/unleash-proxy
変数値
UNLEASH_PROXY_SECRETS Unleash Proxyクライアントの設定に使用する共有シークレット。
UNLEASH_URLプロジェクトのAPI URL。詳細については、「アクセス認証情報を取得する」を参照してください。
UNLEASH_INSTANCE_IDプロジェクトのインスタンス ID。詳細については、「アクセス認証情報を取得する」を参照してください。
UNLEASH_APP_NAMEアプリケーションが動作する環境名。詳細については、アクセス認証情報の取得 をお読みください。
UNLEASH_API_TOKENUnleash Proxyの起動に必要ですが、GitLabへの接続には使用しません。任意の値を設定できます。

Unleash Proxyを使用する際には制限があり、各プロキシインスタンスはUNLEASH_APP_NAMEで指定された環境に対してのみフラグをリクエストすることができます。プロキシはクライアントに代わって GitLab にこのフラグを送信します。

機能フラグに関連するイシューをリンクすることができます。機能フラグにリンクされた課題のセクションで、+ ボタンを選択し、課題の参照番号か完全な URL を入力してください。イシューは関連機能フラグに表示されます。

この機能はリンクされたイシュー機能に似ています。

パフォーマンス要因

GitLab機能フラグはどのようなアプリケーションでも使用できます。大規模なアプリケーションでは事前の設定が必要になるかもしれません。このセクションでは、機能を使用する前に何が必要かを特定するために、パフォーマンス要因について説明します。詳細に入る前に、How it worksセクションをお読みください。

アプリケーションノードでサポートされる最大クライアント数

GitLabはレート制限に達するまで、可能な限りクライアントからのリクエストを受け付けます。現時点では、機能フラグAPIはGitLab.com特有の制限でUnauthenticated traffic (from a given IP address)に該当するため、1分あたり500リクエストとなっています。

ポーリングレートはSDKで設定可能です。すべてのクライアントが同じIPからリクエストしていることが条件です：

  • 1分間に1回リクエスト …500クライアントをサポートできます。
  • 15秒に1回リクエスト …125クライアント対応可能

よりスケーラブルなソリューションをお求めの場合は、Unleash Proxyをご利用ください。このプロキシサーバはサーバとクライアントの間に位置します。クライアントグループの代理としてサーバにリクエストするので、アウトバウンドリクエストの数を大幅に減らすことができます。

また、現在のレート制限にもっと容量を与えるイシューもあります。

ネットワークエラーからの回復

一般的に、Unleashクライアントには、サーバーがエラーコードを返したときにフォールバックするメカニズムがあります。たとえば、unleash-ruby-client 、アプリケーションが現在の状態で実行し続けられるように、ローカルバックアップからフラグデータを読み取ります。

詳細については、SDKプロジェクトのドキュメントをお読みください。

自己管理型 GitLab

機能的には違いはありません。SaaSもセルフマネージドも動作は同じです。

スケーラビリティに関しては、GitLabインスタンスの仕様次第です。例えば、GitLab.comはHAアーキテクチャを採用しているので、多くの同時リクエストを処理することができます。しかし、パワー不足のマシン上のセルフマネージドインスタンスでは、同等のパフォーマンスは得られません。詳しくはリファレンスアーキテクチャをご覧ください。