Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Allgemeine Funktionen von Canary

Du kannst die folgenden Funktionen mit allen Canary-Runtimes verwenden.

Umgebungsvariablen

Sie können Umgebungsvariablen verwenden, wenn Sie Canaries erstellen. Sie können ein einzelnes Canary-Skript schreiben und es mit unterschiedlichen Werten verwenden, um schnell mehrere Canaries für eine ähnliche Aufgabe zu erstellen.

Nehmen wir zum Beispiel an, Ihre Organisation hat Endpunkte wie proddev, und pre-release für verschiedene Softwareentwicklungsphasen. Sie müssen Kanarien erstellen, um jeden Endpunkt zu testen. Sie können ein einzelnes Canary-Skript schreiben, das Ihre Software testet. Geben Sie dann unterschiedliche Werte für die Endpunkt-Umgebungsvariablen an, wenn Sie jede der drei Kanarien erstellen. Wenn Sie einen Canary erstellen, geben Sie die Werte für das Skript und die Umgebungsvariablen an.

Die Namen von Umgebungsvariablen können Buchstaben, Zahlen und den Unterstrich enthalten. Sie müssen mit einem Buchstaben beginnen und mindestens zwei Zeichen enthalten. Die Gesamtgröße Ihrer Umgebungsvariablen darf einen Wert von 4 KB nicht überschreiten. Sie können keine reservierten Lambda-Umgebungsvariablen als Namen Ihrer Umgebungsvariablen angeben. Weitere Informationen zu reservierten Umgebungsvariablen finden Sie unter Laufzeitumgebungsvariablen.

Das folgende Beispielskript verwendet zwei Umgebungsvariablen. Dieses Skript ist für einen Canary bestimmt, der prüft, ob eine Webseite verfügbar ist. Es verwendet Umgebungsvariablen, um sowohl die URL, die es überprüft, als auch das CloudWatch Synthetics-Log-Level, das es verwendet, zu parametrisieren.

Die folgenden Snippets sind Teil des vollständigen Skripts, das folgt.

Die folgende Funktion setzt LogLevel auf den Wert der Umgebungsvariablen LOG_LEVEL.

 synthetics.setLogLevel(process.env.LOG_LEVEL);

Diese Funktion setzt URL auf den Wert der Umgebungsvariablen URL.

const URL = process.env.URL;

Das folgende vollständige Skript veranschaulicht beide Umgebungsvariablen. Wenn Sie mit diesem Skript einen Canary erstellen, geben Sie Werte für die Umgebungsvariablen LOG_LEVEL und URL an.

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();
};

Übergeben von Umgebungsvariablen an Ihr Skript

Um Umgebungsvariablen an Ihr Skript zu übergeben, wenn Sie einen Canary in der Konsole erstellen, geben Sie die Schlüssel und Werte der Umgebungsvariablen im Abschnitt Umgebungsvariablen der Konsole an. Weitere Informationen finden Sie unter Erstellen eines Canarys.

Um Umgebungsvariablen über die API oder zu übergeben AWS CLI, verwenden Sie den EnvironmentVariables Parameter im RunConfig Abschnitt. Im Folgenden finden Sie einen AWS CLI Beispielbefehl, mit dem ein Canary erstellt wird, das zwei Umgebungsvariablen mit den Schlüsseln Environment und verwendetRegion.

Das vollständige Schema des RunConfig ParametersEnvironmentVariables, einschließlich, finden Sie CanaryRunConfigInput in der Amazon CloudWatch Synthetics API-Referenz.

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"
}'

Verschlüsselung von Umgebungsvariablen im Ruhezustand mit einem vom Kunden verwalteten Schlüssel

Standardmäßig verschlüsselt ein AWS eigener Schlüssel die Canary-Umgebungsvariablen im Ruhezustand. Sie können einen vom Kunden verwalteten AWS KMS Schlüssel angeben, um die Canary-Umgebungsvariablen im Ruhezustand zu verschlüsseln. Mit einem vom Kunden verwalteten Schlüssel haben Sie die volle Kontrolle über die Verschlüsselung vertraulicher Konfigurationsdaten. In den folgenden Abschnitten werden die Anforderungen, Konfigurationsschritte und Berechtigungen für die Verwendung eines vom Kunden verwalteten Schlüssels beschrieben.

Voraussetzungen

Bevor Sie einen vom Kunden verwalteten Schlüssel konfigurieren, stellen Sie sicher, dass Sie die folgenden Anforderungen erfüllen:

