本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

CloudWatch 合成安全 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>

確定滿足必要條件。
+ AWS 具有 CloudWatch 合成許可的帳戶
+ 支援的執行時期版本上的現有 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 合成主控台。

1. 選取要更新的 Canary。

1. 從**動作**下拉式清單中，選擇**編輯**。

   使用要測試的變更來更新 Canary。例如，變更執行時期版本或編輯指令碼的程式碼。

1. 在 **Canary 指令碼**下，選擇**啟動模擬執行**以立即測試和檢視結果，或選擇頁面底部的**稍後驗證並儲存**以開始測試，並稍後前往 **Canary 詳細資訊**頁面檢視結果。

1. 模擬執行成功後，選擇**提交**以遞交 Canary 更新。

 **使用 AWS 管理主控台 更新批次中的 Canary** 

1. 前往 CloudWatch 合成主控台。

1. 選擇 **Synthetics** 清單頁面。

1. 選取最多五個您要更新執行時期的 Canary。

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 會在 `DryRunId`內傳回 `DryRunConfigOutput` 。

使用所提供的 `DryRunId` 呼叫 `GetCanary`，可接收 Canary 的模擬執行組態，以及包含列為 `DryRunConfig` 之模擬執行狀態的額外欄位 `LastDryRunExecutionStatus`。

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

如需詳細資訊，請使用 `GetCanaryRuns` 搭配提供的 `DryRunId` 來擷取執行和其他資訊。

```
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
```

*狀態*、*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` 時，合成不會執行模擬執行以驗證變更，而是直接遞交您的更新。

如需排解 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\$1、syn-nodejs-playwright-2.0\$1、syn-python-selenium-5.1\$1 和 syn-nodejs-3.0\$1
+ 每個 Canary 一次只能執行一個模擬執行
+ 當模擬執行失敗時，您無法更新 Canary
+ 模擬執行無法測試任何**排程**欄位變更

**注意**  
當您使用 Playwright Canary 的程式碼變更啟動模擬執行，並且想要更新 Canary 而不提供相關聯的 `DryRunId` 時，必須明確指定程式碼參數。