# マルチチェックブループリント Canary の作成
Amazon CloudWatch Synthetics マルチチェックブループリントは、シンプルな JSON 設定を提供することで Synthetics Canary を作成するのに役立ちます。ステップベースのシーケンシャル方式で最大 10 種類の HTTP/DNS/SSL/TCP チェックをバンドルすることで、コストを削減できます。各チェックには、チェック結果に対する基本的な検証を提供するアサーションが含まれます。
マルチチェック Canary は、ヘッドレスブラウザを使用しない基本チェックのみを必要とするシンプルなユースケース向けに設計されています。より複雑なユースケースについては、Amazon CloudWatch Synthetics が提供する他の Canary タイプを確認してください。
**Topics**
+ [前提条件](#CloudWatch_Synthetics_MultiCheck_Prerequisites)
+ [制限事項](#CloudWatch_Synthetics_MultiCheck_Limitations)
+ [パッケージ構造、JSON スキーマ、および設定](#CloudWatch_Synthetics_MultiCheck_Packaging)
+ [AWS マネジメントコンソール でのマルチチェック Canary の作成](#CloudWatch_Synthetics_MultiCheck_Console)
+ [AWS Synthetics API を使用したマルチチェック Canary の作成](#CloudWatch_Synthetics_MultiCheck_API)
+ [CloudFormation でのマルチチェック Canary の作成](#CloudWatch_Synthetics_MultiCheck_CloudFormation)
+ [認証の設定](#CloudWatch_Synthetics_MultiCheck_Authentication)
+ [トラブルシューティング](#CloudWatch_Synthetics_MultiCheck_Troubleshooting)
## 前提条件
+ マルチチェック Canary を作成するには、syn-nodejs-3.0\$1 を使用している必要があります。
+ Authentication and Secrets Manager 設定を使用する場合は、Canary [ExecutionRoleArn](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_CreateCanary.html) がこれらのシークレットへのアクセスを許可していることが必要です
+ Authentication for Sigv4 を使用する場合は、Canary [ExecutionRoleArn](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_CreateCanary.html) が関連するロールへのアクセスを許可していることが必要です
## 制限事項
+ HTTP レスポンスサイズは 1 MB 以下
+ 定義済み変数は最大 10 個。
+ JSON RFC を使用する場合、Checks JSON には重複するフィールドが指定されている場合がありますが、最後のシーケンシャルフィールドのみが使用されます。
+ AWS マネジメントコンソール では、マルチチェック Canary はデフォルトでマルチチェックステップメトリクスを表示して、各チェックが使用できるかどうかすぐに識別できるようにします。チェックが削除されても、メトリクスが少なくとも 3 時間アクティブでなくなるまで、このグラフの可用性グラフにチェックが表示されることがあります。
## パッケージ構造、JSON スキーマ、および設定
Canary に使用される 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 マネジメントコンソール でのマルチチェック Canary の作成
1. Amazon CloudWatch Synthetics コンソールを開きます。
1. **[Canary を作成]** を選択します。
1. **[設計図を使用する]** で、**[マルチチェック]** を選択します。
**[チェックを設定]** に、**[チェック]** と **[Canary 設定]** の 2 つのタブが表示されます。
1. ランタイムバージョン **syn-nodejs-3.0** 以降を選択します。
1. [Node.js マルチチェックブループリントの JSON 設定の記述](CloudWatch_Synthetics_WritingCanary_Multichecks.md) にある手順に従って、実行するチェックを記述します。または、コンソールにデフォルトの JSON 設定が用意されているため、これに基づいて構築することもできます。
1. **[Canary を作成]** を選択します。
## AWS Synthetics API を使用したマルチチェック Canary の作成
`Code` パラメータ内で `CreateCanary` API を使用し、` Handler` ではなくフィールド/値として `BlueprintTypes="multi-checks"` を指定します。`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 でのマルチチェック Canary の作成
マルチチェック Canary の CloudFormation テンプレートの `Code` パラメータ内で、` Handler` ではなくフィールド/値として `BlueprintTypes="multi-checks"` を指定します。`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"]
...
```
## 認証の設定
認証されたエンドポイントに Canary が HTTP リクエストを行う場合、Basic、API キー、OAuth クライアント認証情報、SigV4 の 4 つの認証タイプのいずれかを使用するようにブループリント Canary の手順を設定できます。リクエストヘッダーを自分で設定するのではなく、ブループリント定義で認証タイプを指定できます。そうすると、Synthetics は指定された認証タイプに従って、HTTP リクエストのコンポーネントに提供された認証情報を入力します。
ブループリントステップの認証セクションで認証タイプを指定します。使用する認証スキーム、選択した認証スキームに必要なプロパティを指定します。そうすると、Synthetics は提供された情報を使用して HTTP リクエストの認証ヘッダーを作成します。
シークレット (パスワードや API キーなど) をプレーンテキストで保存するとセキュリティ上の懸念があるため、Synthetics は AWS Secrets Manager との統合をサポートしています。Synthetics ブループリント Canary で HTTP リクエストを認証する場合は、認証情報を保存するシークレットを参照すると、Synthetics はシークレットの取得と Canary でのキャッシュを処理します。このアプローチによって、ブループリント設定でシークレットをプレーンテキストで指定することなく、シークレットを安全に保存しながら Synthetics にシークレットが提供されます。
AWS Secrets Manager の詳細については、「[AWS Secrets Manager とは](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)」を参照してください。
### 基本認証
Synthetics は、RFC 7617 で定義された Basic HTTP 認証スキームを実装します。このプロセスは次のように機能します。
+ ユーザー名とパスワードのペアは、ブループリント設定から提供されます。
+ ユーザーパスは、ユーザー名、単一コロン (":") 文字、パスワードを連結することによって作成されます。
+ ユーザーパスは UTF-8 でエンコードされ、base64 でエンコードされた文字列に変換されます。
+ この base64 でエンコードされたユーザーパスは、「Authorization」ヘッダーで次の形式で提供されます: Authorization: Basic \$1base64-encoded-user-pass\$1
例えば、ユーザーエージェントが user-id「Aladdin」とパスワード「open sesame」を送信する場合、次のヘッダーフィールドを使用します: Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
設定例:
```
"Authentication": {
"type": "BASIC",
"username": MY_USERNAME, // Required
"password": MY_PASSWORD // Required
}
```
### API キー認証
HTTP リクエストを認証するための API キーを指定できます。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 (Signature Version 4) は、AWS API リクエストに認証情報を追加するための AWS 署名プロトコルです。SigV4 で認証されたリクエストを行うには、リクエスト先のリージョンとサービス、および Canary が引き受ける IAM ロールを識別する ARN (AWS リソースネーム) を、この SigV4 リクエストを行うときに指定する必要があります。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 を Canary が引き受けられるようにする必要があります。信頼する必要がある AWS プリンシパルは、Canary が AWS STS を通じて引き受けたロールです。` aws:sts::{account_running_the_canary}:assumed-role//` arn: の形式を取ります。
例えば、アカウント 0123456789012 で test-canary という名前の Canary が実行されていて、引き受けたロールが canary-assume-role という名前だった場合、Canary が 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 で Basic 認証スキームを使用して、ベアラートークンを発行するエンドポイントである tokenUrl へのリクエストを認証する
+ オプションのスコープ、対象者、リソースパラメータを指定すると、トークンリクエストに含まれます。
+ tokenUrl が返したアクセストークンを使用して HTTP リクエストを認証する
+ 将来のトークンリクエストのために tokenUrl から返された更新トークンを安全に保存する
設定例:
```
"Authentication": {
"type": "OAUTH_CLIENT_CREDENTIALS",
"tokenUrl": ..., // Required
"clientId": ..., // Required
"clientSecret": ..., // Required
"scope": ..., // Optional
"audience": ..., // Optional
"resource": ..., // Optional
}
```
#### OAuth に関する考慮事項
Synthetics は、401 または 407 の応答が返されたときに 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 が指定されたシークレットを取得できるようにするには、Canary が引き受けるロール 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 で記述されます。一般的な障害については、Canary のトラブルシューティングページ「[Canary の障害のトラブルシューティング](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Troubleshoot.html)」を参照してください。
### JSON チェック設定構文エラー
Canary の JSON チェック設定に関連する構文エラーがある場合、AWS マネジメントコンソール では Canary を作成しようとするときに失敗の理由が表示されます。API または CloudFormation を使用して Canary を作成する場合、Canary が初めて実行されると失敗が表示されます。マルチチェック Canary には、安全な Canary 更新ワークフローを使用することをお勧めします。詳細については、「[安全な Canary 更新の実行](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/performing-safe-canary-upgrades.html)」を参照してください。
### ネットワークまたはタイムアウトの障害
タイムアウトに関連する断続的または一貫した障害やネットワーク接続の障害 (ENOTFOUND、ECONNRESET など) では、次の実行でチェックが失敗する理由の詳細が表示されるように ` DEBUG` ログをオンにすることを検討してください。そのためには、環境変数 CW\$1SYNTHETICS\$1LOG\$1LEVEL: "DEBUG" を指定します。
それでもデバッグできない障害が発生した場合は、AWS サポートに問い合わせるか、CloudWatch Synthetics から提供されている他のいずれかの Canary タイプの方がユースケースにより適合するかどうかを確認することを検討してください。