マルチチェックブループリント Canary の作成

Amazon CloudWatch Synthetics マルチチェックブループリントは、シンプルな JSON 設定を提供することで Synthetics Canary を作成するのに役立ちます。ステップベースのシーケンシャル方式で最大 10 種類の HTTP/DNS/SSL/TCP チェックをバンドルすることで、コストを削減できます。各チェックには、チェック結果に対する基本的な検証を提供するアサーションが含まれます。

マルチチェック Canary は、ヘッドレスブラウザを使用しない基本チェックのみを必要とするシンプルなユースケース向けに設計されています。より複雑なユースケースについては、Amazon CloudWatch Synthetics が提供する他の Canary タイプを確認してください。

前提条件

制限事項

パッケージ構造、JSON スキーマ、および設定

Canary に使用される 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 マネジメントコンソール でのマルチチェック Canary の作成

AWS Synthetics API を使用したマルチチェック Canary の作成

Code パラメータ内で CreateCanary API を使用し、Handler ではなくフィールド/値として BlueprintTypes="multi-checks" を指定します。BlueprintTypes と Handler の両方を指定すると、ValidationException が表示されます。提供されるランタイムバージョンは syn-nodejs-3.0 or later である必要があります。

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 とは」を参照してください。

基本認証

Synthetics は、RFC 7617 で定義された Basic HTTP 認証スキームを実装します。このプロセスは次のように機能します。

例えば、ユーザーエージェントが 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/<canary_name>/<assumed_role_name>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 は次の手順を実行します。

設定例:

"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:<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 が指定されたシークレットを取得できるようにするには、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 の障害のトラブルシューティング」を参照してください。

JSON チェック設定構文エラー

Canary の JSON チェック設定に関連する構文エラーがある場合、AWS マネジメントコンソール では Canary を作成しようとするときに失敗の理由が表示されます。API または CloudFormation を使用して Canary を作成する場合、Canary が初めて実行されると失敗が表示されます。マルチチェック Canary には、安全な Canary 更新ワークフローを使用することをお勧めします。詳細については、「安全な Canary 更新の実行」を参照してください。

ネットワークまたはタイムアウトの障害

タイムアウトに関連する断続的または一貫した障害やネットワーク接続の障害 (ENOTFOUND、ECONNRESET など) では、次の実行でチェックが失敗する理由の詳細が表示されるように DEBUG ログをオンにすることを検討してください。そのためには、環境変数 CW_SYNTHETICS_LOG_LEVEL: "DEBUG" を指定します。

それでもデバッグできない障害が発生した場合は、AWS サポートに問い合わせるか、CloudWatch Synthetics から提供されている他のいずれかの Canary タイプの方がユースケースにより適合するかどうかを確認することを検討してください。