# Canary リリースのデプロイを作成する
[Canary 設定](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html#canarySettings)で[デプロイ作成](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html)オペレーションへの追加の入力として API をデプロイする場合は、Canary リリースのデプロイを作成します。
また、Canary 設定をステージに追加する [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) リクエストを行うことで、既存の非カナリアデプロイから Canary リリースのデプロイを作成することもできます。
非 Canary リリースのデプロイを作成する場合、存在しないステージ名を指定できます。指定されたステージが存在しない場合、API Gateway がそれを作成します。ただし、Canary リリースのデプロイを作成する場合は、存在しないステージ名を指定することはできません。エラーが表示され、API Gateway は Canary リリースのデプロイを作成しません。
API Gateway コンソール、AWS CLI、または AWS SDK を使用して、API Gateway で Canary リリースデプロイを作成できます。
**Topics**
+ [API Gateway コンソールを使用したカナリアデプロイの作成](#create-canary-deployment-using-console)
+ [AWS CLI を使用してカナリアデプロイを作成する](#create-canary-deployment-using-cli)
## API Gateway コンソールを使用したカナリアデプロイの作成
API Gateway コンソールを使用して Canary デプロイのリリースを作成するには、以下の手順に従います。
**最初の Canary リリースのデプロイを作成するには**
1. [API Gateway コンソール] にサインインします。
1. 既存の REST API を選択するか、新しい REST API を作成します。
1. メインナビゲーションペインで、**[リソース]** を選択してから **[API をデプロイ]** を選択します。[**API のデプロイ**] にある画面の指示に従って API を新しいステージにデプロイします。
ここまでで、API を本稼働リリースステージにデプロイしました。次に、ステージの Canary 設定を編集し、必要に応じて、キャッシュの有効化、ステージ変数の設定、または API 実行またはアクセスログの設定を行います。
1. API キャッシュを有効にするか、AWS WAF Web ACL をステージに関連付けるには、**[ステージの詳細]** セクションで **[編集]** を選択します。詳細については、「[API Gateway での REST API のキャッシュ設定](api-gateway-caching.md)」または「[API Gateway コンソールを使用して AWS WAF ウェブ ACL を API Gateway API ステージに関連付けるには](apigateway-control-access-aws-waf.md#apigateway-control-access-aws-waf-console)」を参照してください。
1. 実行またはアクセスログを設定するには、**[ログとトレース]** セクションで、**[編集]** を選択して画面の手順に従います。詳細については、「[API Gateway で REST API の CloudWatch ログ記録を設定する](set-up-logging.md)」を参照してください。
1. ステージ変数を設定するには、**[ステージ変数]** タブを選択し、画面の手順に従ってステージ変数を追加または変更します。詳細については、「[API Gateway で REST API のステージ変数を使用する](stage-variables.md)」を参照してください。
1. **[Canary]** タブを選択し、**[Canary の作成]** を選択します。**[Canary]** タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. **[Canary 設定]** の **[Canary]** で、canary に転送されるリクエストの割合を入力します。
1. 必要に応じて、**[ステージキャッシュ]** を選択し、Canary リリースのキャッシュを有効にします。API キャッシュが有効になるまでは Canary リリースのキャッシュは使用できません。
1. 既存のステージ変数を上書きするには、**[Canary の上書き]** に新しいステージ変数値を入力します。
Canary リリースがデプロイステージで初期化された後、API を変更して変更をテストできます。更新されたバージョンとベースバージョンの両方に同じステージからアクセスできるように、同じステージに API を再デプロイできます。以下のステップでは、その方法について説明します。
**最新の API バージョンを Canary にデプロイするには**
1. 各 API の更新で、**[API のデプロイ]** を選択します。
1. **[API のデプロイ]** で、**[デプロイされるステージ]** ドロップダウンリストから Canary を含むステージを選択します。
1. (オプション)**[デプロイの説明]** に、デプロイの説明を入力します。
1. [**デプロイ**] を選択し、最新の API バージョンを Canary リリースにプッシュします。
1. 必要に応じて、[最初の Canary リリースのデプロイを作成するには](#to-create-canary-release-on-new-deployment) の説明にあるとおり、ステージ設定、ログ、または Canary 設定を再設定します。
その結果、Canary リリースは最新バージョンを指し、本稼働リリースは API の最初のバージョンを指します。[[https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings)] には新しい [**deploymentId**] 値ができていますが、ステージには引き続き当初の [[https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId)] があります。内部では、コンソールは [[**stage:update**]](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) を呼び出します。
## AWS CLI を使用してカナリアデプロイを作成する
**新しいステージのカナリアデプロイを作成するには**
1. 次の [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) コマンドを使用して、2 つのステージ変数を含むデプロイを作成しますが、Canary は作成しません。
```
aws apigateway create-deployment \
--variables sv0=val0,sv1=val1 \
--rest-api-id abcd1234 \
--stage-name 'prod'
```
出力は次のようになります。
```
{
"id": "du4ot1",
"createdDate": 1511379050
}
```
1. 次の [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) コマンドを使用して、`prod` ステージにカナリアデプロイを作成します。
```
aws apigateway create-deployment \
--rest-api-id abcd1234 \
--canary-settings percentTraffic=10.5,stageVariableOverrides={sv1='val2',sv2='val3'},useStageCache=false \
--stage-name 'prod'
```
出力は次のようになります。
```
{
"id": "a6rox0",
"createdDate": 1511379433
}
```
結果的に生じるデプロイ `id` により Canary リリースの API のテストバージョンが識別されます。その結果、関連付けられたステージは Canary が有効になっています。
1. (オプション) 次の [get-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-stage.html) コマンドを使用して、ステージ表現を表示します。
```
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 が有効になるようにステージを更新します。
**既存のデプロイから Canary リリースデプロイを作成するには**
1. [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) コマンドを使用して、Canary なしのデプロイを作成します。
```
aws apigateway create-deployment \
--variables sv0=val0,sv1=val1 \
--rest-api-id abcd1234 \
--stage-name 'beta'
```
1. [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) コマンドを使用して、ステージを更新して 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 を変更して再度このステージにデプロイした後、新しいバージョンは Canary リリースに入り、ベースバージョンは本稼働リリースに残ります。これは、ステージ進化で明らかになります。Canary リリースの `deploymentId` は新しいデプロイ `id` に更新され、本稼働リリースの `deploymentId` は変更されません。