创建多重检查蓝图金丝雀

Amazon CloudWatch Synthetics 多重检查蓝图通过提供简单的 JSON 配置，帮助您创建 Synthetics 金丝雀。您可以以基于步骤的顺序方式捆绑最多 10 种不同类型的 HTTP/DNS/SSL/TCP 检查，以此节省成本。每项检查都包含针对检查结果提供基本验证的断言。

多重检查金丝雀专为简单使用案例而设计，这些使用案例仅需基本检查，无需使用无头浏览器。有关更复杂的使用案例，请查看 Amazon CloudWatch Synthetics 提供的其他金丝雀类型。

先决条件

限制

打包结构、JSON 架构和配置设置

必须将用于金丝雀的 JSON Checks 配置命名为 blueprint-config.json。配置必须遵循架构并按照为 Node.js 多重检查蓝图编写 JSON 配置中的说明进行操作。

将 blueprint-config.json 压缩为 ZIP 文件，并在以下任一创建工作流中提供。如果存在 synthetics.json 配置，它也会被压缩到同一 ZIP 文件中。以下是名为 multi-checks.zip 的 zip 文件示例。

multi-checks.zip
├── blueprint-config.json
└── synthetics.json
    

在 AWS 管理控制台中创建多重检查金丝雀

使用 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？

基本身份验证

Synthetics 实施 RFC 7617 中定义的基本 HTTP 身份验证方案。具体流程如下：

例如，如果用户代理希望发送用户 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/<canary_name>/<assumed_role_name>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 会执行以下步骤：

示例配置：

"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:<secret_name>}，也可以引用特定密钥 ${aws_SECRET:<secret_name>:<secret_key>}。

例如，如果密钥名为 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 编写的。有关常见故障，请参阅金丝雀问题排查页面：排查失败金丝雀的问题。

JSON 检查配置语法错误

当出现任何与金丝雀 JSON 检查配置相关的语法错误时，AWS 管理控制台会在您尝试创建金丝雀时提供失败原因。如果您使用 API 或 CloudFormation 创建金丝雀，则首次执行金丝雀时会失败。建议对多重检查金丝雀使用安全的金丝雀更新工作流。有关更多信息，请参阅执行安全金丝雀更新。

网络或超时故障

对于任何与超时、网络连接故障（例如 ENOTFOUND、ECONNRESET）相关的间歇性或持续性故障，请考虑启用 DEBUG 日志，以便后续运行提供有关检查失败原因的更多详细信息。为此，请提供环境变量 CW_SYNTHETICS_LOG_LEVEL: "DEBUG"。

如果仍然存在无法调试的故障，可以考虑联系 AWS Support，或者检查 CloudWatch Synthetics 提供的其他任何金丝雀类型是否更符合使用案例。