レート制限でインスタンスの安定性を改善する

When automated integrations or scripts send requests to Bamboo in huge bursts, it can affect Bamboo's stability, leading to drops in performance or even downtime. With rate limiting, you can control how many external REST API requests automations and users can make and how often they can make them, making sure that your Bamboo instance remains stable.

Rate limiting is incompatible with Oracle JDBC driver versions earlier than 21.x. If you're using or plan to use Bamboo with Oracle Database, make sure to install or upgrade to Oracle JDBC version 21.x or later. For more information, see Failed to enable rate limiting in Bamboo in the Bamboo Knowledge Base.

レート制限の仕組み

Here’s some details about how rate limiting works in Bamboo.

リクエストの制限

Rate limiting targets only external REST API requests, which means that requests made within Bamboo aren’t limited in any way. When users move around the Bamboo user interface, viewing projects, transitioning issues, and completing other actions, they won’t be affected by rate limiting, as we’re seeing this as a regular user experience that shouldn’t be limited.

次の例で詳しく説明します。

  • When a user views an issue in Bamboo, a number of requests are sent in the background — these requests ask Bambo for comments, assignees, attachments, etc. Since this traffic is internal to Bamboo, it won’t be limited.

  • When the same user opens up the terminal on their laptop and sends a request to get information about an issue, it will be rate limited because it’s made outside of Bamboo.

認証メカニズム

制限対象のリクエストを製品で特定する方法の詳細として、製品では次の認証メカニズムを使用した外部 HTTP リクエストを対象にしています。

  • Basic Auth
  • OAuth
  • JSESSIONID cookie
弊社で採用したレート制限技術について

アトラシアンでは、レート制限に利用できる多数の技術の中から、リクエストに交換可能なトークンの残数をユーザーに示すトークン バケットを採用ました。トークン バケットの仕組みの概要は次のとおりです。

  • ユーザーにはトークンが提供されます。これはリクエストに交換されます。1 つのトークンは 1 件のリクエストに相当します。

  • ユーザーは一定のタイミングで新しいトークンを取得するため、常に新しいリクエストを作成できます。これが許可されたリクエスト数であり、10 個/1 分のように設定されます。

  • トークンは、個人用のバケットが満杯になるまで追加されます。これが最大リクエスト数であり、トークンの使用を独自の頻度に調整できます。たとえば、通常のレートとして指定した 10 件/1 分ではなく、20 件/2 分とすることができます。

  • ユーザーが、自身が保有しているトークン数を超えるリクエストを送信しようとした場合、バケットからトークンを取得できたリクエストのみが成功します。残りのリクエストには 429 エラー メッセージ (too many requests) が返されます。ユーザーは新しいトークンの取得後にこれらのリクエストを再試行できます。

他のアトラシアン製品との連携

Bamboo works best when used with our other products like Bitbucket, or Jira. Technically, products like these are external to Bamboo, so they should be limited. In this case, however, we’re treating them as belonging to the same user experience and don’t want to enforce any limits for requests coming from or to these products.

現在の状況は次のとおりです。

  • Data Center: Not limited in any way.

  • クラウド製品: クラウド製品に送受信されるリクエストにレート制限が適用される、既知の問題があります。アトラシアンではクラウド製品に対するレート制限の無効化に取り組んでおり、近日中に提供を開始する予定です。現時点では回避策を使用できます。詳しくは、「アトラシアン クラウド製品に対するレート制限の削除」を参照してください。

Atlassian Marketplace のアプリ

The general assumption is that Marketplace apps are installed on a Bamboo instance, make internal requests from within Bamboo, and shouldn’t be limited. But, as always, it depends on how an app works.

  • 内部: アプリがユーザー エクスペリエンスの強化のために内部で動作している場合、それは制限されません。このようなアプリの例として、スクラム ボードに表示される特別なバナーなどがあります。このバナーは完了したすべての課題を確認し、このスプリントの勝者、つまり、このスプリントでもっとも多くの課題を完了したユーザーを表示するとします。このようなトラフィックは内部のものになり、制限されません。

  • External: Apps whose requests are external to Bamboo are limited. Let’s say we have an app that displays a wallboard on TV. It asks Bamboo for details about boards, issues, assignees, etc. and then reshuffles and displays them in its own way as the earlier mentioned wallboard. An app like that sends external requests and behaves just like a user sending requests over a terminal.

アプリによって異なりますが、ほとんどのものが制限対象外であると想定しています。

クラスタでのレート制限の仕組み

