• 変更のロールアウト
  • 本番前のテスト用に機能を有効化
  • GitLab.comの機能を有効にするには
    • 変更を伝える
    • プロセス
      • アクターのパーセンテージ vs 時間ロールアウトのパーセンテージ
      • 機能フラグの無効化
    • アクターによる選択的な無効化
    • パーセンテージベースのアクター選択
  • 機能フラグを有効にした後のメトリクスの検証
  • 機能フラグの変更ロギング
    • ChatOpsレベル
    • インスタンス・レベル
• クリーンアップ
  • ChatOpsのクリーンアップ

ChatOpsを使用して機能フラグを有効または無効にします。

ステージングや本番環境のようなGitLabが提供する環境で機能フラグの背後にある機能をオン/オフするには、ChatOpsボットにアクセスする必要があります。ChatOps ボットは現在、GitLab.comやdev.gitlab.orgとは異なる ops インスタンス上で動作しています。

ChatOpsのドキュメントに従ってアクセスをリクエストしてください。

プロジェクトに追加された後、アクセスが伝播したかどうかをテストします：

/chatops run feature --help

変更のロールアウト

変更が環境にデプロイされたら、その機能をユーザーにロールアウトしましょう。変更をロールアウトする正確な手順は、変更によって異なる可能性があるため、特定されていません。しかし、一般的には、変更をすぐにすべての人に有効にするのではなく、段階的にロールアウトすることをお勧めします。また、コードがデプロイされる_前に_機能を有効に_しない_ことも推奨します。これにより、機能のロールアウトとデプロイを分離することができ、両方の影響を別々に測定することが容易になります。

GitLabの機能ライブラリ（Flipperを使用し、機能フラグプロセスガイドでカバーされています）は、ユーザーへの時間の割合に対する変更のロールアウトをサポートしています。これはGitLab ChatOpsを使ってコントロールすることができます。

最新の機能フラグコマンドのリストはソースコードをご覧ください。そのファイル内の全ての例の前には/chatops run を付けなければならないことに注意してください。

エラー “Whoops！このアクションは許可されていません。このインシデントはレポーターされます。”というエラーが表示された場合は、Slackアカウントで機能フラグの変更が許可されていないか、アクセス権がないことを意味します。

本番前のテスト用に機能を有効化

機能展開の最初のステップとして、staging.gitlab.com とdev.gitlab.org で機能を有効にする必要があります。

この2つの環境は異なるスコープを持っています。dev.gitlab.org は本番CE環境で、GitLab Inc.内部のトラフィックがあり、いくつかの開発やその他の関連作業に使われています。staging.gitlab.com はGitLab.comのデータベースとリポジトリのより小さなサブセットを持ち、通常のトラフィックはありません。ステージングはEEインスタンスで、あなたの機能がGitLab.com上でどのように見え、どのように振る舞うかを（非常に）大まかに見積もることができます。これらのインスタンスはどちらも Sentry に接続されているので、機能フラグを有効にした後、機能をテストしている間にプロジェクトに例外がないか確認してください。

これらのプリプロダクション環境では、視認性を高めるために#staging,#production, あるいは#chatops-ops-testでコマンドを実行することを強く推奨します。

25%の確率で機能を有効にするには、Slackで以下を実行します：

/chatops run feature set new_navigation_bar 25 --random --dev
/chatops run feature set new_navigation_bar 25 --random --staging

GitLab.comの機能を有効にするには

プリプロダクション環境で機能を有効にし、安全に動作することが確認できたら、その変更をGitLab.com（本番環境）にロールアウトすることができます。

機能が非推奨の場合は、フラグを有効にしないでください。

変更を伝える

GitLab.comの機能フラグの変更には、社内の一部と連絡を取るべきものもあります。担当する開発者は、それが必要かどうか、そして適切なコミュニケーションのレベルを判断する必要があります。これは、その機能やどのような影響があるかによって異なります。

ガイドライン

