Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Caractéristiques communes des canaris

Vous pouvez utiliser les fonctionnalités suivantes avec tous les environnements d'exécution de Canary.

Variables d’environnement

Vous pouvez utiliser des variables d'environnement lorsque vous créez des canaris. Vous pouvez écrire un seul script canari et l'utiliser avec différentes valeurs pour créer rapidement plusieurs canaris pour une tâche similaire.

Supposons, par exemple, que votre organisation dispose de points de terminaison tels que proddev, et pre-release pour différentes étapes de développement logiciel. Vous devez créer des canaris pour tester chaque point de terminaison. Vous pouvez écrire un seul script Canary pour tester votre logiciel. Spécifiez ensuite différentes valeurs de variables d'environnement du point de terminaison lorsque vous créez chacun des trois canaris. Lorsque vous créez un canari, spécifiez le script et les valeurs des variables d'environnement.

Les noms des variables d'environnement peuvent contenir des lettres, des chiffres et le caractère de soulignement. Ils doivent commencer par une lettre et comporter au moins deux caractères. La taille totale de vos variables d'environnement ne peut pas dépasser 4 Ko. Vous ne pouvez pas spécifier de variables d'environnement réservées Lambda comme noms pour vos variables d'environnement. Pour plus d'informations sur les variables d'environnement réservées, consultez Variables d'environnement d'exécution.

L'exemple de script suivant utilise deux variables d'environnement. Ce script est destiné à un script Canary qui vérifie si une page web est disponible. Il utilise des variables d'environnement pour paramétrer à la fois l'URL qu'il vérifie et le niveau de journal Synthetics qu'il utilise CloudWatch .

Les extraits suivants font partie du script complet présenté ci-dessous.

La fonction suivante définit LogLevel sur la valeur de la variable d'environnement LOG_LEVEL.

 synthetics.setLogLevel(process.env.LOG_LEVEL);

Cette fonction définit URL sur la valeur de la variable d'environnement URL.

const URL = process.env.URL;

Le script complet suivant illustre les deux variables d'environnement. Lorsque vous créez un script Canary à l'aide de ce script, vous spécifiez les valeurs pour les variables d'environnement LOG_LEVEL et 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();
};

Transmission de variables d'environnement à votre script

Pour transmettre des variables d'environnement à votre script lorsque vous créez un script Canary dans la console, spécifiez les clés et les valeurs des variables d'environnement dans la section Environment variables (Variables d'environnement) de la console. Pour de plus amples informations, veuillez consulter Création d'un Canary.

Pour transmettre des variables d'environnement via l'API AWS CLI, utilisez le EnvironmentVariables paramètre de la RunConfig section. Voici un exemple de AWS CLI commande qui crée un canari qui utilise deux variables d'environnement avec les clés de Environment etRegion.

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

Chiffrer les variables d'environnement au repos à l'aide d'une clé gérée par le client

Par défaut, une clé AWS détenue chiffre les variables d'environnement Canary au repos. Vous pouvez spécifier une AWS KMS clé gérée par le client pour chiffrer les variables d'environnement Canary au repos. Avec une clé gérée par le client, vous avez un contrôle total sur le chiffrement des données de configuration sensibles. Les sections suivantes décrivent les exigences, les étapes de configuration et les autorisations relatives à l'utilisation d'une clé gérée par le client.

Exigences

Avant de configurer une clé gérée par le client, vérifiez que vous répondez aux exigences suivantes :

Configuration d'une clé gérée par le client

Vous pouvez configurer une clé gérée par le client lorsque vous créez ou mettez à jour un Canary. Les procédures suivantes montrent comment configurer le chiffrement à l'aide de la CloudWatch console Amazon et de l'API Synthetics.

Configuration du chiffrement dans la console

Pour créer ou modifier un canari dans la CloudWatch console Amazon, développez la section Variables d'environnement. Sous Configuration du chiffrement au repos, choisissez Utiliser une clé gérée par le client, puis choisissez ou spécifiez l'ARN de votre AWS KMS clé.

Configuration du chiffrement à l'aide de l'API

Lorsque vous appelez CreateCanary ouUpdateCanary, spécifiez le KmsKeyArn paramètre avec l'ARN de votre clé gérée par le client. Pour revenir à la clé AWS gérée, définissez KmsKeyArn une chaîne vide.

Exemple : CreateCanary demande avec une clé gérée par le client

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

Autorisations requises pour le chiffrement au repos

Si vous créez ou mettez à jour le canari, vous devez disposer des autorisations suivantes sur la AWS KMS clé :

Le rôle d'exécution Canary ne nécessite aucune AWS KMS autorisation pour le chiffrement au repos. Lambda utilise la subvention pour gérer le chiffrement et le déchiffrement.

Multi-location canaris

Pour les canaris à sites multiples, chaque emplacement répliqué peut avoir sa propre clé. AWS KMS Spécifiez le AddReplicaLocations paramètre KmsKeyArn in lors de la création ou de la mise à jour d'un canari. La clé doit se trouver dans la même région que la réplique.

Chiffrement des variables d'environnement en transit

Outre le chiffrement au repos, vous pouvez chiffrer des valeurs de variables d'environnement individuelles avant que CloudWatch Synthetics ne les stocke. CloudWatch Synthetics appelle cela le chiffrement en transit. Lorsque vous chiffrez une valeur en transit, la console remplace la valeur en texte brut par un texte chiffré codé en base64 que seul votre Canary peut déchiffrer au moment de l'exécution.

Comment fonctionne le chiffrement en transit

Lorsque vous choisissez de chiffrer la valeur d'une variable d'environnement en transit :

Autorisations requises pour le chiffrement en transit

Vous devez disposer des autorisations suivantes pour le chiffrement en transit :

Voici un exemple de politique IAM à associer au rôle d'exécution Canary :

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

Déchiffrer des valeurs dans votre script Canary

Pour utiliser une variable d'environnement chiffrée dans votre script Canary, déchiffrez-la au moment de l'exécution. L' Node.js exemple suivant montre comment déchiffrer une variable d'environnement :

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

Intégrer votre canari à d'autres AWS services

Vous pouvez utiliser la bibliothèque AWS SDK de votre Canary pour l'intégrer à d'autres AWS services.

Pour ce faire, ajoutez le code suivant à votre canari. Dans ces exemples, le canari s'intègre à AWS Secrets Manager.

L'extrait de code Canary suivant montre plus en détail comment intégrer 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();
};

Utilisation forcée d'une adresse IP statique par le script Canary

Vous pouvez configurer un script Canary afin qu'il utilise une adresse IP statique.