PythonでGitLab機能フラグを活用する：入門ガイド

あなたならこんな経験があるかもしれません。

新機能の開発に数週間かけてきました。すべてのテストをパスし、コードレビューも完了して、リリース準備が整いました。いざデプロイしたところ、1時間もしないうちに受信トレイがバグ報告で埋め尽くされます。機能自体はほとんどのユーザーで問題なく動作するのに、想定していなかった本番トラフィックの何かが、一部のユーザーで障害を引き起こしているのです。そこからロールバック対応、インシデントレポートの作成、PR対応に追われることになります。

機能フラグはまさにこうした事態を防ぐものです。デプロイとリリースを切り離すことができます。コードの準備ができたときに本番環境へプッシュしておき、GitLabでトグルを切り替えることで、実際に新機能を見るユーザーをコントロールできます。まず「ユーザーID」戦略でQAチームから始め、「10%ロールアウト」に切り替え、確信が持てたら「全ユーザー」へと移行できます。途中で問題が起きても、数秒でオフにできます。再デプロイも、ホットフィックスも、悪評も防げます。

このチュートリアルでは、Unleash Python SDKを通じてGitLabの機能フラグを読み取る、動作するFlaskアプリケーションを解説します。完全なサンプルコードは gitlab.com/omid-blogs/gitlab-feature-flags-demo で公開されています。自分のグループまたはワークスペースにクローンすれば、数分でライブの機能フラグ制御を体験できます。

このチュートリアルを終えると、インテグレーションの仕組みを理解し、自分のプロジェクトにそのまま流用できるテンプレートが完成します。

必要なもの

• 機能フラグが有効になったGitLabプロジェクト（Free、Premium、またはUltimate）。フラグの作成と管理はここで行います。有効にするには、プロジェクトの 設定 > 一般 > 公開設定、プロジェクト機能、権限 に移動し、機能フラグ のトグルがオンになっていることを確認してください。
• デモリポジトリ を自分のGitLab名前空間にフォークし、ローカルにクローンしたもの

GitLabの機能フラグの仕組み

GitLabはすべてのプロジェクトに対して Unleash 互換のAPIを公開しています。つまり、UnleashのクライアントSDK（Go、Ruby、Python、JavaScriptなど）は、独立したUnleashサーバーなしでGitLabに直接接続できます。

起動時にSDKがすべてのフラグ定義を取得し、設定可能なインターバルで再取得します（デモでは15秒）。is_enabled() を呼び出すたびに、キャッシュされた設定に基づいてローカルで評価が行われ、フラグチェックごとのネットワーク呼び出しは発生しません。これにより、フラグ評価はほぼ瞬時に行われ、一時的なネットワーク障害にも強くなります。

GitLabの機能フラグをPython FlaskアプリにUnleash SDKで統合する手順を説明します。

1. GitLabプロジェクトのセットアップとデモのクローン

必要なもの：

• 機能フラグをホストするための自分のGitLabプロジェクト
• アプリを実行するためにローカルにクローンしたデモリポジトリ

デモリポジトリをフォークまたはクローンする

gitlab.com/omid-blogs/gitlab-feature-flags-demo にアクセスして、自分のGitLab名前空間にフォークしてください。これにより、独自の機能フラグを管理できるプロジェクトのコピーが作成されます。次にローカルにクローンして、お気に入りのIDEで開きます。

      git clone https://gitlab.com/<your-namespace>/gitlab-feature-flags-demo.git
cd gitlab-feature-flags-demo

    

リポジトリの構成

      .
├── app.py                # FlaskアプリとUnleash SDKの統合
├── requirements.txt      # Pythonの依存関係
├── .env.example          # 必要な環境変数のテンプレート
├── .gitignore
├── templates/
│   └── index.html        # WebUIテンプレート
└── static/
    └── styles.css        # スタイリング

    

2. GitLabで機能フラグを作成する

自分のGitLabプロジェクトを開き、デプロイ > 機能フラグ に移動して、新しい機能フラグ をクリックします。以下の4つのフラグを作成し、それぞれのステータスを アクティブ に、戦略を 全ユーザー に設定します。

• dark_mode — ページをダークカラースキームに切り替えます。
• holiday_banner — ページ上部にフェスティブなバナーを表示します。
• new_layout — カードグリッドを1カラムレイアウトに切り替えます。
• fun_fonts — ボディフォントを遊び心のある手書き風スタイルに変更します。

GitLab UIに表示された4つの機能フラグ

