Amazon API Gateway
開発者ガイド

Canary リリースのデプロイを作成する

Canary 設定デプロイ作成オペレーションへの追加の入力として API をデプロイする場合は、Canary リリースのデプロイを作成します。

また、Canary 設定をステージに追加する stage:update リクエストをすることで、既存の非 Canary デプロイから Canary リリースのデプロイを作成することもできます。

非 Canary リリースのデプロイを作成する場合、存在しないステージ名を指定できます。指定されたステージが存在しない場合、API Gateway がそれを作成します。ただし、Canary リリースのデプロイを作成する場合は、存在しないステージ名を指定することはできません。エラーが表示され、API Gateway は Canary リリースのデプロイを作成しません。

API Gateway で Canary リリースのデプロイを作成するには、API Gateway コンソール、AWS CLI、および AWS SDK を使用します。

API Gateway コンソールを使用して Canary デプロイを作成する

API Gateway コンソールを使用して Canary デプロイのリリースを作成するには、以下の手順に従います。

最初の Canary リリースのデプロイを作成するには

  1. API Gateway コンソールにサインインします。

  2. 既存の API を選択するか、新しい API を作成します。

  3. 必要に応じて API を変更するか、または目的の API メソッドと統合をセットアップします。

  4. [アクション] ドロップダウンメニューから [API のデプロイ] を選択します。[API のデプロイ] にある画面の指示に従って API を新しいステージにデプロイします。

    ここまでで、API を本稼働リリースステージにデプロイしました。次に、ステージの Canary 設定を編集し、必要に応じて、キャッシュの有効化、ステージ変数の設定、または API 実行またはアクセスログの設定を行います。

  5. API キャッシュを有効にするには、[ステージエディタ] の [設定] タブを選択して画面の手順に従います。詳細については、「API キャッシュを有効にして応答性を強化する」を参照してください。

  6. ステージ変数を設定するには、[ステージエディタ] の [ステージ変数] タブを選択し、画面の手順に従ってステージ変数を追加または変更します。詳細については、「REST API デプロイのステージ変数を設定する」を参照してください。

  7. 実行またはアクセスログを設定するには、[ステージエディタ] の [ログ] タブを選択して画面の手順に従います。詳細については、「API Gateway CloudWatch の API ログ作成をセットアップする」を参照してください。

  8. [ステージエディタ] で、[Canary] タブを選択し、[Canary の作成] を選択します。

  9. [ステージのリクエストディストリビューション] セクションで、[Percentage of requests to Canary (Canary へのリクエストの割合)] の横にある鉛筆アイコンを選択して、入力テキストフィールドに数字 (5.0 など) を入力します。チェックマークアイコンを選択して、設定を保存します。

  10. AWS WAF ウェブ ACL をステージに関連付けるには、[ウェブ ACL] ドロップダウンリストからウェブ ACL を選択します。

    注記

    必要に応じて、[ウェブ ACL を作成する] を選択して新しいブラウザタブで AWS WAF コンソールを開き、ウェブ ACL を作成し、API Gateway コンソールに戻ってウェブ ACL をステージに関連付けます。

  11. 必要に応じて、[Block API Request if WebACL cannot be evaluated (Fail- Close) (WebACL を評価できない場合は API リクエストをブロックする (フェイルクローズ))] を選択します。

  12. 必要に応じて、[Add Stage Variables (ステージ変数の追加)] を選択し、[Canary ステージ変数] セクションで追加して既存のステージ変数を上書きするか、または Canary リリースの新しいステージ変数を追加します。

  13. 必要に応じて、[ステージキャッシュの使用を有効化] を選択して Canary リリースのキャッシュを有効にし、選択を保存します。API キャッシュが有効になるまでは Canary リリースのキャッシュは使用できません。

Canary リリースがデプロイステージで初期化された後、API を変更して変更をテストできます。更新されたバージョンとベースバージョンの両方に同じステージからアクセスできるように、同じステージに API を再デプロイできます。以下のステップでは、その方法について説明します。

最新の API バージョンを Canary にデプロイするには

  1. 各 API の更新で、[リソース] リストの横にある [アクション] ドロップダウンメニューから [API のデプロイ] を選択します。

  2. [API のデプロイ] で、[デプロイされるステージ] ドロップダウンリストから現在 Canary が有効なステージを選択します。

  3. (オプション) [デプロイメントの説明] に説明を入力します。

  4. [デプロイ] を選択し、最新の API バージョンを Canary リリースにプッシュします。

  5. 必要に応じて、最初の Canary リリースのデプロイを作成するには の説明にあるとおり、ステージ設定、ログ、または Canary 設定を再設定します。

その結果、Canary リリースは最新バージョンを指し、本稼働リリースは API の最初のバージョンを指します。[canarySettings] は新しい [deploymentId] 値を持つようになりますが、ステージはまだ初期 [deploymentId] 値です。内部的には、コンソールは [stage:update] を呼び出します。

