機能フラグ

機能フラグを使用すると、アプリケーションの新しい機能をより小さなバッチで本番環境にデプロイできます。機能をオンまたはオフにして、ユーザーのサブセットを切り替えることで、継続的デリバリーを実現できます。機能フラグは、リスクを軽減し、制御されたテストを実行し、機能の提供を顧客のローンチから分離するのに役立ちます。

GitLabの機能フラグの完全なリストも利用できます。

機能フラグの実際の動作例については、機能フラグによるリスクの排除を参照してください。

クリックスルーデモについては、機能フラグを参照してください。

機能フラグを使用する

GitLabは、機能フラグ用のUnleash互換APIを提供します。

GitLabでフラグを有効または無効にすると、アプリケーションは有効または無効にする機能を判断できます。

GitLabで機能フラグを作成し、アプリケーションからAPIを使用して、機能フラグとそのステータスのリストを取得できます。アプリケーションはGitLabと通信するように設定する必要があるため、互換性のあるクライアントライブラリを使用し、機能フラグをアプリに統合するのはデベロッパー次第です。

機能フラグを作成する

機能フラグを作成して有効にするには:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
2. デプロイ > 機能フラグを選択します。
3. 新しい機能フラグを選択します。
4. 文字で始まり、小文字、数字、アンダースコア（_）またはダッシュ（-）のみを含み、ダッシュ（-）またはアンダースコア（_）で終わらない名前を入力します。
5. オプション。説明を入力します（最大255文字）。
6. フラグの適用方法を定義するには、機能フラグ戦略を追加します。各ストラテジについて、種類（デフォルトはすべてのユーザー）と環境を含めます。
7. 機能フラグを作成を選択します。

これらの設定を変更するには、リスト内の任意の機能フラグの横にある編集（ ）を選択します。

機能フラグの最大数

GitLab Self-Managedのプロジェクトごとの機能フラグの最大数は200です。GitLab.comの場合、最大数はプランによって決まります:

機能フラグのストラテジ

ストラテジを複数回定義しなくても、複数環境に機能フラグのストラテジを適用できます。

GitLabの機能フラグはUnleashに基づいています。Unleashには、きめ細かい機能フラグ制御のためのストラテジがあります。GitLabの機能フラグには複数のストラテジを設定でき、サポートされているストラテジは次のとおりです:

• すべてのユーザー
• ユーザーの割合
• ユーザーID
• ユーザーリスト

戦略は、機能フラグの作成時、またはデプロイ > 機能フラグに移動し、編集 ( ) を選択して、作成後に既存の機能フラグを編集することで、機能フラグに追加できます。

すべてのユーザー

すべてのユーザーに対して機能を有効にします。標準（default）Unleashアクティベーションストラテジを使用します。

ロールアウト率

動作の一貫性を設定可能にして、ページビューの割合に対して機能を有効にします。この一貫性は、スティッキー性とも呼ばれます。Gradual Rollout（flexibleRollout）Unleashアクティベーションストラテジを使用します。

一貫性は、以下に基づいて設定できます:

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

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

ロールアウト率は0%から100%です。

ユーザーIDに基づいて一貫性のあるロールアウト率は、同じ動作をします。

ユーザーの割合

認証済みユーザーの割合に対して機能を有効にします。UnleashアクティベーションストラテジgradualRolloutUserIdを使用します。

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

ロールアウト率は0%から100%です。

スティッキー性（同じユーザーに対して一貫したアプリケーションの動作）は、認証済みユーザーには保証されますが、匿名ユーザーには保証されません。

ユーザーIDに基づいて一貫性のあるロールアウト率は、同じ動作をします。ユーザーの割合よりもロールアウト率の方が柔軟性があるため、ロールアウト率を使用することをお勧めします。

ユーザーID

ターゲットユーザーのリストに対して機能を有効にします。Unleash UsersIDs（userWithId）アクティベーションストラテジを使用して実装されます。

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

ユーザーリスト

機能フラグ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を表示できます。リストを表示している場合は、編集（ ）を選択して名前を変更できます。

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

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

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
2. デプロイ > 機能フラグを選択します。
3. ユーザーを追加するリストの横にある編集（ ）を選択します。
4. ユーザーを追加を選択します。
5. ユーザーIDを、コンマ区切りの値のリストとして入力します。たとえば、user@example.com, user2@example.com、またはusername1,username2,username3などです。
6. 追加を選択します。

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

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

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
2. デプロイ > 機能フラグを選択します。
3. 変更するリストの横にある編集（ ）を選択します。
4. 削除するIDの横にある削除（ ）を選択します。

コード参照を検索する

