Upstream の作成

Upstream は、バックエンド target（各バックエンドインスタンスのホストとポート）のグループを表します。API Gateway は、Upstream の接続、timeout、health check の設定に従って、これらの target に request を load balancing します。

他のモジュールは次のように Upstream を参照します。

モジュール	Upstream の使い方
Route	Backend Target を Via Upstream に設定: Route が Upstream を直接参照します。
Service	Upstream Binding セクション: Service はちょうど 1 つの Upstream に紐付き、Via Service を使う Route がそれを継承します。

ヒント

Route の作成画面（+ Create new Upstream）や Service の作成画面（+ Create a new upstream）から、画面を離れずに Upstream を作成することもできます。

Create Upstream 画面の左側のナビゲーションには、Basic Information → Target → Connection Configuration（Scheme、Load Balancing、Pass Host、Retry & Timeout、Keepalive Pool、TLS Certificate）→ Health Checks → Review のセクションがあります。Basic Information と Target は必須で、両方が有効になった場合にのみ Create ボタンが有効になります。その他のセクションにはデフォルト値があります。

Target は手動で入力するか、API Catalog にある API の server 一覧から取得できます。

Upstream を手動で作成する

ステップ 1Create Upstream をクリックして Create Upstream 画面を開きます

1 / 7

画像をクリックすると拡大します。

Upstream を手動で作成するには、次の手順を実行します。

1. 左側のメニューで API Gateway → Upstream を選択し、右上で API Gateway を選択してから、Create Upstream をクリックします。

2. Basic Information セクションで、次の情報を入力します。

フィールド	必須	説明
Name	Y	Upstream の名前です。一覧に表示され、Route や Service の画面で Upstream を選択するために使われます。英字で始まり、英字 a-z、数字 0-9、_、- のみ使用できます。名前は API Gateway 内で一意である必要があります。
Description	N	Upstream の用途です。後から他の人が理解できるように、どのバックエンドや環境に使うかなどを記述します。

3. Target セクションを選択し、トラフィックを受信するバックエンドインスタンスを宣言します。

フィールド	必須	説明
Target Address	Y	バックエンドインスタンスの IP アドレスまたはホスト名です（例: api.gravitee.io）。各行が load balancing プールの 1 つの target になります。
Port	Y	バックエンドのポートです（1–65535）。
Weight	Y	target の重みです（0–65535、デフォルト 1）。Weight が大きい target ほど多くのトラフィックを受信します。バックエンドのメンテナンス中など、削除せずに target をプールから外す場合は 0 に設定します。

バックエンドに複数のインスタンスがある場合は Add Target をクリックして target を追加し、行末の × をクリックすると target を削除します。Upstream には少なくとも 1 つの target が必要です。

4. API Gateway が target に接続する方法をカスタマイズするには、Connection Configuration のサブセクションを順に選択します。すべてのフィールドにデフォルト値があるため、このステップは省略できます。

Scheme: API Gateway と Upstream 間の protocol です。デフォルトは HTTP です。

値	使用する場面
HTTP / HTTPS	バックエンドが REST API の場合。API Gateway が TLS でバックエンドに接続する必要がある場合は HTTPS を選択します。
gRPC / gRPCs	バックエンドが HTTP/2 上の gRPC サービスの場合。gRPCs は TLS 上の gRPC です。

Load Balancing: request ごとに target を選ぶアルゴリズムです。

値	使用する場面
Round Robin（デフォルト）	Weight に従って request を順番に分散します。クライアントが 1 つの target にとどまる必要のない、独立した target に適しています。
CHash	Consistent Hashing: 同じクライアントは常に同じ target に到達します。キャッシュやセッションアフィニティが必要なバックエンドに適しています。
EWMA	平均レイテンシが最も低い target を優先し、遅い target を自動的に避けます。
Least conn	アクティブな接続数が最も少ない target を選びます。処理時間にばらつきのある request に適しています。

Pass Host: API Gateway が Upstream に request を転送するときの Host ヘッダーの値です。

値	意味
Pass（デフォルト）	クライアントの request の Host ヘッダーをそのまま使います。
Node	target のドメインまたは IP を Host ヘッダーとして使います。
Rewrite	カスタムのホストを使います。選択すると Upstream Host フィールドが表示され、入力が必須になります。

Retry & Timeout: target を呼び出す際のリトライと timeout です。

フィールド	必須	説明
Retries	N	ある target への request が失敗したときに、API Gateway が別の target を試す回数です。デフォルトは 3 です。
Retry Timeout (s)	N	リトライ全体の最大時間です。デフォルトは 5 です。
Connect Timeout (s)	N	target に接続するまでの最大時間です。デフォルトは 60 です。
Send Timeout (s)	N	target への request の送信を完了するまでの最大時間です。デフォルトは 60 です。
Read Timeout (s)	N	target からの response を待つ最大時間で、バックエンドが遅い場合にクライアントが待つ時間になります。デフォルトは 60 です。

注記

Route にも独自の Timeout セクションがあります。Route の作成を参照してください。

Keepalive Pool: target への接続を保持して再利用し、新しい接続を開くコストを減らします。