• 事前に#support_gitlab-com 。万が一、その機能がユーザーエクスペリエンスに何らかの副作用を及ぼす場合、機能フラグを緩和して無効にすることで、影響を軽減することができます。
• その機能が変更管理イシューを作成する要件を満たしている場合、クリティカリティガイドラインに従って変更管理イシューを作成してください。
• シンプルで、リスクが低く、簡単にリバートできる機能の場合は、#production](#process) で、[その機能を有効にしてください。
• 特定のグループまたはプロジェクトの機能フラグを切り替えるサポートリクエストについては、サポートワークフローに記載されている手順に従ってください。

プロセス

機能フラグのロールアウトを有効にする際、例えばアクティブな"severity::1" 、~"severity::2" インシデントや進行中の変更イシューがある場合、システムは自動的にChatOpsコマンドの成功をブロックします：

/chatops run feature set gitaly_lfs_pointers_pipeline true

- Production checks fail!
- active incidents

  2021-06-29 Canary deployment failing QA tests

機能フラグを有効にする前に、プロダクション変更ロック期間に違反していないこと、機能フラグと変更管理プロセスを遵守していることを確認してください。

以下の/chatops コマンドは Slack#production チャンネルで実行してください。

機能を有効にし始めたら、最初に行う/chatops コマンドの Slack スレッド内で、関連する機能フラグのロールアウトイシューにリンクしてください。

25%の確率で機能を有効にするには、Slackで以下を実行します：

/chatops run feature set new_navigation_bar 25 --random

これは、次の式に基づいて機能フラグをtrue に設定します：

feature_flag_state = rand < (25 / 100.0)

これは、GitLab.com に対して機能を有効にします。new_navigation_bar は機能の名前です。このコマンドは、全ユーザーの25%に対して機能を有効にするわけではありません。その代わり、enabled? で機能をチェックすると、25%の確率でtrue が返されます。

ユーザー、プロジェクト、グループなどのアクターの25%に対して機能を有効にするには、Slackで以下を実行します：

/chatops run feature set some_feature 25 --actors

これは、次の式に基づいて機能フラグをtrue に設定します：

feature_flag_state = Zlib.crc32("some_feature<Actor>:#{actor.id}") % (100 * 1_000) < 25 * 1_000
# where <Actor>: is a `User`, `Group`, `Project` and actor is an instance

開発中、機能の性質に基づいて、アクタを選択する必要があります。

ユーザー中心の機能の場合：

Feature.enabled?(:feature_cool_avatars, current_user)

グループまたは名前空間レベルの機能の場合：

Feature.enabled?(:feature_cooler_groups, group)

プロジェクトレベルの機能の場合：

Feature.enabled?(:feature_ice_cold_projects, project)

どのパーセンテージを使用すればよいかわからない場合は、以下の手順を使用してください：

1. 25%
2. 50%
3. 75%
4. 100%

各ステップの間に少し待ち、https://dashboards.gitlab.netの適切なグラフをモニターしてください。正確な待機時間は異なります。機能によっては数分で十分なものもあれば、数時間、あるいは数日待つものもあります。ただ、自分のチームと、潜在的な問題が予想される場合はプロダクション・チームに明確に伝えるようにしてください。

フィーチャーゲートは、アクターベースにすることもできます。例えば、あるフィーチャーを最初にgitlab のプロジェクトだけで有効にすることができます。プロジェクトは--project フラグで渡されます：

/chatops run feature set --project=gitlab-org/gitlab some_feature true

--user オプションを使用すると、特定のユーザーに対して機能フラグを有効にすることができます：

/chatops run feature set --user=myusername some_feature true

まず内部でフィードバックを集めたい場合は、gitlab_team_members 機能グループで GitLab チームメンバーに対してユーザーをスコープした機能フラグを有効にすることもできます：

/chatops run feature set --feature-group=gitlab_team_members some_feature true

--group フラグを使えば、特定のグループの機能フラグを有効にすることができます：

/chatops run feature set --group=gitlab-org some_feature true

--group はユーザー・ネームスペースでは機能しないことに注意してください。一般的なネームスペース（グループを含む）の機能フラグを有効にするには、--namespace を使用します：