クリーンアップ中にコードから機能フラグを削除するには、それに対するプロジェクト参照を見つけます。

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

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
2. デプロイ > 機能フラグを選択します。
3. 削除する機能フラグを編集します。
4. 追加のアクション（ ）を選択します。
5. コードの参照を検索するを選択します。

特定の環境の機能フラグを無効にする

特定の環境の機能フラグを無効にするには:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
2. デプロイ > 機能フラグを選択します。
3. 無効にする機能フラグについて、編集（ ）を選択します。
4. フラグを無効にするには:
   • 適用される各ストラテジについて、環境の下で、環境を削除します。
5. 変更を保存を選択します。

すべての環境の機能フラグを無効にする

すべての環境の機能フラグを無効にするには:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
2. デプロイ > 機能フラグを選択します。
3. 無効にする機能フラグについて、ステータスの切替を無効にスライドさせます。

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

機能フラグをアプリケーションと統合する

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

アクセス認証情報を取得する

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

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
2. デプロイ > 機能フラグを選択します。
3. 設定するを選択して、以下を表示します:

   • API URL: クライアント（アプリケーション）が機能フラグのリストを取得するために接続するURL。

   • インスタンスID: 機能フラグの取得を承認する一意のトークン。

   • Application name（アプリケーション名）: アプリケーションが実行される環境の名前（アプリケーション自体の名前ではありません）。

     たとえば、アプリケーションが本番環境サーバーで実行されている場合、Application name（アプリケーション名）はproductionまたは同様のものになる可能性があります。この値は、環境仕様の評価に使用されます。

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

クライアントライブラリを選択する

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

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

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

機能フラグAPI情報

APIコンテンツについては、以下を参照してください:

• 機能フラグAPI
• 機能フラグユーザーリストAPI

Goアプリケーションの例

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クライアントには、Percent rollout (logged in users)（ロールアウト率（パーセントロールアウト、ログインユーザー））またはTarget Users（ターゲットユーザー）のリストで使用するためのユーザー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.
# 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 Proxyの例

Unleash Proxyバージョン0.2以降、プロキシは機能フラグと互換性があります。

GitLab.comの本番環境ではUnleash Proxyを使用する必要があります。詳細については、パフォーマンスに関する注意を参照してください。

プロジェクトの機能フラグに接続するための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を使用する場合、各プロキシインスタンスはUNLEASH_APP_NAMEで指定された環境の機能フラグのみをリクエストできるという制限があります。プロキシはクライアントの代わりにこれをGitLabに送信します。つまり、クライアントはこれを上書きできません。

機能フラグ関連のイシュー

関連するイシューを機能フラグにリンクできます。機能フラグのLinked issues（リンクされたイシュー）セクションで、+ボタンを選択し、イシューの参照番号またはイシューの完全なURLをインプットします。すると、イシューが関連する機能フラグに表示され、その逆も同様です。

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

パフォーマンス要因

GitLab機能フラグは、あらゆるアプリケーションで使用できます。大規模なアプリケーションでは、高度な設定が必要になる場合があります。このセクションでは、機能を使用する前に組織が行う必要のあることを特定するのに役立つパフォーマンス要因について説明します。詳しくは、機能フラグを使用するをご覧ください。

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

GitLabは、レート制限に達するまで、可能な限り多くのクライアントリクエストを受け入れます。機能フラグAPIは、Unauthenticated traffic (from a given IP address)（認証されていないトラフィック（特定のIPアドレスから））と見なされます。GitLab.comについては、GitLab.com固有の制限を参照してください。

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

• 1分あたり1回リクエスト…500のクライアントをサポートできます。
• 15秒あたり1回リクエスト…125のクライアントをサポートできます。

よりスケーラビリティの高いソリューションをお探しのアプリケーションの場合は、Unleash Proxyを使用する必要があります。GitLab.comでは、エンドポイント全体でレート制限される可能性を減らすために、Unleash Proxyを使用する必要があります。このプロキシサーバーは、サーバーとクライアントの間にあります。クライアントグループの代わりにサーバーにリクエストを行うため、送信リクエストの数を大幅に削減できます。それでも429の応答が得られる場合は、Unleash ProxyでUNLEASH_FETCH_INTERVALの値を大きくしてください。

現在のレート制限により多くのキャパシティを与えるイシューもあります。

ネットワーキングエラーからの回復

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

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

GitLab Self-Managed

機能に関しては、違いはありません。GitLab.comとGitLab Self-Managedはどちらも同じように動作します。

スケーラビリティに関しては、GitLabインスタンスの仕様次第です。たとえば、GitLab.comはHAアーキテクチャを使用しているため、多くの同時リクエストを処理できます。ただし、性能の低いマシン上のGitLab Self-Managedインスタンスでは、同等のパフォーマンスは得られません。詳細については、リファレンスアーキテクチャを参照してください。