Konfiguration eines vom Kunden verwalteten Schlüssels

Du kannst einen vom Kunden verwalteten Schlüssel konfigurieren, wenn du einen Canary erstellst oder aktualisierst. Die folgenden Verfahren zeigen, wie Sie die Verschlüsselung mithilfe der CloudWatch Amazon-Konsole und der Synthetics-API konfigurieren.

Konfigurieren Sie die Verschlüsselung in der Konsole

Um einen Canary in der CloudWatch Amazon-Konsole zu erstellen oder zu bearbeiten, erweitern Sie den Abschnitt Umgebungsvariablen. Wählen Sie unter Konfiguration der Verschlüsselung im Ruhezustand die Option Einen vom Kunden verwalteten Schlüssel verwenden aus und wählen Sie dann den ARN Ihres AWS KMS Schlüssels aus oder geben Sie ihn an.

Konfigurieren Sie die Verschlüsselung mithilfe der API

Wenn Sie CreateCanary oder aufrufenUpdateCanary, geben Sie den KmsKeyArn Parameter mit dem ARN Ihres vom Kunden verwalteten Schlüssels an. Um zum AWS verwalteten Schlüssel zurückzukehren, setzen Sie ihn KmsKeyArn auf eine leere Zeichenfolge.

Beispiel: CreateCanary Anfrage mit einem vom Kunden verwalteten Schlüssel

{
  "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"
    }
  }
}

Erforderliche Berechtigungen für die Verschlüsselung im Ruhezustand

Wenn du den Canary erstellst oder aktualisierst, benötigst du die folgenden Berechtigungen für den AWS KMS Schlüssel:

Für die Canary-Execution-Rolle sind keine AWS KMS Berechtigungen für die Verschlüsselung im Ruhezustand erforderlich. Lambda verwendet den Grant für die Verschlüsselung und Entschlüsselung.

Multi-location Kanaren

Bei Kanarienvögeln mit mehreren Standorten kann jeder Replikatstandort seinen eigenen Schlüssel haben. AWS KMS Geben Sie den KmsKeyArn im AddReplicaLocations Parameter an, wenn Sie einen Canary erstellen oder aktualisieren. Der Schlüssel muss sich in derselben Region wie das Replikat befinden.

Verschlüsselung von Umgebungsvariablen während der Übertragung

Zusätzlich zur Verschlüsselung im Ruhezustand können Sie einzelne Werte von Umgebungsvariablen verschlüsseln, bevor CloudWatch Synthetics sie speichert. CloudWatch Synthetics bezeichnet dies als Verschlüsselung bei der Übertragung. Wenn du einen Wert während der Übertragung verschlüsselst, ersetzt die Konsole den Klartext-Wert durch einen Base64-kodierten Chiffretext, den nur dein Canary zur Laufzeit entschlüsseln kann.

So funktioniert die Verschlüsselung bei der Übertragung

Wenn Sie sich dafür entscheiden, einen Umgebungsvariablenwert während der Übertragung zu verschlüsseln:

Erforderliche Berechtigungen für die Verschlüsselung während der Übertragung

Für die Verschlüsselung bei der Übertragung benötigen Sie die folgenden Berechtigungen:

Im Folgenden finden Sie ein Beispiel für eine IAM-Richtlinie, die an die Canary-Ausführungsrolle angehängt werden kann:

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

Werte in Ihrem Canary-Skript entschlüsseln

Um eine verschlüsselte Umgebungsvariable in Ihrem Canary-Skript zu verwenden, entschlüsseln Sie sie zur Laufzeit. Das folgende Node.js Beispiel zeigt, wie eine Umgebungsvariable entschlüsselt wird:

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');

Integriere deinen Canary mit anderen AWS service

Du kannst die AWS SDK-Bibliothek in deinem Canary verwenden, um sie in andere AWS Dienste zu integrieren.

Füge dazu den folgenden Code zu deinem Canary hinzu. In diesen Beispielen integriert sich der Kanarienvogel in AWS Secrets Manager.

Der folgende Canary-Skript-Codeausschnitt zeigt detaillierter, wie Sie Secrets Manager integrieren können.

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();
};

Verwenden Sie Ihren Canary dazu, eine statische IP-Adresse zu verwenden

Sie können einen Canary so einrichten, dass er eine statische IP-Adresse verwendet.