レート制限は Data Center で利用可能なため、ノードのクラスタがロード バランサの背後にある可能性が高くなります。各ユーザーには、各ノードに個別の制限があります (レート制限はクラスタではなくノードごとに適用されます)。

つまり、1 つのノードで許可されたリクエスト数を使用してレート制限されている場合、別のノードで新しいセッションを開始すると、論理的にはもう一度リクエストを送信できます。ユーザーがノードを切り替えることはできませんが、これが発生する可能性があることを念頭に置いてください。

Whatever limit you’ve chosen (e.g. 100 requests every 1 hour), the same limit will apply to each node, you don’t have to set it separately. This means that each user’s ability to send requests will still be limited, and Bamboo will remain stable regardless of which node their requests are routed to.

管理者による制限の選択基準について

適切な制限の設定は多くの要因に依存するため、単純な回答を提供することはできません。ここではいくつかの提案をご案内させていただきます。

適切な制限を見つける

最初に、インスタンスが受信するトラフィックのサイズを理解します。アクセス ログを解析し、1 日に最大数の REST リクエストを作成したユーザーを見つけます。UI トラフィックはレート制限されないため、この数字はレート制限として必要な値よりも大きくなります。次に、これを基本値とし、以下の質問に基づいてさらに変更します。

  1. ユーザーの作業の中断は許可されますか? ユーザーによる連携機能がミッションクリティカルな場合、代わりにハードウェアをアップグレードすることをご検討ください。連携の重要性に応じて、制限も高く設定する必要があります。算出した数を 2 倍または 3 倍にすることをご検討ください。

  2. インスタンスですでに、REST トラフィックの量による問題が発生していますか? その場合、インスタンスで問題が発生しなかった日の基本値に近い制限を選択します。顕著な問題が発生していないのであれば、基本値に 50% を追加することをご検討ください。これにより、ユーザーの作業が中断されるのを防ぎながら、十分な容量を維持できます。

In general, the limit you choose should keep your instance safe, not control individual users. Rate limiting is more about protecting Bamboo from integrations and scripts going haywire, rather than stoping users from getting their work done.

レート制限を有効化する方法

You need to be a Bamboo Administrator to turn on rate limiting.

レート制限を有効化するには、次の手順を実行します。

  1. Go to Administration > System > Rate limiting.

  2. ステータスを [有効] に変更します。

  3. 次のオプションのうち 1 つを選択します: 無制限のリクエストを許可すべてのリクエストをブロック、またはリクエストを制限。最初のオプションと 2 番目のオプションは許可リストとブロックリストに関連します。最後のオプションの場合、実際の制限を入力する必要はありません。詳細については以下をお読みください。

  4. 保存をクリックします。

  5. 許可リストまたはブロックリストを選択している場合は特に、追加リクエストを本当に必要とするユーザーに例外を追加するようにします。「例外の追加」を参照してください。

リクエストの制限 - 詳細

許可リストやブロックリストと同様に、グローバル設定または例外ではリクエストの制限オプションを頻繁に使用することがあります。

Jira 管理コンソールの [レート制限] ページ。画像の下に注釈の説明があります。

このオプションと仕組みについて詳しく見てみましょう。

  1. 許可されているリクエスト数: 各ユーザーは、選択した期間に特定の件数のリクエストを許可されています。1 秒あたり 10 件のリクエスト、1 時間あたり 100 件のリクエストなどの任意のの設定を選択できます。

  2. 最大リクエスト数 (詳細): リクエストが頻繁に送信されない場合は、許可されているリクエスト数をユーザーあたりの最大数まで貯めることができます。このオプションを使用すると、ユーザーは通常と異なる頻度 (レートで指定された 1 分あたり 10 件の代わりに 2 分あたり 20 件など) でリクエストを作成するか、時間をかけて多くのリクエストを蓄積し、必要に応じて一度に送信できます。最大値の設定が難しい場合、[許可されているリクエスト数] と同じ値に設定することで問題ありません。

例 1: 許可されるリクエストとして 10 件/ 1 時間、最大リクエスト数 100 を設定

許可されるリクエスト: 10 件/時間 | 最大リクエスト数: 100

  • ある開発者は 1 日を通じ、1 時間あたり 10 件のリクエストを定期的に送信します。1 回にまとめて 20 件のリクエストを送信しようとすると、そのうち 10 件のみが成功します。その後の 1 時間で新しいリクエストを作成できるようになったら、残りの 10 件を再試行できます。

  • 別の開発者は過去 10 時間にリクエストを送信していません。そのため、許可されているリクエスト数は最大リクエスト数である 100 に到達するまで蓄積され続けます。これにより、一度に 100 件のリクエストを送信でき、それらすべてが成功するようになります。利用可能なすべてのリクエストを使い果たしたら、1 時間待機することで 10 件のリクエストのみが許可されます。

  • 同じ開発者が 100 件のリクエストのうち 50 件のみを送信した場合、その開発者は直ちに追加で 50 件を送信するか、次の 1 時間で再度蓄積を開始することができます。