/chatops run feature set --namespace=gitlab-org some_feature true
/chatops run feature set --namespace=myusername some_feature true

アクター・ベースのゲートはパーセンテージの前に適用されることに注意してください。たとえば、group/project をgitlab-org/gitlab とし、指定された機能例をsome_feature と考えて、以下の 2 つのコマンドを実行するとします：

/chatops run feature set --project=gitlab-org/gitlab some_feature true
/chatops run feature set some_feature 25 --actors

そうすると、some_feature は 25% のアクタで有効になり、gitlab-org/gitlab と相互作用するときは常に有効になります。機能フラグ開発でグループアクタを使用する場合、これは良いアイデアです。

Feature.enabled?(:some_feature, group)

複数のアクタをカンマ区切りで一緒に渡すことができます：

/chatops run feature set --project=gitlab-org/gitlab,example-org/example-project some_feature true

/chatops run feature set --group=gitlab-org,example-org some_feature true

/chatops run feature set --namespace=gitlab-org,example-org some_feature true

最後に、この機能ができるだけ多くのケースで安定していることを確認するために、この機能フラグをグローバルに有効にして、この機能を完全にロールアウトする必要があります：

/chatops run feature set some_feature true

これにより、機能フラグの状態が常に有効に変更され、上記のプロセスにおける既存のゲート（例えば、--group=gitlab-org ）が上書きされます。

アクターベースの機能ゲートが存在する場合、YAML定義のdefault_enabled 属性をfalse からtrue に切り替えても効果がないことに注意してください。機能ゲートは最初に削除されなければなりません。

例えば、機能フラグがChatOpsで設定されているとします：

/chatops run feature set --project=gitlab-org/gitlab some_feature true

YAML定義のdefault_enabled 属性がtrue に切り替えられたとき、望ましい効果を得るためにはフィーチャーゲートを削除しなければなりません：

/chatops run feature delete some_feature

アクターのパーセンテージ vs 時間ロールアウトのパーセンテージ

ある機能がユーザーにとって常にオンまたはオフであることを確認したい場合は、Percentage of actorsロールアウトを使用します。この場合、_パーセンテージオブタイムロールアウトの_使用は避けてください。

パーセンテージオブタイムロールアウトは、Feature.enabled? 機能フラグの Feature.enabled?値がコードパス上で呼び出されるFeature.enabled? たびにランダム化されるため、コード内で複数回使用 Feature.enabled?すると、動作に一貫性がなくなる可能性があります。

機能フラグの無効化

グローバルに有効になっている機能フラグを無効にするには、次のように実行します：

/chatops run feature set some_feature false

特定のプロジェクトで有効になっている機能フラグを無効にするには、以下を実行します：

/chatops run feature set --project=gitlab-org/gitlab some_feature false

機能フラグを実装する特定の方法を適用しない限り、特定のプロジェクト/グループ/ユーザーに対して機能フラグを選択的に無効にすることはできません。

機能フラグがChatOpsによって無効化されている場合は、YAML内のdefault_enabled の値よりも優先されます。言い換えると、ある機能をオンプレミスのインストールでは有効にして、GitLab.comでは無効にすることができます。

アクターによる選択的な無効化

デフォルトでは、アクターによって機能フラグを選択的に無効にすることはできません。

# This will not work how you would expect.
/chatops run feature set some_feature true
/chatops run feature set --project=gitlab-org/gitlab some_feature false

しかし、2つの機能フラグを追加した場合、同等の選択的無効化が可能になるように条件文を記述することができます。

Feature.enabled?(:a_feature, project) && Feature.disabled?(:a_feature_override, project)

# This will enable a feature flag globally, except for gitlab-org/gitlab
/chatops run feature set a_feature true
/chatops run feature set --project=gitlab-org/gitlab a_feature_override true

パーセンテージベースのアクター選択

複数の機能フラグでアクタのパーセンテージロールアウトを使用する場合、各機能フラグのアクタは個別に選択されます。

