Canary リリースのデプロイを作成する - Amazon API Gateway

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

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

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

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

API Gateway コンソール、AWS CLI、または AWS SDK を使用して、API Gateway で Canary リリースデプロイを作成できます。

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 による REST API のログの設定」を参照してください。

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

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

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

    注記

    必要に応じて、[Create Web 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) が存在しない場合、前述のコマンドはエラーを返します。それ以外の場合は、次のような新しく作成したデプロイリソースの表現を返します。

{ "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 は変更されません。