# Canary 設計図の使用
このセクションでは、Canary の各設計図と、各設計図に最も適合するタスクについて詳しく説明します。設計図は、以下の Canary タイプのために提供されています:
**Topics**
+ [
## ハートビートのモニターリング
](#CloudWatch_Synthetics_Canaries_Blueprints_Heartbeat)
+ [
## API Canary
](#CloudWatch_Synthetics_Canaries_Blueprints_API)
+ [
## リンク切れチェッカー
](#CloudWatch_Synthetics_Canaries_Blueprints_Broken_Links)
+ [
## ビジュアルモニターリングの設計図
](#CloudWatch_Synthetics_Canaries_Blueprints_VisualTesting)
+ [
## Canary Recorder
](#CloudWatch_Synthetics_Canaries_Blueprints_Recorder)
+ [
## GUI ワークフロービルダー
](#CloudWatch_Synthetics_Canaries_Blueprints_GUI_Workflow)
+ [
## マルチチェックのブループリント
](#CloudWatch_Synthetics_Canaries_Blueprints_Multichecks_Blueprint)
+ [
# マルチチェックブループリント Canary の作成
](CloudWatch_Synthetics_Canaries_MultiCheck_Blueprint.md)
設計図を使用して Canary を作成する場合、CloudWatch コンソールの各フィールドに入力するに従って、作成中の Canary がページの [**スクリプトエディタ**] 領域に Node.js スクリプトとして表示されます。この領域で Canary を編集し、さらにカスタマイズすることもできます。
## ハートビートのモニターリング
ハートビートスクリプトは、指定した URL をロードし、ページのスクリーンショットと HTTP アーカイブファイル (HAR ファイル) を保存します。また、アクセスした URL のログも保存します。
HAR ファイルを使用して、ウェブページに関する詳細なパフォーマンスデータを表示できます。ウェブリクエストのリストを分析し、項目の読み込み時間などのパフォーマンス問題を検出できます。
Canary が `syn-nodejs-puppeteer-3.1` 以降のランタイムバージョンを使用している場合、ハートビートモニターリングブループリントを使用して複数の URL をモニターリングし、Canary 実行レポートのステップの概要で各 URL のステータス、期間、関連付けられたスクリーンショット、失敗の理由を確認できます。
## API Canary
API Canary は、REST API の基本的な読み取り関数と書き込み関数をテストできます。RESTは *Representational State Transfer* の略であり、開発者が API を作成するときに従う一連のルールです。これらのルールの 1 つでは、特定の URL へのリンクがデータを返す必要があることを指定しています。
Canary は任意の API で動作し、すべてのタイプの機能をテストできます。各 Canary は複数の API 呼び出しを行うことができます。
ランタイムバージョン `syn-nodejs-2.2` 以降を使用する Canary では、API Canary ブループリントは、API を HTTP ステップとしてモニターリングする複数ステップの Canary をサポートします。1 つの Canary で複数の API をテストできます。各ステップは、異なる URL にアクセスしたり、異なるヘッダーを使用したり、ヘッダーとレスポンス本文を取得するかどうかについて異なるルールを使用したりできる個別のリクエストです。ヘッダーとレスポンス本文を取得しないことで、機密データが記録されないようにできます。
API Canary 内の各リクエストは、次の情報で構成されます。
+ *エンドポイント*。リクエストする URL です。
+ *メソッド*。サーバーに送信されるリクエストのタイプです。REST API は、GET (読み取り)、POST (書き込み)、PUT (更新)、PATCH (更新)、DELETE (削除) の各オペレーションをサポートしています。
+ *ヘッダー*。クライアントとサーバーの両方に情報を提供します。これらは認証に使用され、本文の内容に関する情報を提供します。有効なヘッダーのリストについては、「[HTTPヘッダー](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)」をご参照ください。
+ *データ* (または*本文*)。サーバーに送信される情報を含みます。これは、POST、PUT、PATCH、または DELETE の各リクエストでのみ使用されます。
**注記**
API Canary ブループリントは、Playwright ランタイムではサポートされていません。
API Canary ブループリントは、GET メソッドと POST メソッドをサポートしています。この設計図を使用する場合は、ヘッダーを指定する必要があります。例えば、**Authorization** を **[キー]** として指定し、必要な認可データを **[値]** として指定できます。
POST リクエストをテストする場合は、**[データ]** フィールドに書き込むコンテンツも指定します。
**API Gateway との統合**
API ブループリントは Amazon API Gateway と統合されています。これにより、API Gateway API やステージを Canary と同じ AWS アカウントやリージョンから選択したり、API Gateway から Swagger テンプレートをアップロードして、クロスアカウントとクロスリージョン API のモニターリングを行ったりすることができます。その後、最初から入力するのではなく、コンソールで残りの詳細を選択して Canary を作成できます。API Gateway の詳細については、「[Amazon API Gateway とは](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html)」を参照してください。
**プライベート API の使用**
Amazon API Gateway でプライベート API を使用する Canary を作成できます。詳細については、「[Amazon API Gateway でのプライベート API の作成](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html)」を参照してください。
## リンク切れチェッカー
リンク切れチェッカーは、`document.getElementsByTagName('a')` を使用して、テスト対象である URL 内のすべてのリンクを収集します。この際、ユーザーが指定したリンク数までがテストされ、また、URL 自体も最初のリンクとしてカウントされます。例えば、5 つのリンクが含まれているページのすべてのリンクをチェックする場合は、Canary が 6 つのリンクをたどるように指定する必要があります。
`syn-nodejs-2.0-beta` ランタイム以降を使用して作成されたリンク切れチェッカー Canary は、次の追加機能をサポートしています。
+ チェックされたリンク、ステータスコード、エラーの理由 (存在する場合)、およびソースページとターゲットページのスクリーンショットを含むレポートを生成する。
+ Canary の結果を表示するとき、フィルタリングしてリンク切れのみを表示し、エラーの理由に基づいてリンクを修正できます。
+ このバージョンでは、各リンクの注釈付きソースページのスクリーンショットがキャプチャされ、リンクが見つかったアンカーが強調表示されます。非表示のコンポーネントには注釈が付けられません。
+ キャプチャするスクリーンショットは、ソースおよびターゲットページの両方、ソースページのみ、またはターゲットページのみに設定できます。
+ 最初のページから多くのリンクがスクレイプされた場合でも最初のリンク切れの後に Canary スクリプトが停止するという、以前のバージョンの問題は、このバージョンで修正されています。
**注記**
壊れたリンクチェッカーのブループリントは、Playwright ランタイムではサポートされていません。
新しいランタイムを導入するために、`syn-1.0` を使用している既存の Canary を更新する場合は、一度 Canary を削除した上で再作成する必要があります。既存の Canary を新しいランタイムに更新しても、これらの機能は利用可能になりません。
リンク切れチェッカー Canary は、次の種類のリンクエラーを検出します。
+ 404 ページが見つからない。
+ ホスト名が無効である。
+ URL が正しくない。この例としては、URL から角括弧が抜けている、スラッシュが余分についている、プロトコルが間違っているなどが挙げられます。
+ HTTP レスポンスコードが無効である。
+ ホストサーバーが、コンテンツもなく、レスポンスコードもない、空のレスポンスを返す。
+ HTTPリクエストが Canary の実行中に常にタイムアウトする。
+ ホストが正しく設定されていないか、ビジーすぎるために接続が常に切断される。
## ビジュアルモニターリングの設計図
ビジュアルモニターリングの設計図には、Canary 実行中に撮影されたスクリーンショットと、ベースライン Canary 実行中に撮影されたスクリーンショットを比較するコードが含まれています。2 つのスクリーンショット間の不一致がしきい値のパーセンテージを超えている場合、Canary は失敗します。ビジュアルモニターリングは、**syn-puppeteer-node-3.2** 以降で実行中の Canary でサポートされています。Python と Selenium を実行している Canary、または Playwright ランタイムを使用している Canary では現在サポートされていません。
ビジュアルモニターリングのブループリントには、デフォルトの Canary ブループリントスクリプトに次のコード行が含まれており、ビジュアルモニターリングが有効になります。
```
syntheticsConfiguration.withVisualCompareWithBaseRun(true);
```
この行がスクリプトに追加された後に初めて Canary が正常に実行されると、その実行中に撮影されたスクリーンショットが比較のベースラインとして使用されます。最初に Canary を実行した後、CloudWatch コンソールを使用して Canary を編集して、次のいずれかの操作を行うことができます。
+ Canary の次の実行を新しいベースラインとして設定する。
+ 現在のベースラインスクリーンショットに境界を描画し、ビジュアル比較時に無視するスクリーンショットの領域を指定する。
+ スクリーンショットをビジュアルモニターリングに使用しないようにする。
CloudWatch コンソールを使用して Canary を編集する方法の詳細については、 「[Canary を編集または削除する](synthetics_canaries_deletion.md)」を参照してください。
また、` nextrun` または `lastrun` パラメーターを指定するか、Canary 実行 ID を [UpdateCanary](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_UpdateCanary.html) API で指定することにより、ベースラインとして使用される Canary 実行を変更することもできます。
ビジュアルモニターリングの設計図を使用する場合は、スクリーンショットを撮影する URL を入力し、差分しきい値をパーセンテージで指定します。ベースライン実行後、そのしきい値よりも大きい視覚差を検出する Canary を今後実行すると、Canary 障害がトリガーされます。ベースライン実行後、Canary を編集して、ビジュアルモニターリング中に無視するベースラインスクリーンショットに境界線を「描画」することもできます。
ビジュアルモニターリング機能は、ImageMagick オープンソースソフトウェアツールキットによって機能します。詳細については、「[ImageMagick](https://imagemagick.org/index.php)」を参照してください。
## Canary Recorder
Canary レコーダーの設計図を使用すると、CloudWatch Synthetics Recorder を使用してウェブサイトでクリックおよび入力のアクションを記録し、同じステップに従う Canary を作成するために使用できる Node.js スクリプトを自動的に生成できます。CloudWatch Synthetics Recorder は、Amazon が提供する Google Chrome 拡張機能です。Canary レコーダーは、Playwright ランタイムを使用する Canary ではサポートされていません。
**クレジット**: CloudWatch Synthetics Recorder は、[Headless レコーダー](https://github.com/checkly/headless-recorder)に基づいています。
詳細については、「[Google Chrome の CloudWatch Synthetics Recorder を使用する](CloudWatch_Synthetics_Canaries_Recorder.md)」を参照してください。
## GUI ワークフロービルダー
GUI ワークフロービルダー設計図は、ウェブページに対してアクションを実行できることを検証します。例えば、ウェブページにログインフォームがある場合、Canary はユーザーフィールドとパスワードフィールドに入力し、このフォームを送信してウェブページが正しく動作していることを検証できます。
このタイプの Canary を設計図を従って作成する場合は、Canary がウェブページに対して実行するアクションを指定します。使用できるアクションは次のとおりです。
+ **クリック** – 指定した要素を選択し、ユーザーによる要素のクリックまたは選択をシミュレートします。
Node.js スクリプトで要素を指定するには、`[id=]` または ` a[class=]` を使用します。
Python スクリプトで要素を指定するには、`xpath //*[@id=]` または ` //*[@class=]` を使用します。
+ **セレクタの検証** – 指定した要素がウェブページに存在することを検証します。このテストは、以前のアクションによって正しい要素がページに入力されていることを検証するのに役立ちます。
Node.js スクリプトで検証する要素を指定するには、`[id=]` または ` a[class=]` を使用します。
Python スクリプトで検証する要素を指定するには、`xpath //*[@id=]` または `//*[class=]` を使用します。
+ **テキストの検証** – 指定した文字列がターゲット要素内に含まれていることを検証します。このテストは、事前のアクションが正しいテキストを表示したかどうかを確認するのに役立ちます。
このアクションでは Puppeteer の ` div[@id=]//h1` 関数を使用するため、Node.js スクリプト内の要素を指定するには `waitForXPath` などの形式を使用します。
Python スクリプトで要素を指定するには、このアクションは Selenium で ` //*[@id=] ` 関数を使用するため、`implicitly_wait` または //\$1[@class=] などの xpath 形式を使用します。
+ **テキストの入力** – 指定したテキストをターゲット要素に書き込みます。
Node.js スクリプトで検証する要素を指定するには、`[id=]` または ` a[class=]` を使用します。
Python スクリプトで検証する要素を指定するには、`xpath //*[@id=]` または `//*[@class=]` を使用します。
+ **クリックして移動** – 指定した要素を選択した後で、ページ全体が読み込まれるまで待ちます。これは、ページを再度読み込む必要がある場合に最も役立ちます。
Node.js スクリプトで要素を指定するには、`[id=]` または ` a[class=]` を使用します。
Python スクリプトで要素を指定するには、`xpath //*[@id=]` または ` //*[@class=]` を使用します。
例えば、次のブループリントでは Node.js を使用しています。このスクリプトは指定した URL の **[firstButton]** をクリックし、想定したセレクタで想定されたテキストが表示されることを検証します。さらに、名前 `Test_Customer` を **[名前]** フィールドに入力して **[ログイン]** ボタンをクリックし、次のページに **[ようこそ]** テキストが表示されることを確認し、そのログインが成功したことを検証します。
![\[コンソールの Canary の作成ページ。GUI ワークフロー設計図のフィールドが入力されています。\]](http://docs.aws.amazon.com/ja_jp/AmazonCloudWatch/latest/monitoring/images/canary_create_gui_workflow.PNG)
次のランタイムを使用する GUI ワークフロー Canary は、各 Canary 実行に対して実行されたステップの概要も提供します。各ステップに関連付けられたスクリーンショットおよびエラーメッセージを使用して、エラーの根本原因を見つけることができます。
+ `syn-nodejs-2.0` 以降
+ `syn-python-selenium-1.0` 以降
## マルチチェックのブループリント
マルチチェックブループリントで、Canary の作成が簡単になります。HTTP、DNS、SSL、TCP チェックを実行する、すぐに使用できる機能を提供するシンプルな JSON 設定を使用することで、コストを削減できます。最大 10 個のチェックを設定できます。各チェックを順番に実行される数値ステップとして設定し、Canary フローを明確に理解できるようにします。
マルチチェックブループリントは以下をサポートします。
+ 基本的な HTTP リクエスト、TCP リクエスト、DNS レコードの検証、SSL 証明書のモニタリング
+ Secrets Manager と統合された Basic、API Key、OAuth、Sigv4 などの HTTP 認証方法
+ 各チェックのアサーション
詳細については、「[Canary を作成する](CloudWatch_Synthetics_Canaries_Create.md)」を参照してください。
# マルチチェックブループリント 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 タイプの方がユースケースにより適合するかどうかを確認することを検討してください。