ヒント： フラグが有効として評価されるには、アクティブ状態で少なくとも1つの戦略が設定されている必要があります。戦略がない場合、SDKはフラグが「アクティブ」とマークされていても無効として扱います。

各戦略の概要

「全ユーザー」はシンプルなオン/オフのトグルですが、GitLabにはすぐに使える戦略が他にもいくつかあります。

• パーセントロールアウト（推奨）：ユーザーID、セッションID、またはランダムに基づいて、一定割合のユーザーに段階的に展開します。最も柔軟なオプションで、最初に選ぶべき戦略です。
• ユーザーのパーセント：認証済みユーザーの一定割合に対して有効にします。ログインユーザーにのみ機能するため、パーセントロールアウトほど柔軟ではありません。
• ユーザーID：特定のユーザーIDのみに対して有効にします。指定グループによる内部テストに最適です。
• ユーザーリスト：事前に定義されたユーザーリストに対して有効にします。
• 全ユーザー：すべてのユーザーに対して有効にします。

戦略こそが機能フラグを非常に強力にしている部分です。ユーザーID戦略でQAチームから始め、10%のパーセントロールアウトに切り替え、確信が持てたら全ユーザーへ。GitLab UIから操作するだけで、コード変更は一切不要です。

3. Unleash認証情報を取得する

機能フラグのページで、右上の 設定 をクリックします。以下の2つの値が表示されます。

• API URL: https://gitlab.com/api/v4/feature_flags/unleash/<your-project-id>
• インスタンスID: プロジェクトにスコープされた一意のトークン

両方の値をコピーしてください。アプリに環境変数として渡します。インスタンスIDは読み取り専用であることに注意してください。フラグの状態を取得するだけで、変更はできません。ただし、情報漏洩を防ぐためにインスタンスIDはシークレットとして扱ってください。

設定パネルにAPI URLとインスタンスIDが表示されている

4. プロジェクトをローカルにセットアップする

READMEに完全なセットアップ手順がありますが、簡単にまとめると次のとおりです。

      pip install -r requirements.txt

    

次に認証情報を設定します。2つの方法があります。

方法A：.envファイルを使う（推奨）

リポジトリには .env.example ファイルが含まれています。これをコピーして値を入力します。

      cp .env.example .env

    

エディターで .env を開き、ステップ3で取得した認証情報でプレースホルダーを置き換えます。

      UNLEASH_URL=https://gitlab.com/api/v4/feature_flags/unleash/<your-project-id>
UNLEASH_INSTANCE_ID=<your-instance-id>
UNLEASH_APP_NAME=production

    

次にエクスポートします。

      export $(grep -v '^#' .env | xargs)

    

方法B：ターミナルで直接エクスポートする

      export UNLEASH_URL="https://gitlab.com/api/v4/feature_flags/unleash/<your-project-id>"
export UNLEASH_INSTANCE_ID="<your-instance-id>"
export UNLEASH_APP_NAME="production"

    

.env ファイルはバージョン管理にコミットしないでください。リポジトリの .gitignore ですでに除外されていますが、理由を知っておく価値があります。インスタンスIDはシークレットであり、gitの履歴に残すべきではありません。

インテグレーション全体を動かす環境変数は3つです。

UnleashClient が主要な依存関係です。ポーリング、キャッシュ、ローカルでのフラグ評価を処理する公式のUnleash Python SDKであり、これらを自前で構築する必要がなくなります。

5. アプリケーションを理解する

実行する前に app.py を読んでください。自分のプロジェクトで再現できるよう、理解しておく価値のある主要なパターンを説明します。

SDKの初期化

      unleash_client = UnleashClient(
    url=UNLEASH_URL,
    app_name=UNLEASH_APP_NAME,
    instance_id=UNLEASH_INSTANCE_ID,
    refresh_interval=15,
    metrics_interval=60,
)

unleash_client.initialize_client()

    

パーソナルアクセストークンも、ソースにハードコードされた認証情報も不要です。必要な変数のいずれかが欠けている場合、アプリは即座に明確なエラーメッセージを出力して終了します。

フラグの確認

      def is_flag_enabled(flag_name):
    return unleash_client.is_enabled(flag_name)

    

SDKがフラグ定義をメモリにキャッシュするため、is_enabled() はネットワーク往復なしに即座に結果を返します。

フラグでの実際の動作の制御

インデックスルートはフィーチャーディクショナリを構築し、各フラグを評価してテンプレートに結果を渡します。

      features = {}
for flag_name, config in feature_configs.items():
    features[flag_name] = {
        **config,
        'enabled': is_flag_enabled(flag_name)
    }

return render_template('index.html', features=features)

    

