# 创建多重检查蓝图金丝雀 Amazon CloudWatch Synthetics 多重检查蓝图通过提供简单的 JSON 配置，帮助您创建 Synthetics 金丝雀。您可以以基于步骤的顺序方式捆绑最多 10 种不同类型的 HTTP/DNS/SSL/TCP 检查，以此节省成本。每项检查都包含针对检查结果提供基本验证的断言。 多重检查金丝雀专为简单使用案例而设计，这些使用案例仅需基本检查，无需使用无头浏览器。有关更复杂的使用案例，请查看 Amazon CloudWatch Synthetics 提供的其他金丝雀类型。 **Topics** + [先决条件](#CloudWatch_Synthetics_MultiCheck_Prerequisites) + [限制](#CloudWatch_Synthetics_MultiCheck_Limitations) + [打包结构、JSON 架构和配置设置](#CloudWatch_Synthetics_MultiCheck_Packaging) + [在 AWS 管理控制台中创建多重检查金丝雀](#CloudWatch_Synthetics_MultiCheck_Console) + [使用 AWS Synthetics API 创建多重检查金丝雀](#CloudWatch_Synthetics_MultiCheck_API) + [在 CloudFormation 中创建多重检查金丝雀](#CloudWatch_Synthetics_MultiCheck_CloudFormation) + [身份验证配置](#CloudWatch_Synthetics_MultiCheck_Authentication) + [问题排查](#CloudWatch_Synthetics_MultiCheck_Troubleshooting) ## 先决条件 + 必须使用 syn-nodejs-3.0\$1 才能创建多重检查金丝雀 + 使用身份验证和 Secrets Manager 配置时，必须确保金丝雀的 [ExecutionRoleArn](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_CreateCanary.html) 有权访问这些密钥 + 为 Sigv4 使用身份验证时，必须确保金丝雀的 [ExecutionRoleArn](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_CreateCanary.html) 有权访问相关角色 ## 限制 + HTTP 响应大小不能超过 1 MB + 最多定义 10 个变量。 + 使用 JSON RFC 时，Checks JSON 可能提供重复字段，但仅会使用最后一个顺序字段 + 在 AWS 管理控制台中，多重检查金丝雀将默认显示多重检查步骤指标，以便识别每项检查的可用性。删除检查后，此图表可能仍会在可用性图表中显示这些检查，直到指标停止活动至少 3 小时 ## 打包结构、JSON 架构和配置设置 必须将用于金丝雀的 JSON Checks 配置命名为 ` blueprint-config.json`。配置必须遵循[架构](https://github.com/aws-samples/synthetics-canary-local-debugging-sample/tree/main)并按照[为 Node.js 多重检查蓝图编写 JSON 配置](CloudWatch_Synthetics_WritingCanary_Multichecks.md)中的说明进行操作。 将 `blueprint-config.json` 压缩为 ZIP 文件，并在以下任一创建工作流中提供。如果存在 `synthetics.json` 配置，它也会被压缩到同一 ZIP 文件中。以下是名为 `multi-checks.zip` 的 zip 文件示例。 ``` multi-checks.zip ├── blueprint-config.json └── synthetics.json ``` ## 在 AWS 管理控制台中创建多重检查金丝雀 1. 打开 Amazon CloudWatch Synthetics 控制台。 1. 选择 **Create Canary (创建金丝雀)**。 1. 在**使用蓝图**下，选择**多重检查**。 在**配置检查**下，您将看到两个选项卡：**检查**和**金丝雀配置**。 1. 选择运行时版本 **syn-nodejs-3.0** 或更高版本。 1. 按照[为 Node.js 多重检查蓝图编写 JSON 配置](CloudWatch_Synthetics_WritingCanary_Multichecks.md)下的步骤描述要执行的检查。或者，控制台会提供默认 JSON 配置，您可以在此基础上进行构建。 1. 选择 **Create Canary (创建金丝雀)**。 ## 使用 AWS Synthetics API 创建多重检查金丝雀 使用 `CreateCanary` API，并在 `Code` 参数中提供字段/值 `BlueprintTypes="multi-checks"` 而不是 ` Handler`。如果同时指定了 `BlueprintTypes` 和 `Handler`，则会显示 `ValidationException`。提供的运行时版本必须为 `syn-nodejs-3.0` 或更高版本。 ``` aws synthetics create-canary \ --name my-multi-check-canary \ --code ZipFile="ZIP_BLOB",BlueprintTypes="multi-checks" \ --runtime-version syn-nodejs-3.0 \ ... // Or if you wanted to use S3 to provide your code. aws synthetics create-canary \ --name my-multi-check-canary \ --code S3Bucket="my-code-bucket",S3Key="my-zip-code-key",BlueprintTypes="multi-checks" \ ... ``` ## 在 CloudFormation 中创建多重检查金丝雀 在多重检查金丝雀的 CloudFormation 模板中，在 `Code` 参数内，提供字段/值 `BlueprintTypes="multi-checks"` 而不是 ` Handler`。如果同时指定了 `BlueprintTypes` 和 `Handler`，则会显示 `ValidationException`。提供的运行时版本必须为 `syn-nodejs-3.0 or later`。 示例模板： ``` SyntheticsCanary: Type: 'AWS::Synthetics::Canary' Properties: Name: MyCanary RuntimeVersion: syn-nodejs-3.0 Schedule: {Expression: 'rate(5 minutes)', DurationInSeconds: 3600} ... Code: S3Bucket: "my-code-bucket" S3Key: "my-zip-code-key" BlueprintTypes: ["multi-checks"] ... ``` ## 身份验证配置 当金丝雀向经过身份验证的端点发出 HTTP 请求时，您可以将蓝图金丝雀的步骤配置为使用四种身份验证类型之一：基本身份验证、API 密钥、OAuth 客户端凭证和 Sigv4。您无需自己设置请求头，只需在蓝图定义中指定身份验证类型，Synthetics 就会按照指定的身份验证类型，使用提供的身份验证信息填充 HTTP 请求的各个部分。 您可以在蓝图步骤的“身份验证”部分中指定身份验证类型。您可以指定要使用的身份验证方案、所选身份验证方案所需的属性，然后 Synthetics 将使用提供的信息为 HTTP 请求构造身份验证标头。 由于以纯文本形式存储机密（例如密码或 API 密钥）存在安全隐患，因此 Synthetics 支持与 AWS Secrets Manager 集成。如果希望在 Synthetics 蓝图金丝雀中对 HTTP 请求进行身份验证，可以引用存储身份验证信息的密钥，Synthetics 就会检索密钥并将其缓存在金丝雀中。这种方法可以向 Synthetics 提供密钥，同时确保密钥安全存储，无需在蓝图配置中以纯文本形式指定它们。 有关 AWS Secrets Manager 的更多信息，请参阅[什么是 AWS Secrets Manager？](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) ### 基本身份验证 Synthetics 实施 RFC 7617 中定义的基本 HTTP 身份验证方案。具体流程如下： + 蓝图配置中提供了用户名和密码对。 + user-pass 通过连接用户名、冒号（“:”）字符以及密码进行创建。 + user-pass 采用 UTF-8 编码，然后转换为 base64 编码字符串。 + 这个 base64 编码的 user-pass 包含在“Authorization”标头中，格式如下：Authorization: Basic \$1base64-encoded-user-pass\$1 例如，如果用户代理希望发送用户 ID“Aladdin”和密码“open sesame”，则会使用以下标头字段：Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 示例配置： ``` "Authentication": { "type": "BASIC", "username": MY_USERNAME, // Required "password": MY_PASSWORD // Required } ``` ### API 密钥身份验证 您可以提供 API 密钥来验证 HTTP 请求。使用 API 密钥身份验证时，您提供的 API 密钥将放入“x-api-key”HTTP 标头中。如果您有自定义资源在其他标头中查找 API 密钥标头，则可以选择指定其他标头名称，让 Synthetics 将 API 密钥放入其中。 示例配置： ``` "Authentication": { "type": "API_KEY", "apiKey": S0A1M2P3L4E5, // Required "header": X-Specific-Header // Optional, defaults to "X-API-Key" } ``` ### SigV4 身份验证 AWS SigV4（签名版本 4）是将身份验证信息添加到 AWS API 请求的 AWS 签名协议。要发出 SigV4 身份验证的请求，需要指定要向其发出请求的区域和服务，并标识您希望金丝雀在发出此 SigV4 请求时代入的 IAM 角色的 ARN（AWS 资源名称）。Synthetics 将代入 roleArn 中提供的 IAM 角色，并使用该角色对 AWS API 请求进行身份验证。 示例配置： ``` "Authentication": { "type": "SIGV4", "region": us-west-2, // Required "service": s3, // Required "roleArn": arn:AWS:iam:12345678912:role/SampleRole // Required } ``` #### SigV4 注意事项 要使 Synthetics 代入您在 Sigv4 身份验证部分中提供的角色，必须将附加到该角色的信任策略配置为允许金丝雀代入所提供的 roleArn。需要您信任的 AWS 主体是金丝雀通过 AWS STS 代入的角色。它采用 ` aws:sts::{account_running_the_canary}:assumed-role//` arn: 格式。 例如，如果您在账户 0123456789012 中运行了名为 test-canary 的金丝雀，且其所代入的角色名为 canary-assume-role，则信任策略需要包含以下语句，这样金丝雀才能正确代入用于 SigV4 身份验证的 roleArn： ``` { "Effect": "Allow", "Principal": { "AWS": "arn:AWS:sts::123456789012:assumed-role/test-canary/" }, "Action": "sts:AssumeRole" } ``` ### OAuth 客户端凭证 Synthetics 实现了 RFC 6479 第 4.4 节中定义的 OAuth 客户端凭证授权类型。如果您想向使用 OAuth 令牌端点所颁发的持有者令牌进行身份验证的端点发出 HTTP 请求，Synthetics 可以代表您请求并管理该持有者令牌。如果使用 OAuth 方案，Synthetics 会执行以下步骤： + 采用基本身份验证方案，通过 clientId 和 clientSecret 对发往 tokenUrl（颁发持有者令牌的端点）的请求进行身份验证 + 如果提供了可选的 scope、audience 和 resource 参数，它们将包含在令牌请求中 + 使用 tokenUrl 返回的访问令牌对 HTTP 请求进行身份验证 + 安全地存储从 tokenUrl 返回的刷新令牌，用于未来的令牌请求 示例配置： ``` "Authentication": { "type": "OAUTH_CLIENT_CREDENTIALS", "tokenUrl": ..., // Required "clientId": ..., // Required "clientSecret": ..., // Required "scope": ..., // Optional "audience": ..., // Optional "resource": ..., // Optional } ``` #### OAuth 注意事项 当返回 401 或 407 响应时，Synthetics 会刷新 OAuth 令牌。 ### AWS Secrets Manager 集成 为避免以纯文本形式存储密钥值（例如密码或 API 密钥），Synthetics 提供了与 AWS Secrets Manager 的集成。您可以在蓝图配置中引用整个密钥值，格式为 ` ${aws_SECRET:}`，也可以引用特定密钥 ` ${aws_SECRET::}`。 例如，如果密钥名为 login/basic-auth-credentials，则使用以下 JSON 结构存储用户名和密码： ``` { "username": "Aladdin", "password": "open sesame" } ``` 您可以按如下方式在蓝图配置中引用用户名和密码，Synthetics 会检索密钥值并使用其键对请求进行身份验证： ``` "Authentication": { "type": "BASIC", "username": ${AWS_SECRET:login/basic-auth-credentials:username}, "password": ${AWS_SECRET:login/basic-auth-credentials:password} } ``` 为使 Synthetics 能够检索指定的密钥，金丝雀代入的角色 ARN 需要具有 secretsManager:GetSecretValue 权限。如果密钥加密方式使用客户自主管理型密钥，而非 AWS 托管密钥 AWS/secretsmanager，您还需要该密钥的 kms:Decrypt 权限。 示例权限： ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "secretsmanager:GetSecretValue", "Resource": "arn:AWS:secretsmanager:us-east-1:123456789012:secret:secretName-AbCdEf" }, { "Effect": "Allow", "Action": "kms:Decrypt", "Resource": "arn:AWS:kms:us-east-1:123456789012:key/key-id" } ] } ``` ## 问题排查 ### 常见问题排查 多重检查蓝图的底层代码是用 Typescript 编写的。有关常见故障，请参阅金丝雀问题排查页面：[排查失败金丝雀的问题](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Troubleshoot.html)。 ### JSON 检查配置语法错误 当出现任何与金丝雀 JSON 检查配置相关的语法错误时，AWS 管理控制台会在您尝试创建金丝雀时提供失败原因。如果您使用 API 或 CloudFormation 创建金丝雀，则首次执行金丝雀时会失败。建议对多重检查金丝雀使用安全的金丝雀更新工作流。有关更多信息，请参阅[执行安全金丝雀更新](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/performing-safe-canary-upgrades.html)。 ### 网络或超时故障 对于任何与超时、网络连接故障（例如 ENOTFOUND、ECONNRESET）相关的间歇性或持续性故障，请考虑启用 ` DEBUG` 日志，以便后续运行提供有关检查失败原因的更多详细信息。为此，请提供环境变量 CW\$1SYNTHETICS\$1LOG\$1LEVEL: "DEBUG"。 如果仍然存在无法调试的故障，可以考虑联系 AWS Support，或者检查 CloudWatch Synthetics 提供的其他任何金丝雀类型是否更符合使用案例。