例 1: 許可されるリクエストとして 1 件/ 1 秒、最大リクエスト数 60 を設定

許可されるリクエスト: 1 件/秒 | 最大リクエスト数: 60

  • 開発者は、1 秒あたり 1 件のリクエストまたは 毎分 60 件のリクエスト を送信するように任意の頻度を選択できます。

  • 割り当てられた 60 件のリクエストを任意の頻度で使用できるので、それらすべてを一度に使用することも、非常に短い間隔で使用することもできます。このような場合、1 秒あたり 1 件のリクエストという通常のレートを超えることになります。

適切な制限を見つける

管理者による制限の選択基準について

適切な制限の設定は多くの要因に依存するため、単純な回答を提供することはできません。ここではいくつかの提案をご案内させていただきます。

適切な制限を見つける

最初に、インスタンスが受信するトラフィックのサイズを理解します。アクセス ログを解析し、1 日に最大数の REST リクエストを作成したユーザーを見つけます。UI トラフィックはレート制限されないため、この数字はレート制限として必要な値よりも大きくなります。次に、これを基本値とし、以下の質問に基づいてさらに変更します。

  1. ユーザーの作業の中断は許可されますか? ユーザーによる連携機能がミッションクリティカルな場合、代わりにハードウェアをアップグレードすることをご検討ください。連携の重要性に応じて、制限も高く設定する必要があります。算出した数を 2 倍または 3 倍にすることをご検討ください。

  2. インスタンスですでに、REST トラフィックの量による問題が発生していますか? その場合、インスタンスで問題が発生しなかった日の基本値に近い制限を選択します。顕著な問題が発生していないのであれば、基本値に 50% を追加することをご検討ください。これにより、ユーザーの作業が中断されるのを防ぎながら、十分な容量を維持できます。

In general, the limit you choose should keep your instance safe, not control individual users. Rate limiting is more about protecting Bamboo from integrations and scripts going haywire, rather than stoping users from getting their work done.

例外の追加

同様に例外は、他のユーザーよりも多くのリクエストを実際に必要とするユーザーのための特別な制限です。選択した例外は、グローバル設定よりも優先されます。

tip/resting Created with Sketch.

例外を追加または編集した後、変更はすぐに反映されますが、新しい設定がユーザーに適用されるには最大で 1 分かかります。

レート制限から除外されたユーザーが表示された [例外] タブ

例外を追加するには、次の手順を実行します。

  1. [例外] タブを開きます。

  2. [例外の追加] をクリックします。

  3. ユーザーを見つけ、そのユーザーのための新しい設定を選択します。

    • グループを選択することはできませんが、複数のユーザーを選択できます。

    • ここで利用可能なオプションはグローバルな設定の場合と同じです: "無制限のリクエストを許可"、"すべてのリクエストをブロック "、"カスタム制限を割り当て"。

  4. 保存をクリックします。

後から例外を編集したい場合は、[例外] タブでユーザー名の横にある [編集] をクリックします。

推奨: 匿名アクセスへの例外を追加

Bamboo sees all anonymous traffic as made by one user: Anonymous. If your rate limits are not too high, it might happen that a single user drains the limit assigned to anonymous. It’s a good idea to add an exemption for this account with a higher limit, and then observe whether you need to increase it further. 

レート制限されているユーザーの特定

ユーザーがレート制限を受けている場合、HTTP 429 エラー メッセージ (too many requests) が表示されるため、ユーザーはすぐにそのことを確認できます。管理者はレート制限設定ページの [制限を受けているアカウントの一覧] を開いて、レート制限を受けているユーザーを特定できます。一覧には、クラスタ全体のすべてのユーザーが表示されます。

tip/resting Created with Sketch.

ユーザーがレート制限を受けている場合、表に表示されるには最大で 5 分かかります。

制限されたアカウントの一覧。

異常なアカウント

