Canary の一般的な機能

次の機能はすべての Canary ランタイムで使用できます。

環境変数

Canary を作成する際に環境変数を使用できます。単一の Canary スクリプトを記述し、そのスクリプトをさまざまな値とともに使用すれば、1 つの同様のタスクに対して複数の Canary をすばやく作成できます。

たとえば、さまざまなソフトウェア開発ステージに prod、dev、pre-release などのエンドポイントがあるとします。各エンドポイントをテストするには、Canary を作成する必要があります。ソフトウェアをテストする単一の Canary スクリプトを記述できます。次に、3 つの Canary のそれぞれを作成するときに、異なるエンドポイント環境変数値を指定します。Canary を作成するときに、そのスクリプトと環境変数値を指定します。

環境変数の名前には、文字、数字、およびアンダースコアを使用できます。文字で始まり、少なくとも 2 文字である必要があります。環境変数の合計サイズは 4 KB を超えることはできません。Lambda の予約済み環境変数を環境変数の名前として指定することはできません。予約済み環境変数の詳細については、「ランタイム環境変数」をご参照ください。

次のスクリプト例では、2 つの環境変数を使用しています。このスクリプトは、ウェブページが利用可能かどうかをチェックする Canary 用です。環境変数を使用して、チェックする URL と、使用する CloudWatch Synthetics ログレベルの両方をパラメータ化します。

次のスニペットは、以下に示す完全なスクリプトの一部です。

次の関数は、LogLevel を LOG_LEVEL 環境変数の値に設定します。

 synthetics.setLogLevel(process.env.LOG_LEVEL);

この関数は、URL を URL 環境変数の値に設定します。

const URL = process.env.URL;

次の完全なスクリプトは、両方の環境変数を示しています。このスクリプトを使用して Canary を作成するときは、LOG_LEVEL および URL 環境変数の値を指定します。

var synthetics = require('@aws/synthetics-puppeteer');
const log = require('@aws/synthetics-logger');

const pageLoadEnvironmentVariable = async function () {

  // Setting the log level (0-3)
  synthetics.setLogLevel(process.env.LOG_LEVEL);
  // INSERT URL here
  const URL = process.env.URL;

  let page = await synthetics.getPage();
  //You can customize the wait condition here. For instance,
  //using 'networkidle2' may be less restrictive.
  const response = await page.goto(URL, {waitUntil: 'domcontentloaded', timeout: 30000});
  if (!response) {
      throw "Failed to load page!";
  }
  //Wait for page to render.
  //Increase or decrease wait time based on endpoint being monitored.
  await page.waitFor(15000);
  await synthetics.takeScreenshot('loaded', 'loaded');
  let pageTitle = await page.title();
  log.info('Page title: ' + pageTitle);
  log.debug('Environment variable:' + process.env.URL);

  //If the response status code is not a 2xx success code
  if (response.status() < 200 || response.status() > 299) {
      throw "Failed to load page!";
  }
};

exports.handler = async () => {
  return await pageLoadEnvironmentVariable();
};

環境変数をスクリプトに渡す

コンソールで Canary を作成するときに環境変数をスクリプトに渡すには、コンソールの [Environment variables] (環境変数) セクションで環境変数のキーと値を指定します。詳細については、「Canary を作成する」を参照してください。

API または AWS CLI を介して環境変数を渡すには、RunConfig セクションの EnvironmentVariables パラメータを使用します。以下は、キー Environment とキー Region を持つ 2 つの環境変数を使用する Canary を作成する AWS CLI コマンドの例です。

aws synthetics create-canary --cli-input-json '{
 "Name":"nameofCanary",
 "ExecutionRoleArn":"roleArn",
 "ArtifactS3Location":"s3://amzn-s3-demo-bucket-123456789012-us-west-2",
 "Schedule":{
    "Expression":"rate(0 minute)",
    "DurationInSeconds":604800
 },
 "Code":{
    "S3Bucket": "canarycreation",
    "S3Key": "cwsyn-mycanaryheartbeat-12345678-d1bd-1234-abcd-123456789012-12345678-6a1f-47c3-b291-123456789012.zip",
    "Handler":"pageLoadBlueprint.handler"
 },
 "RunConfig": {
    "TimeoutInSeconds":60,
    "EnvironmentVariables": {
       "Environment":"Production",
       "Region": "us-west-1"
    }
 },
 "SuccessRetentionPeriodInDays":13,
 "FailureRetentionPeriodInDays":13,
 "RuntimeVersion":"syn-nodejs-2.0"
}'

カスタマーマネージド型キーを使用した環境変数の保存時の暗号化

デフォルトでは、AWS 所有キーにより保存中の Canary 環境変数が暗号化されます。カスタマーマネージド AWS KMS キーを指定して、保存中の Canary 環境変数を暗号化できます。カスタマーマネージドキーを使用すると、機密設定データの暗号化を完全に制御できます。以下のセクションでは、カスタマーマネージドキーを使用するための要件、設定ステップ、およびアクセス許可について説明します。

要件

カスタマーマネージドキーを設定する前に、次の要件を満たしているか確認してください。

カスタマーマネージドキーの設定

Canary の作成時や更新時にカスタマーマネージドキーを設定できます。次の手順は、Amazon CloudWatch コンソールと Synthetics API を使用して暗号化を設定する方法を示しています。

