# 执行安全金丝雀更新
<a name="performing-safe-canary-upgrades"></a>

CloudWatch Synthetics 安全金丝雀更新功能允许在应用更改之前，在先对现有金丝雀的更新进行测试。此功能可帮助验证金丝雀与新运行时和其他配置更改（例如代码或内存更改）的兼容性。这将有助于最大限度地减少错误更新造成的潜在监控中断。

通过对运行时版本更新、配置更改和代码脚本修改使用金丝雀安全更新，您可以降低风险、保持不间断的监控、在提交和更新之前验证更改并减少停机时间。

**Topics**
+ [先决条件](#performing-safe-canary-upgrades-prereq)
+ [最佳实践](#performing-safe-canary-upgrades-best-practices)
+ [使用试运行测试金丝雀](#performing-safe-canary-upgrades-getting-started)
+ [限制](#performing-safe-canary-upgrades-limitations)

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

确保已满足先决条件。
+ 具有 CloudWatch Synthetics 权限的 AWS 账户
+ 支持的运行时版本上已有金丝雀（有关兼容的运行时，请参阅[限制](#performing-safe-canary-upgrades-limitations)）
+ 执行试运行时包括兼容的运行时（有关兼容的运行时，请参阅[限制](#performing-safe-canary-upgrades-limitations)）

## 最佳实践
<a name="performing-safe-canary-upgrades-best-practices"></a>

下面是在执行金丝雀时可遵循的一些最佳实践。
+ 执行试运行以验证运行时更新
+ 在对金丝雀进行生产环境更新之前执行试运行
+ 试运行后查看金丝雀日志和构件
+ 使用试运行来验证依赖项和库兼容性

## 使用试运行测试金丝雀
<a name="performing-safe-canary-upgrades-getting-started"></a>

您可使用以下选项测试金丝雀更新：

 **使用 AWS 管理控制台的“编辑”工作流程** 

1. 前往 CloudWatch Synthetics 控制台。

1. 选择要更新的金丝雀。

1. 从**操作**下拉列表中选择**编辑**。

   使用要测试的更改来更新金丝雀。例如，更改运行时版本或编辑脚本代码。

1. 在**金丝雀脚本**下选择**开始试运行**，立即测试并查看结果；或在页面底部选择**验证并稍后保存**，开始测试并稍后在**金丝雀详细信息**页面中查看结果。

1. 试运行成功后选择**提交**，完成金丝雀更新的提交。

 **使用 AWS 管理控制台批量更新金丝雀** 

1. 前往 CloudWatch Synthetics 控制台。

1. 选择 **Synthetics** 列表页面。

1. 最多可选择五个要为其更新运行时的金丝雀。

1. 从**操作**下拉列表中选择**更新运行时**。

1. 选择**为新的运行时开始试运行**开始试运行，并在更新之前测试更改。

1. 在 **Synthetics** 列表页面上，您将在金丝雀的**运行时**版本旁边看到一个文本，其中显示了试运行的进度（仅在涉及运行时更新的试运行中才会显示此文本）。

   试运行成功后，即可看到**启动更新**文本。

1. 选择**启动更新**，完成提交运行时更新的提交。

1. 如果试运行失败，则会看到**更新试运行失败**文本。选择文本，即可查看金丝雀详细信息页面的调试链接。

 **使用 AWS CLI 或 SDK** 

API 开始对提供的金丝雀名称 `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`，获取金丝雀的试运行配置以及包含列为 `LastDryRunExecutionStatus` 的试运行状态的附加字段 `DryRunConfig`。

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

成功试运行后，即可将 `UpdateCanary` 与提供的 ` DryRunId` 一起使用来提交更改。

```
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 金丝雀模板中，提供接受布尔值 `true` 或 `false` 的字段 `DryRunAndUpdate`。

当值为 `true` 时，每次更新都会执行试运行来验证更改，然后自动更新金丝雀。如果试运行失败，金丝雀不会更新，而且部署和 CloudFormation 部署会因有效原因失败。要调试此问题，请使用 [AWS Synthetics 控制台](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Troubleshoot.html)；如果使用 API 调试，请使用 `GetCanaryRuns` API 获取 `ArtifactS3Location`，然后下载 `*-log.txt` 文件，查看金丝雀日志执行中是否存在错误。验证后，修改 CloudFormation 模板并重试部署或使用上述 API 进行验证。

当值为 `false` 时，Synthetics 不会执行试运行来验证更改，而是直接提交您的更新。

有关对失败金丝雀进行问题排查的信息，请参阅[排查失败金丝雀的问题](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
+ 每个金丝雀每次只能执行一次试运行
+ 如果试运行失败，则无法更新金丝雀
+ 试运行无法测试任何**计划**字段的更改

**注意**  
如果启动具有 Playwright 金丝雀代码更改的试运行，并且想要在不提供相关 `DryRunId` 的情况下更新金丝雀，必须明确指定代码参数。