ユーザーは一覧にユーザー名で表示されます。ただし一覧には、いくつかの異常なアカウントが表示される場合があります。以下に例を示します。

  • Unknown: That’s a user that has been deleted in Bamboo. They shouldn’t appear on the list for more than 24 hours (as they can’t be rate limited anymore), but you might see them in the list of exemptions. Just delete any settings for them, they don’t need rate limiting anymore.

  • Anonymous: このエントリは、認証されていないアカウントから行われたすべてのリクエストを収集します。1 人のユーザーで匿名アクセスの制限までのリクエスト数を簡単に使用できてしまうことがあるため、匿名トラフィックに例外を追加して、高い制限値を追加することをおすすめします。

制限付きのリクエストをログ ファイルに追加する

You can also view information about rate limited users and requests in the Bamboo log file. This is useful if you want to get more details about the URLs that requests targeted or originated from.

手順について

制限付きのリクエストをログ ファイルに追加するには、次の手順を実行します。

  1. [管理] > [システム] > [ロギングとプロファイリング] に移動します。

  2. [別のパッケージ用にログ レベルを設定する] をクリックします。

  3. パッケージ名を次のように設定します。 

    com.atlassian.ratelimiting.internal.requesthandler.logging
  4. ロギング レベルを [DEBUG] に設定して [追加] をクリックします。

  5. Every rate limited requests will now appear in the Bamboo log file.

レート制限とは - ユーザーの観点から

ユーザーが認証済みのリクエストを作成すると、レスポンスにレート制限のヘッダーが表示されます。これらのヘッダーはレート制限されているときだけでなく、すべてのレスポンスに追加されます。

ヘッダー説明

X-RateLimit-Limit

保有できるリクエスト (トークン) の最大数。この制限に到達した後は、新しいトークンがバケットに追加されません。管理者はこれを最大リクエスト数として設定します。

X-RateLimit-Remaining

トークンの残りの数。自身が現在保有していて、すぐに使用できるトークン数です。

X-RateLimit-Interval-Seconds

時間間隔 (秒単位)。この間隔ごとに新しいトークンのバッチを取得できます。

X-RateLimit-FillRate

時間間隔ごとに取得するトークンの数。管理者は、これを許可されるリクエスト数として設定します。

retry-after

新しいトークンを取得するまでに待機する必要がある時間。

ユーザーがレート制限を受けていてリクエストが処理されない場合、HTTP 429 エラー メッセージ (too many requests) が返されます。ユーザーはこのヘッダーを使用して、スクリプトや自動化を制限に合わせて調整し、妥当な頻度でリクエストを送信できます。

URL と外部アプリケーションの許可リスト

URL とリソースを許可リストに追加する

We’ve also added a way to allowlist whole URLs and resources on your Bamboo instance. This should be used as quick fix for something that gets rate limited, but shouldn’t.

使用すべきタイミング

For example, a Marketplace app added some new API to Bamboo. The app itself is used from the UI, so it shouldn’t be limited, but it might happen that Bamboo sees this traffic as external and applies the rate limit. In this case, you could disable the app or increase the rate limit, but this brings additional complications.

このような問題を回避するには、アプリによって追加されたリソース全体を許可リストに追加し、それらが制限なしで動作するようにできます。

To add URLs the allowlist, configure -Dcom.atlassian.ratelimiting.whitelisted-url-patterns as a system property with the URLs in a comma-separated list. For example:

-Dcom.atlassian.ratelimiting.whitelisted-url-patterns=/**/rest/applinks/**,/**/rest/capabilities,/**/rest/someapi

For more info on setting system properties, see Configuring your system properties.

For more info on how to create URL patterns, see AntPathMatcher: URL patterns.

外部アプリケーションを許可リストに追加する

コンシューマー キーを許可リストに追加して、アプリケーション リンクを通じて連携された外部アプリケーションのレート制限を削除できます。

Find your app's consumer key

To find your app's consumer key:

  1. Go to  > Overview.

  2. In the left menu, scroll down to Manage apps and select Application links.

  3. Open Incoming authentication and copy the consumer key.

Add the consumer key to the allowlist

To add consumer keys to the allowlist, configure -Dcom.atlassian.ratelimiting.whitelisted-oauth-consumers as a system property with the consumer keys in a comma-separated list.

コンシューマー キーを入力すると、関連するアプリケーションからのトラフィックは制限されなくなります。

レート制限用にコードを調整する

コード (スクリプト、連携、アプリ) に適用してレート制限で使用できる、一連の戦略を作成しました。詳しくは、「レート制限用にコードを調整する」を参照してください。

最終更新日: 2024 年 2 月 1 日

この内容はお役に立ちましたか?

はい
いいえ
この記事についてのフィードバックを送信する

このセクションの項目

Powered by Confluence and Scroll Viewport.