コンソールで暗号化を設定する

Amazon CloudWatch コンソールで Canary の作成や編集を行うには、[環境変数] セクションを展開します。[保存時暗号化の設定] で、[カスタマーマネージドキーの使用] を選択し、AWS KMS キーの ARN を選択または指定します。

API を使用して暗号化を設定する

CreateCanary または UpdateCanary を呼び出すときに、カスタマーマネージドキーの ARN を使用して KmsKeyArn パラメータを指定します。AWS マネージドキーに戻すには、KmsKeyArn に空の文字列を設定します。

例: カスタマーマネージドキーを使用した CreateCanary リクエスト

{
"Name": "my-canary-EXAMPLE",
"KmsKeyArn": "arn:aws:kms:us-east-1:111122223333:key/a1b2c3d4-e5f6-7890-abcd-EXAMPLE11111",
"RunConfig": {
  "EnvironmentVariables": {
    "SECRET_KEY": "my-secret-value-EXAMPLE"
  }
}
}

保存時暗号化に必要なアクセス許可

Canary の作成時や更新時には、AWS KMS キーに対する次のアクセス許可が必要です。

Canary 実行ロールには、保存時暗号化のための AWS KMS アクセス許可は不要です。Lambda はその権限を使用して暗号化と復号を処理します。

マルチロケーション Canary

マルチロケーション Canary の場合、各レプリカロケーションに固有の AWS KMS キーを設けることができます。Canary の作成時や更新時に AddReplicaLocations パラメータで KmsKeyArn を指定します。このキーは、レプリカと同一のリージョン内に存在する必要があります。

転送中の環境変数の暗号化

保存時の暗号化に加えて、個々の環境変数値を CloudWatch Synthetics により保存される前に暗号化することができます。CloudWatch Synthetics では、これを「転送中の暗号化」と呼びます。転送中の値を暗号化すると、コンソールはプレーンテキストの値を、Canary のみがランタイム時に復号できる base64 でエンコードされた暗号文に置き換えます。

転送中の暗号化の仕組み

環境変数値に対して転送中の暗号化を選択した場合:

転送中の暗号化に必要なアクセス許可

転送中の暗号化には、次のアクセス許可が必要です。

以下は、Canary 実行ロールにアタッチする IAM ポリシーの例です。

{
"Version": "2012-10-17",
"Statement": [
  {
    "Effect": "Allow",
    "Action": "kms:Decrypt",
    "Resource": "arn:aws:kms:us-east-1:111122223333:key/a1b2c3d4-e5f6-7890-abcd-EXAMPLE11111"
  }
]
}

Canary スクリプトでの値の復号化

Canary スクリプトで暗号化された環境変数を使用するには、ランタイム時に復号します。次の Node.js の例は、環境変数の復号方法を示しています。

const { KMSClient, DecryptCommand } = require('@aws-sdk/client-kms');
const client = new KMSClient({ region: process.env.AWS_REGION });

async function decryptEnvVar(name) {
const encrypted = process.env[name];
const req = {
  CiphertextBlob: Buffer.from(encrypted, 'base64'),
};
const command = new DecryptCommand(req);
const response = await client.send(command);
return new TextDecoder().decode(response.Plaintext);
}

// Usage
const mySecret = await decryptEnvVar('MY_CONFIG_VAR');

Canary と他の AWS のサービスとの統合

Canary の AWS SDK ライブラリを使用して、他の AWS サービスと統合することができます。

これを行うには、Canary に次のコードを追加します。これらの例では、Canary は AWS Secrets Manager と統合されています。

次の Canary スクリプトのコードスニペットは、Secrets Manager との統合方法をより詳細に示しています。

var synthetics = require('@aws/synthetics-puppeteer');
const log = require('@aws/synthetics-logger');

const AWS = require('aws-sdk');
const secretsManager = new AWS.SecretsManager();

const getSecrets = async (secretName) => {
  var params = {
      SecretId: secretName
  };
  return await secretsManager.getSecretValue(params).promise();
}

const secretsExample = async function () {
  let URL = "<URL>";
  let page = await synthetics.getPage();

  log.info(`Navigating to URL: ${URL}`);
  const response = await page.goto(URL, {waitUntil: 'domcontentloaded', timeout: 30000});

  // Fetch secrets
  let secrets = await getSecrets("secretname")

  /**
  * Use secrets to login.
  *
  * Assuming secrets are stored in a JSON format like:
  * {
  *   "username": "<USERNAME>",
  *   "password": "<PASSWORD>"
  * }
  **/
  let secretsObj = JSON.parse(secrets.SecretString);
  await synthetics.executeStep('login', async function () {
      await page.type(">USERNAME-INPUT-SELECTOR<", secretsObj.username);
      await page.type(">PASSWORD-INPUT-SELECTOR<", secretsObj.password);

      await Promise.all([
        page.waitForNavigation({ timeout: 30000 }),
        await page.click(">SUBMIT-BUTTON-SELECTOR<")
      ]);
  });

  // Verify login was successful
  await synthetics.executeStep('verify', async function () {
      await page.waitForXPath(">SELECTOR<", { timeout: 30000 });
  });
};

exports.handler = async () => {
  return await secretsExample();
};

Canary に静的 IP アドレスの使用を強制する

静的 IP アドレスを使用するように Canary を設定できます。