# 安全な Canary 更新の実行
<a name="performing-safe-canary-upgrades"></a>

CloudWatch Synthetics の安全な Canary 更新機能を使用すると、既存の Canary の更新をテストしたうえで変更を適用できます。この機能は新しいランタイムと Canary の互換性の検証や、コードやメモリの変更のような設定変更を確認するのに役立ちます。これにより、更新内容の誤りが原因でモニタリングの中断が発生するのを最小限に抑えることができます。

Canary の安全な更新機能を使用してランタイムのバージョン更新や設定変更、コードスクリプトの修正を行うことで、リスクを緩和し、無停止でモニタリングを継続し、コミットや更新前に変更内容を検証し、ダウンタイムを抑えるなど、さまざまなメリットを得られます。

**Topics**
+ [前提条件](#performing-safe-canary-upgrades-prereq)
+ [ベストプラクティス](#performing-safe-canary-upgrades-best-practices)
+ [ドライランを使用した Canary のテスト](#performing-safe-canary-upgrades-getting-started)
+ [制限事項](#performing-safe-canary-upgrades-limitations)

## 前提条件
<a name="performing-safe-canary-upgrades-prereq"></a>

前提条件を満たしていることを確認してください。
+ CloudWatch Synthetics へのアクセス権限がある AWS アカウント
+ 既存の Canary とサポート対象のランタイムバージョン (互換性のあるランタイムについては「[制限事項](#performing-safe-canary-upgrades-limitations)」を参照)
+ ドライランの実行時に互換性のあるランタイムを含める (互換性のあるランタイムについては「[制限事項](#performing-safe-canary-upgrades-limitations)」を参照)

## ベストプラクティス
<a name="performing-safe-canary-upgrades-best-practices"></a>

Canary を実行する際のベストプラクティスには、次のものがあります。
+ ドライランを実行してランタイムの更新を検証する
+ Canary に本番環境用の更新を適用する前にドライランを実行する
+ ドライランの実行後に Canary ログとアーティファクトを確認する
+ ドライランを利用して依存関係とライブラリの互換性を検証する

## ドライランを使用した Canary のテスト
<a name="performing-safe-canary-upgrades-getting-started"></a>

Canary の更新のテストでは、次のオプションを使用できます。

 **AWS マネジメントコンソール の編集ワークフローの使用** 

1. CloudWatch Synthetics コンソールに移動します。

1. 更新する Canary を選択します。

1. **[アクション]** ドロップダウンから、**[編集]** を選択します。

   テストを行う変更内容を使用して Canary を更新します。例えば、ランタイムバージョンの変更やスクリプトのコードの編集などの変更です。

1. **[Canary スクリプト]** で、テスト後に直ちに結果を確認する場合は **[ドライランを開始]** を選択します。テストを開始して、後で **[Canary の詳細]** ページから結果を確認する場合は、ページ下部の **[検証して結果を保存]** を選択します。

1. ドライランが正常に終了したら、**[送信]** を選択して Canary の更新をコミットします。

 **AWS マネジメントコンソール を使用して Canary を一括で更新する** 

1. CloudWatch Synthetics コンソールに移動します。

1. **Synthetics** の一覧ページを選択します。

1. ランタイムを更新する Canary を 5 つまで選択します。

1. **[アクション]** ドロップダウンメニューから、**[ランタイムを更新]** を選択します。

1. **[新しいランタイムのドライランを開始]** を選択してドライランを開始し、更新前に変更をテストします。

1. **[Synthetics]** 一覧ページには、Canary の **[ランタイム]** バージョン表記の横に、ドライランの進行状況を示すテキストが表示されます (ドライランでランタイムの更新を伴う場合のみ)。

   ドライランが正常に終了すると、**[更新を開始]** というテキストが表示されます。

1. **[更新を開始]** を選択して、ランタイム更新をコミットします。

1. ドライランが失敗した場合、**[ドライランの更新に失敗]** というテキストが表示されます。テキストを選択すると、Canary の詳細ページに移動するデバッグリンクが表示されます。

 **AWS CLI または SDK を使用する** 

API は指定した Canary 名 `MyCanary` のドライランを開始し、ランタイムバージョンを `syn-nodejs-puppeteer-10.0` に更新します。

```
aws synthetics start-canary-dry-run \
    --name MyCanary \
    --runtime-version syn-nodejs-puppeteer-10.0
      
      // Or if you wanted to update other configurations:

aws synthetics start-canary-dry-run \
    --name MyCanary \
    --execution-role-arn arn:aws:iam::123456789012:role/NewRole
```

API は `DryRunConfigOutput` 内で `DryRunId` を返します。

得られた `DryRunId` を指定して `GetCanary` を呼び出し、Canary のドライラン設定と追加フィールド `DryRunConfig` を受け取ります。このフィールドには `LastDryRunExecutionStatus` としてリストされているドライランのステータスが含まれます。

```
aws synthetics get-canary \
    --name MyCanary \
    --dry-run-id XXXX-XXXX-XXXX-XXXX
```

詳細については、得られた `DryRunId` を指定して `GetCanaryRuns` を使用し、該当の実行と追加情報を取得してください。

```
aws synthetics get-canary-runs \
    --name MyCanary \
    --dry-run-id XXXX-XXXX-XXXX-XXXX
```

ドライランが正常に終了したら、得られた ` DryRunId` を指定して `UpdateCanary` を使用し、変更をコミットできます。

```
aws synthetics update-canary \
    --name MyCanary \
    --dry-run-id XXXX-XXXX-XXXX-XXXX
```

何らかの理由で失敗した場合 (GetCanaryRuns の結果に詳細が表示されます)、`GetCanaryRuns` の結果には、デバッグ用のログを含むアーティファクトの場所が出力されます。ログがない場合は、ドライランの作成に失敗しています。` GetCanary` を使用すれば実行を検証できます。

```
aws synthetics get-canary \
    --name MyCanary \
    --dry-run-id XXXX-XXXX-XXXX-XXXX
```

*State*、*StateReason*、*StateReasonCode* にドライランのステータスが表示されます。

 **CloudFormation の使用** 

Synthetics Canary のテンプレートに、ブール値 `true` または `false` を受け取る `DryRunAndUpdate` フィールドを追加します。

値が `true` の場合、更新の際に Canary を自動で更新せずに、まずドライランを実行して変更内容を検証します。ドライランが失敗した場合は Canary は更新されず、対象のデプロイと CloudFormation のデプロイは正当な理由により失敗となります。この問題をデバッグするには、[AWS Synthetics コンソール](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Troubleshoot.html)を使用するか、API を利用している場合は `GetCanaryRuns` API を使用して `ArtifactS3Location` を取得し、`*-log.txt` ファイルをダウンロードして Canary ログから実行エラーを確認します。検証が終わったら CloudFormation テンプレートを修正してもう一度デプロイを試すか、上記の API を使用して検証を行います。

値が `false` の場合、Synthetics はドライランを実行して変更を検証せず、更新内容を直接コミットします。

失敗した Canary のトラブルシューティングについては、「[失敗した Canary のトラブルシューティング](CloudWatch_Synthetics_Canaries_Troubleshoot.md)」を参照してください。

テンプレートの例

```
SyntheticsCanary:
    Type: 'AWS::Synthetics::Canary'
    Properties:
      Name: MyCanary
      RuntimeVersion: syn-nodejs-puppeteer-10.0
      Schedule: {Expression: 'rate(5 minutes)', DurationInSeconds: 3600}
      ...
      DryRunAndUpdate: true
```

## 制限事項
<a name="performing-safe-canary-upgrades-limitations"></a>
+ サポートされるランタイムバージョン – syn-nodejs-puppeteer-10.0 以降、syn-nodejs-playwright-2.0 以降、syn-python-selenium-5.1 以降、および syn-nodejs-3.0 以降
+ 各 Canary で一度に実行できるドライランは 1 つだけです
+ ドライランが失敗した場合、Canary は更新できません
+ ドライランでは **Schedule** フィールドの変更をテストできません

**注記**  
Playwright Canary のコードを変更してドライランを開始し、関連付けられた `DryRunId` を指定せずに Canary を更新する場合は、コードパラメータを明示的に指定する必要があります。