たとえば、次の機能フラグがある割合のアクタで有効になっているとします：

/chatops run feature set feature-set-1 25 --actors
/chatops run feature set feature-set-2 25 --actors

プロジェクト A で:feature-set-1 が有効になっている場合、プロジェクト A でも:feature-set-2 が有効になっている保証はありません。

詳しくは、「Flipperではパーセントがどのように機能するか」をご覧ください。

機能フラグを有効にした後のメトリクスの検証

機能フラグを有効にした後は、各ステップ間の関連グラフを監視する必要があります：

1. dashboards.gitlab.netにアクセスしてください。
2. feature-flag をオンにします。
3. Latency: Apdex で、変更によって影響を受ける可能性のあるサービス（sidekiq service 、api service 、web serviceなど）を確認します。次に、Service Overview Dashboards を選択し、変更に関連しそうなダッシュボードを選択して、より詳細なダッシュボードをチェックします。

この図では、09:46 で機能フラグを有効にした後、Apdex スコアが低下し始めたことがわかります。その後、機能フラグは10:31 で無効化され、サービスは元の値に戻りました：

機能フラグの変更ロギング

ChatOpsレベル

ChatOps経由でGitLab.com（本番環境）に影響する機能フラグの変更は、自動的にイシューに記録されます。

イシューはgl-infra/feature-flag-logプロジェクトに作成され、機能フラグを有効にした人の Slack ハンドル、時間、変更されたフラグの名前が最低限記録されます。

イシューはGitLab内部のGrafanaダッシュボードにもアノテーションマーカーとして投稿され、変更がより可視化されます。

イシューフォーマットへの変更はChatOpsプロジェクトで提出できます。

インスタンス・レベル

GitLabインスタンスに影響する機能フラグの変更は、features_json.logに自動的に記録されます。Kibana で変更履歴を検索できます。KibanaでGitLab.comの機能フラグ変更履歴にアクセスすることもできます。

クリーンアップ

機能フラグは、不要になったらすぐに削除すべきです。コードベースに機能フラグが追加されるたびに、アプリケーションの複雑さが増し、テストスイートがすべての可能な組み合わせをカバーしているという信頼性が低下します。さらに、いくつかの環境で機能フラグが上書きされると、システムの動作が未定義になり、テストされなくなる可能性があります。

development タイプの機能フラグは、永続的な変更を展開することが目的であるため、ライフサイクルが短いはず developmentです。2マイルストーンより古い機能フラグは、エンジニアリングマネージャに報告されます。レポートツールは月単位で実行されます。例えば、2021年12月のレポートをご覧ください。

development 機能フラグが6ヶ月後もコードベースに残っている場合、次のいずれかのアクションを取る必要があります：

• 機能フラグをデフォルトで有効にし、削除します。
• インスタンス、グループ、プロジェクトの設定に変換します。
• 無効のままで不要になった場合は、変更を戻してください。

機能フラグを削除するには、1つのマージリクエストを開いて変更します。MR：

1. 機能フラグ」ラベルを追加し、リリース管理者が削除を認識できるようにします。
2. マージリクエストを現在のバージョンにバックポートする必要がある場合、パッチリリースのランブックプロセスに従ってください。詳細は機能フラグプロセスを参照してください。
3. テストを含むコードベースから機能フラグへの参照をすべて削除します。
4. リポジトリから機能の YAML 定義を削除します。

上記の MR がマージされたら、次のようにします：

1. /chatops run feature delete some_feature を使って、すべての環境から機能フラグをクリーンアップします。
2. 機能フラグがコードベースから削除された後、機能フラグのロールアウトイシューを閉じます。

ChatOpsのクリーンアップ

機能ゲートがコードベースから削除されても、機能フラグがデプロイされたデータベースには機能レコードが残っています。このレコードは、MRが各環境にデプロイされると削除することができます：

/chatops run feature delete some_feature --dev
/chatops run feature delete some_feature --staging

MR が prod にデプロイされた後、production から削除することができます：

/chatops run feature delete some_feature