メニュー
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 REST API を使用します。

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

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

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

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

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

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

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

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

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

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

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

  8. [Stage Editor] で、[Canary] タブを選択し、[Create Canary] を選択します。

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

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

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

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

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

  1. 各 API の更新で、[Resources] リストの横にある [Actions] ドロップダウンメニューから [Deploy API] を選択します。

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

  3. (オプション) [Deployment description] に説明を入力します。

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

  5. 必要に応じて、 の説明にあるとおり、ステージ設定、ログ、または 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 は変更されません。

API Gateway API を使用して Canary デプロイを作成する

API Gateway REST API を使用して API を Canary リリースとしてデプロイするには、次のように deployment:create を呼び出します。

POST /restapis/fugvjdxtri/deployments HTTP/1.1 Content-Type: application/json Host: apigateway.us-east-1.amazonaws.com X-Amz-Date: 20171103T175605Z Authorization: AWS4-HMAC-SHA256 Credential={SECRET_ACCESS_KEY}/20160603/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={SIGV4_SIGNATURE} { "stageName" : "prod", "stageDescription" : "Production stage", "description" : "Production deployment with canary", "variables" : { "sv1" : "val1" }, "canarySettings": { "percentTraffic": 10.5, "useStageCache": false, "stageVariableOverrides": { "sv1": "val2", "sv2": "val3" } } }

成功すると、これが初めてステージに API をデプロイする場合は、まったく新しい Canary リリースのデプロイ (nfcn0x) を受け取ります。

{ "_links": { ... }, "createdDate": "2017-11-22T00:54:28Z", "description": "Production deployment with canary", "id": "nfcn0x" }

このデプロイでは、ステージと Canary の両方が同じ deploymentId を持ちます。つまり、どちらも同じ API バージョンを参照します。

同じステージへの後続の API デプロイでは、Canary がそのステージで無効にされるまでは常に canarySettings を入力として指定する必要があります。たとえば、以前の deployment:create リクエストを 2 回目に呼び出すときは、結果として新しいデプロイ (eh1sby) を受け取ります。

{ "_links": { ... }, "createdDate": "2017-11-22T01:24:23Z", "description": "Production deployment with canary", "id": "eh1sby" }

より新しい deploymentId の値が canarySettings に設定され、Canary は新しい API バージョンを表します。一方、最初の deploymentId は最初の API バージョンを表すステージに関連付けされたままになります。これを確認するには、GET /restapis/fugvjdxtri/stages/prod リクエストを呼び出して成功したレスポンスペイロードを調べます。

{ "_links": { ... }, "accessLogSettings": { ... }, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "canarySettings": { "deploymentId": "eh1sby", "useStageCache": false, "stageVariableOverrides": { "sv2": "val3", "sv1": "val2" }, "percentTraffic": 10.5 }, "createdDate": "2017-11-20T04:42:19Z", "deploymentId": "nfcn0x", "lastUpdatedDate": "2017-11-22T00:54:28Z", "methodSettings": { "*/*": { "dataTraceEnabled": true, "throttlingRateLimit": 10000, "cacheTtlInSeconds": 300, "cachingEnabled": false, "requireAuthorizationForCacheControl": true, "metricsEnabled": true, "loggingLevel": "INFO", "unauthorizedCacheControlHeaderStrategy": "SUCCEED_WITH_RESPONSE_HEADER", "throttlingBurstLimit": 5000, "cacheDataEncrypted": false } }, "stageName": "canary", "variables": { "sv1": "val1" } }

関連するステージで有効な Canary がない通常の本稼働デプロイでは、ステージで Canary を有効にすることでデプロイを Canary リリースデプロイにすることができます。これを行うには、次に示すように stage:update を呼び出します。元のデプロイ ID を ghdx4w と想定しています。

PATCH /restapis/4wk1k4onj3/stages/prod HTTP/1.1 Host: apigateway.us-east-1.amazonaws.com Content-Type: application/json X-Amz-Date: 20171121T232431Z Authorization: AWS4-HMAC-SHA256 Credential={SECRET_ACCESS_KEY}/20171121/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={SIGV4_SIGNATURE} { "patchOperations": [ { "op": "replace", "path": "/canarySettings/deploymentId", "value": "ghdx4w" }, { "op": "replace", "path": "/canarySettings/percentTraffic", "value": "15.0" } ] }

元のデプロイは Canary リリースがないため、/canarysettings/deploymentId の値をデプロイステージに関連付けされた deploymentId("ghdx4w") に設定します。

レスポンスが成功すると、次のようなペイロードを返します。

{ "_links": { ... }, "accessLogSettings": { ... }, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "canarySettings": { "deploymentId": "ghdx4w", "useStageCache": false, "stageVariableOverrides": null, "percentTraffic": 15 }, "createdDate": "2017-11-20T04:42:19Z", "deploymentId": "ghdx4w", "lastUpdatedDate": "2017-11-21T23:24:31Z", "methodSettings": { "*/*": { "dataTraceEnabled": true, "throttlingRateLimit": 10000, "cacheTtlInSeconds": 300, "cachingEnabled": false, "requireAuthorizationForCacheControl": true, "metricsEnabled": true, "loggingLevel": "INFO", "unauthorizedCacheControlHeaderStrategy": "SUCCEED_WITH_RESPONSE_HEADER", "throttlingBurstLimit": 5000, "cacheDataEncrypted": false } }, "stageName": "prod" }

Canary がステージで有効になっていると、デプロイは Canary リリースのデプロイになります。Canary 設定がステージから削除されるまで、ステージは非 Canary のデプロイに関連付けることはできません。