フィールド	必須	説明
Size	N	再利用のために保持するアイドル接続の最大数です。デフォルトは 320 です。
Idle Timeout (s)	N	アイドル接続を閉じるまで保持する時間です。デフォルトは 60 です。
Requests	N	1 つの接続で処理する request の最大数で、これを超えると接続が置き換えられます。デフォルトは 1000 です。

TLS Certificate: API Gateway が Upstream に接続するときの TLS 検証です。Scheme が HTTPS または gRPCs の場合にのみ適用されます。

フィールド	必須	説明
Verify Upstream Cert	N	オンにすると、API Gateway がバックエンドの TLS 証明書を検証し、なりすましを防ぎます。デフォルトは Disable です。
Client Cert	N	相互 TLS（mTLS）のために API Gateway がバックエンドに提示する、PEM 形式の公開証明書です。
Client Key	N	Client Cert に対応する PEM 形式の秘密鍵です。

5. 障害のある target を API Gateway に検出させ、一時的にプールから外したい場合は、Health Checks セクションを選択します。独立した 2 つの仕組みがあり、どちらもデフォルトではオフです。

Active checks がオンの場合: API Gateway は各 target にチェック request（probe）を定期的に送信します。失敗が多すぎる target はプールから外され、probe が再び成功すると戻ります。

フィールド	必須	説明
Type	N	probe の protocol: HTTP または HTTPs。デフォルトは HTTP です。
HTTPs Verify Certificate	N	HTTPs で probe するときに TLS 証明書を検証します。デフォルトは Disable です。
Timeout (s)	N	各 probe の最大待ち時間です。デフォルトは 1 です。
Concurrency	N	同時に送信する probe の数です。デフォルトは 10 です。
Host、Port、HTTP Path	N	probe を受信するアドレスと path です。HTTP Path のデフォルトは / です。
Healthy Status: Interval、Successes	N	probe の間隔（秒）と、target を正常とみなすための連続成功回数です。デフォルトは 1 と 2 です。
Unhealthy Status: Interval、HTTP Failures	N	probe の間隔（秒）と、target を異常とみなすための失敗回数です。デフォルトは 1 と 5 です。

Passive checks がオンの場合: API Gateway は追加のチェック request を送信せず、実際に通過するトラフィックから target を判定します。

フィールド	必須	説明
Healthy Successes	N	target を正常とみなすための成功 response の数です。
Unhealthy HTTP Failures	N	target を異常とみなすための HTTP エラーの数です。
Unhealthy TCP Failures	N	target を異常とみなすための TCP エラーの数です。

6. Review セクションを選択し、設定全体を確認します。デフォルトのままのセクションには Using defaults.、オフの Health Checks には Disabled. と表示されます。変更する場合は、対応するセクションを選択します。

7. Create をクリックして完了します。

Upstream created successfully というメッセージが表示され、Upstream 画面に戻り、新しい Upstream が一覧の先頭に表示されます。

API Catalog から Upstream を作成する

API が server を宣言した spec 付きで API Catalog にすでに登録されている場合に使います。API の server 一覧から Target が自動入力されるため、手入力は不要です。

ステップ 2Create Upstream from API Catalog をクリックして Select API Catalog フォームを開きます

1 / 5

画像をクリックすると拡大します。

API Catalog から Upstream を作成するには、次の手順を実行します。

1. 左側のメニューで API Gateway → Upstream を選択し、右上で API Gateway を選択してから、Create Upstream をクリックします。

2. Create Upstream from API Catalog をクリックします。Select API Catalog フォームが開き、カタログ内の API が、各 spec で宣言された server の数と server アドレスとともに一覧表示されます。Search API catalog ボックスにキーワードを入力すると、API をすばやく検索できます。

3. API を選択します。フォームが閉じ、API の server 一覧から Target セクションが自動入力され、server URL の protocol に従って Scheme が設定されます（例: https://... の server では Scheme が HTTPS になります）。上部の Prefilled from API Catalog バーには、API 名、target の数、および 2 つのボタンが表示されます。

• Change selection: 別の API を選択します。
• Clear & start blank: 自動入力されたデータを破棄し、手動で最初からやり直します。

警告

Target Address は spec の server URL からそのままコピーされます。spec が完全な URL ではなく相対 path（上の画像のような /api/v3 など）を宣言している場合は、Target Address をバックエンドのホストに変更してください。server が完全な URL（https://host:port）になっている API を使うことをおすすめします。

4. 手動作成のステップ 2–5 と同様に、Basic Information を入力し、必要に応じて他のセクションをカスタマイズします。

5. Review セクションを選択して確認し、Create をクリックします。

よくある問題

エラー	原因	対処方法
名前がすでに存在するため作成が拒否される	この API Gateway に同じ名前の Upstream がすでに存在します	別の名前を使います。
Create ボタンが無効	Name が空か、有効な target がありません（セクションに赤い ⓘ アイコンが表示されます）	ⓘ アイコンのあるセクションを開き、必須フィールドを入力します。

次のステップ

• Upstream の詳細表示
• Via Upstream を使って Route を作成する
• Upstream に紐付く Service を作成する
• Upstream の編集
• Route の作成
• Service の作成