テンプレートはこれらの値を使用して、CSSクラスを条件付きで適用し、UI要素をレンダリングします。dark_mode はbodyクラスを切り替え、holiday_banner はバナー要素の表示/非表示を完全に制御します。templates/index.html を開いて、どのように接続されているか確認してください。

なお、index.html は小さなJavaScriptスニペットによって30秒ごとに自動更新されるため、手動でリロードしなくても機能フラグの変更が反映されるのを確認できます。

ターゲット戦略のためのユーザーコンテキストの渡し方

全ユーザーを超えてパーセントロールアウトやユーザーターゲティングを使用する準備ができたら、is_enabled() にコンテキストオブジェクトを渡します。

      unleash_client.is_enabled(
    'new_layout',
    context={'userId': current_user.id}
)

    

SDKはパーセントロールアウトの一貫したハッシュ処理を自動的に行います。計算は一切不要です。

6. アプリを実行する

      python3 app.py

    

http://localhost:8080 にアクセスしてください。4つの機能カードが現在の有効/無効の状態で表示されるはずです。

すべての機能フラグが無効になっているデモアプリ

7. リアルタイムでフラグを切り替える

GitLabの デプロイ > 機能フラグ に戻り、いずれかのフラグを切り替えてみてください。最も視覚的な効果が得られる dark_mode または holiday_banner を試してみましょう。約15秒待ってからページをリロードすると、カードが新しい状態を反映して更新されます。dark_mode をオンにした場合、ページ全体がダークテーマに切り替わります。オフに戻して待ち、リロードすると即座に元に戻ります。

これが機能フラグのコアバリューです。コードに触れることなく、再デプロイすることなく、GitLabからアプリケーションの動作を制御できます。

2つの機能フラグがオフになっているデモアプリ

GitLab REST APIではなくUnleash SDKを使う理由

すべてのリクエストでフラグを評価するアプリには、SDKが明らかに優れています。より高速で、よりシンプルで、SDKが使用するインスタンスIDはフラグ状態の読み取り以外の権限を持ちません。これはPATよりもはるかに小さなセキュリティフットプリントです。

トラブルシューティング

本番環境でのレート制限について

15秒のポーリングインターバルは、開発環境や小規模なデプロイには適しています。すべてのクライアントが同じIPからポーリングする場合、GitLab.comは15秒インターバルで約125クライアントをサポートできます。それを超えるとレート制限に達します。より大規模な本番アプリを構築する場合は、クライアントの前にUnleash Proxyを実行することを検討してください。すべてのインスタンスに代わってGitLabへのリクエストをバッチ処理し、上流のトラフィックを大幅に削減します。

セキュリティに関する考慮事項

1. debug=False はデモですでに設定されています： このままにしておいてください。Flaskのデバッグモードはリモートコード実行を可能にする対話型デバッガーを公開します。
2. 依存関係を最新の状態に保つ：requirements.txt には特定のバージョンが指定されています。CI/CDパイプラインでGitLabのDependency Scanningを有効にして、脆弱性を把握し続けましょう。
3. 認証情報には環境変数を使う：ソースコードにインスタンスIDやトークンをハードコードしないでください。デモの .env.example が正しいパターンを示しています。
4. インスタンスIDは読み取り専用です：フラグの状態を取得するだけで、変更はできません。それでもシークレットとして扱ってください。

まとめ

このチュートリアルでは、GitLabの機能フラグをPythonアプリケーションに統合する全ライフサイクルを説明しました。適切な戦略でフラグを作成すること、Unleash認証情報の取得、SDKの初期化、Flaskでのフラグのローカル評価、そして再デプロイなしにリアルタイムで動作を切り替えることまでをカバーしました。

インテグレーション全体に必要なのは、1つの依存関係（UnleashClient）、3つの環境変数、そして1つのメソッド呼び出し（is_enabled()）だけです。独立したUnleashサーバーも、パーソナルアクセストークンも、複雑なインフラも不要です。

機能フラグは、デプロイリスクを軽減するための最も実践的なツールの1つです。壊れた機能を即座に無効化したり、ターゲットユーザーグループから一定割合、そして全ユーザーへと段階的に展開したりする能力は、デプロイパイプラインに一切触れることなく、最小限のセットアップで大きな価値をもたらします。デモリポジトリ は、あらゆるプロジェクトにフォークして応用できる、動作するベースを提供しています。

リソース

• GitLabのデモプロジェクト
• GitLab 機能フラグドキュメント
• Unleash Python SDK（GitHub）
• Unleash SDK（全言語）