AWS CLI を使用して Canary デプロイを作成する

まず、2 つのステージ変数で、Canary なしでベースラインデプロイを作成します。

aws apigateway create-deployment --variables sv0=val0,sv1=val1 --rest-api-id 4wk1k4onj3 --stage-name prod

このコマンドは、次のような Deployment を結果とする表現を返します。

{ "id": "du4ot1", "createdDate": 1511379050 }

結果的に生じるデプロイ id により API のスナップショット (またはバージョン) が識別されます。

次に、prod ステージの Canary デプロイを作成します。

aws apigateway create-deployment --canary-settings '{ \ "percentTraffic":10.5, \ "useStageCache":false, \ "stageVariableOverrides":{ \ "sv1":"val2", \ "sv2":"val3" \ } \ }' \ --rest-api-id 4wk1k4onj3 \ --stage-name prod

指定されたステージ (prod) が存在しない場合、前述のコマンドはエラーを返します。それ以外の場合は、次のような新しく作成した deployment リソースの表現を返します。

{ "id": "a6rox0", "createdDate": 1511379433 }

結果的に生じるデプロイ id により Canary リリースの API のテストバージョンが識別されます。その結果、関連付けられたステージは Canary が有効になっています。get-stage コマンドを呼び出して、このステージの表現を表示できます。次のようになります。

aws apigateway get-stage --rest-api-id 4wk1k4onj3 --stage-name prod

以下に示すのは、コマンドの出力としての Stage の表現です。

{ "stageName": "prod", "variables": { "sv0": "val0", "sv1": "val1" }, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": "du4ot1", "lastUpdatedDate": 1511379433, "createdDate": 1511379050, "canarySettings": { "percentTraffic": 10.5, "deploymentId": "a6rox0", "useStageCache": false, "stageVariableOverrides": { "sv2": "val3", "sv1": "val2" } }, "methodSettings": {} }

この例では、ベースバージョンの API は {"sv0":val0", "sv1":val1"} のステージ変数を使用し、テストバージョンではステージ変数 {"sv1":val2", "sv2":val3"} を使用します。本稼働リリースと Canary リリースの両方が同じステージ変数 sv1 を使用しますが、それぞれ別の値、val1 および val2 をそれぞれ使用します。ステージ変数 sv0 は本稼働リリースでのみ使用され、ステージ変数 sv2 は Canary リリースでのみ使用されます。

既存の通常のデプロイから Canary リリースのデプロイを作成するには、Canary が有効になるようにステージを更新します。これを示すため、まず通常のデプロイを作成します。

aws apigateway create-deployment \ --variables sv0=val0,sv1=val1 \ --rest-api-id 4wk1k4onj3 \ --stage-name beta

このコマンドは、ベースバージョンのデプロイの表現を返します。

{ "id": "cifeiw", "createdDate": 1511380879 }

関連付けられたベータステージには Canary 設定がありません。

{ "stageName": "beta", "variables": { "sv0": "val0", "sv1": "val1" }, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": "cifeiw", "lastUpdatedDate": 1511380879, "createdDate": 1511380879, "methodSettings": {} }

次に、ステージの Canary をアタッチすることで、新しい Canary リリースのデプロイを作成します。

aws apigateway update-stage \ --patch-operations '[{ \ "op":"replace", \ "path":"/canarySettings/percentTraffic", \ "value":"10.5" \ },{ \ "op":"replace", \ "path":"/canarySettings/useStageCache", \ "value":"false" \ },{ \ "op":"replace", \ "path":"/canarySettings/stageVariableOverrides/sv1", \ "value":"val2" \ },{ \ "op":"replace", \ "path":"/canarySettings/stageVariableOverrides/sv2", \ "value":"val3" \ }]' \ --rest-api-id 4wk1k4onj3 \ --stage-name beta

更新されたステージの表現は次のようになります。

{ "stageName": "beta", "variables": { "sv0": "val0", "sv1": "val1" }, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": "cifeiw", "lastUpdatedDate": 1511381930, "createdDate": 1511380879, "canarySettings": { "percentTraffic": 10.5, "deploymentId": "cifeiw", "useStageCache": false, "stageVariableOverrides": { "sv2": "val3", "sv1": "val2" } }, "methodSettings": {} }

既存のバージョンの API で Canary を先ほど有効にしたので、本稼働リリース (Stage) および Canary リリース (canarySettings) 両方が同じデプロイ、つまり、同じバージョンの API (deploymentId) を指します。API を変更して再度このステージにデプロイした後、新しいバージョンは Canary リリースに入り、ベースバージョンは本稼働リリースに残ります。これは、ステージ進化で明らかになります。Canary リリースの deploymentId は新しいデプロイ id に更新され、本稼働リリースの deploymentId は変更されません。