Amazon API Gateway
開発者ガイド

Canary リリースの昇格

Canary リリースを昇格させると、本稼働ステージでテスト中の API バージョンを使用可能にできます。オペレーションには次のタスクが含まれます。

  • ステージのデプロイ ID を Canary のデプロイ ID 設定でリセットします。これによりステージの API スナップショットが Canary のスナップショットで更新され、テストバージョンを本稼働リリースにもします。

  • Canary のステージ変数でステージ変数を更新する (存在する場合)これによりステージの API 実行コンテキストが Canary のもので更新されます。この更新をしないと、テストバージョンでさまざまなステージ変数やさまざまな既存のステージの値を使用している場合、新しい API バージョンで予期しない結果が生じる場合があります。

  • Canary トラフィックの割合を 0.0% に設定します。

Canary リリースが昇格してもステージで Canary は無効になりません。Canary を無効にするには、ステージで Canary 設定を削除する必要があります。

API Gateway コンソールを使用して Canary リリースを昇格させる

API Gateway コンソールを使用して Canary リリースのデプロイを昇格させるには、以下を実行します。

  1. API Gateway コンソールにサインインし、プライマリナビゲーションペインで既存の API を選択します。

  2. API の下にある [ステージ] を選択し、[ステージ] リストの下にある既存のステージを選択して [ステージエディター] を開きます。

  3. [設定] の [Canary] タブを選択します。

  4. [Canary の昇格] を選択します。

  5. 変更内容を確認し、[更新] を選択します。

昇格後、本稼働リリースは Canary リリースと同じ API バージョン (deploymentId) を参照します。これを確認するには、AWS CLI または API Gateway REST API を使用します。たとえば、AWS CLI を使用して Canary リリースを昇格させる または API Gateway REST API を使用して Canary リリースを昇格させる を参照します。

AWS CLI を使用して Canary リリースを昇格させる

AWS CLI コマンドを使用して Canary リリースを本稼働リリースに昇格させるには、update-stage コマンドを呼び出して Canary に関連付けられた deploymentId をステージに関連付けられた deploymentId にコピーし、Canary トラフィックの割合をゼロ (0.0) にリセットして、Canary にバインドされたステージ変数を対応するステージにバインドされた変数にコピーします。

Suppose we have a canary release deployment, described by a stage similar to the following:

{ "_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": { ... }, "stageName": "prod", "variables": { "sv1": "val1" } }

以下の update-stage リクエストを呼び出して昇格させることができます。

aws apigateway update-stage \ --rest-api-id {rest-api-id} \ --stage-name '{stage-name}' \ --patch-operations '[{ \ "op": "replace", \ "value": "0.0" \ "path": "/canarySettings/percentTraffic", \ }, { \ "op": "copy", \ "from": "/canarySettings/stageVariableOverrides", \ "path": "/variables", \ }, { \ "op": "copy", \ "from": "/canarySettings/deploymentId", \ "path": "/deploymentId" \ }]'

After the promotion, the stage now looks like this:

{ "_links": { ... }, "accessLogSettings": { ... }, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "canarySettings": { "deploymentId": "eh1sby", "useStageCache": false, "stageVariableOverrides": { "sv2": "val3", "sv1": "val2" }, "percentTraffic": 0 }, "createdDate": "2017-11-20T04:42:19Z", "deploymentId": "eh1sby", "lastUpdatedDate": "2017-11-22T05:29:47Z", "methodSettings": { ... }, "stageName": "prod", "variables": { "sv2": "val3", "sv1": "val2" } }

As you can see, promoting a canary release to the stage does not disable the canary and the deployment remains to be a canary release deployment. To make it a regular production release deployment, you must disable the canary settings. For more information about how to disable a canary release deployment, see Canary リリースを無効にする.

API Gateway REST API を使用して Canary リリースを昇格させる

API Gateway REST API を使用して Canary リリースを本稼働リリースに昇格させるには、stage:update リクエストを呼び出して Canary に関連付けられた deploymentId をステージに関連付けられた deploymentId にコピーし、Canary トラフィックの割合をゼロ (0.0) にリセットして、Canary にバインドされたステージ変数を対応するステージにバインドされた変数にコピーします。

Suppose we have a canary release deployment, described by a stage similar to the following:

{ "_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": { ... }, "stageName": "prod", "variables": { "sv1": "val1" } }

以下の stage:update リクエストを呼び出して昇格させることができます。

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": "copy", "path": "/deploymentId", "from": "/canarySettings/deploymentId" }, { "op": "replace", "path": "/canarySettings/percentTraffic", "value": "0.0" }, { "op": "copy", "path": "/variables", "from": "/canarySettings/stageVariableOverrides" } ] }

After the promotion, the stage now looks like this:

{ "_links": { ... }, "accessLogSettings": { ... }, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "canarySettings": { "deploymentId": "eh1sby", "useStageCache": false, "stageVariableOverrides": { "sv2": "val3", "sv1": "val2" }, "percentTraffic": 0 }, "createdDate": "2017-11-20T04:42:19Z", "deploymentId": "eh1sby", "lastUpdatedDate": "2017-11-22T05:29:47Z", "methodSettings": { ... }, "stageName": "prod", "variables": { "sv2": "val3", "sv1": "val2" } }

As you can see, promoting a canary release to the stage does not disable the canary and the deployment remains to be a canary release deployment. To make it a regular production release deployment, you must disable the canary settings. For more information about how to disable a canary release deployment, see Canary リリースを無効にする.