API Gateway コンソールを使用した Canary デプロイメントの作成 AWS CLI を使用して Canary デプロイを作成する

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 リリースのデプロイを作成するには

[API Gateway コンソール] にサインインします。
既存の REST API を選択するか、新しい REST API を作成します。
メインナビゲーションペインで、[リソース] を選択してから [API をデプロイ] を選択します。[API のデプロイ] にある画面の指示に従って API を新しいステージにデプロイします。

ここまでで、API を本稼働リリースステージにデプロイしました。次に、ステージの Canary 設定を編集し、必要に応じて、キャッシュの有効化、ステージ変数の設定、または API 実行またはアクセスログの設定を行います。
API キャッシュを有効にするか、AWS WAF Web ACL をステージに関連付けるには、[ステージの詳細] セクションで [編集] を選択します。詳細については、「API キャッシュを有効にして応答性を強化する」または「API Gateway コンソールを使用して AWS WAF ウェブ ACL を API Gateway API ステージに関連付けるには」を参照してください。
実行またはアクセスログを設定するには、[ログとトレース] セクションで、[編集] を選択して画面の手順に従います。詳細については、「API Gateway での CloudWatch による REST API のログの設定」を参照してください。
ステージ変数を設定するには、[ステージ変数] タブを選択し、画面の手順に従ってステージ変数を追加または変更します。詳細については、「REST API デプロイのステージ変数のセットアップ」を参照してください。
[Canary] タブを選択し、[Canary の作成] を選択します。[Canary] タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
[Canary 設定] の [Canary] で、canary に転送されるリクエストの割合を入力します。
必要に応じて、[ステージキャッシュ] を選択し、Canary リリースのキャッシュを有効にします。API キャッシュが有効になるまでは Canary リリースのキャッシュは使用できません。
既存のステージ変数を上書きするには、[Canary の上書き] に新しいステージ変数値を入力します。

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

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

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


aws apigateway create-deployment \
    --variables sv0=val0,sv1=val1 \
    --rest-api-id abcd1234 \
    --stage-name 'prod' \

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


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

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

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


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

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


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

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


aws apigateway get-stage --rest-api-id acbd1234 --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 abcd1234 \
    --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 \
    --rest-api-id abcd1234 \
    --stage-name 'beta' \
    --patch-operations '[{
            "op": "replace",
            "value": "0.0",
            "path": "/canarySettings/percentTraffic"
        }, {
            "op": "copy",
            "from": "/canarySettings/stageVariableOverrides",
            "path": "/variables"
        }, {
            "op": "copy",
            "from": "/canarySettings/deploymentId",
            "path": "/deploymentId"
        }]'

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


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

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

Canary リリースのデプロイをセットアップする

Canary リリースの更新

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

トピック

API Gateway コンソールを使用した Canary デプロイメントの作成

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

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

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