Écrire un script Canary Node.js à l'aide du moteur d'exécution Puppeteer

Création d'un CloudWatch canari Synthetics à partir de zéro

Voici un exemple minimal de script Canary Synthetics. Ce script est transmis comme une exécution réussie et renvoie une chaîne. Pour voir à quoi ressemble un script Canary qui a échoué, remplacez let fail = false; par let fail = true;.

Vous devez définir une fonction de point d'entrée pour le script Canary. Pour voir comment les fichiers sont chargés vers l'emplacement Amazon S3 indiqué comme étant celui du CanaryArtifactS3Location, créez ces fichiers dans le /tmp dossier. Tous les artefacts Canary doivent être stockés dans ce répertoire/tmp, car il s'agit du seul répertoire accessible en écriture. Assurez-vous que le chemin de capture d'écran est défini sur /tmp pour toutes les captures d'écran ou autres fichiers créés par le script. Synthetics télécharge automatiquement les fichiers /tmp dans un compartiment S3.

/tmp/<name>

Une fois le script exécuté, le statut de réussite/d'échec et les métriques de durée sont publiés dans un compartiment S3 CloudWatch et les fichiers situés en dessous /tmp sont chargés dans un compartiment S3.

const basicCustomEntryPoint = async function () {

    // Insert your code here

    // Perform multi-step pass/fail check

    // Log decisions made and results to /tmp

    // Be sure to wait for all your code paths to complete 
    // before returning control back to Synthetics.
    // In that way, your canary will not finish and report success
    // before your code has finished executing

    // Throw to fail, return to succeed
    let fail = false;
    if (fail) {
        throw "Failed basicCanary check.";
    }

    return "Successfully completed basicCanary checks.";
};

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

Ensuite, nous allons développer le script pour utiliser la journalisation Synthetics et passer un appel à l'aide du. AWS SDK À des fins de démonstration, ce script créera un client Amazon DynamoDB et appellera DynamoDB. listTables API Il enregistre la réponse à la demande et les journaux réussissent ou échouent selon le succès de la demande.

const log = require('SyntheticsLogger');
const AWS = require('aws-sdk');
// Require any dependencies that your script needs
// Bundle additional files and dependencies into a .zip file with folder structure
// nodejs/node_modules/additional files and folders

const basicCustomEntryPoint = async function () {

    log.info("Starting DynamoDB:listTables canary.");
    
    let dynamodb = new AWS.DynamoDB();
    var params = {};
    let request = await dynamodb.listTables(params);
    try {
        let response = await request.promise();
        log.info("listTables response: " + JSON.stringify(response));
    } catch (err) {
        log.error("listTables error: " + JSON.stringify(err), err.stack);
        throw err;
    }

    return "Successfully completed DynamoDB:listTables canary.";
};

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

Empaqueter vos fichiers Canary Node.js

Si vous chargez vos scripts canary à l'aide d'un emplacement Simple Storage Service (Amazon S3), votre fichier zip doit inclure votre script sous la structure de dossier suivante : nodejs/node_modules/myCanaryFilename.js file.

Si vous avez plusieurs .js fichiers ou si votre script dépend d'une dépendance, vous pouvez tous les regrouper dans un seul ZIP fichier contenant la structure de dossiersnodejs/node_modules/myCanaryFilename.js file and other folders and files. Si vous utilisez syn-nodejs-puppeteer-3.4 ou une version ultérieure, vous pouvez éventuellement placer vos fichiers canary dans un autre dossier et créer votre structure de dossiers comme suit : nodejs/node_modules/myFolder/myCanaryFilename.js file and other folders and files.

Nom du gestionnaire

Assurez-vous de définir le point d'entrée (gestionnaire) de votre script Canary de sorte que myCanaryFilename.functionName corresponde au nom du fichier du point d'entrée de votre script. Si vous utilisez une exécution antérieure à syn-nodejs-puppeteer-3.4, alors functionName doit être handler. Si vous utilisez syn-nodejs-puppeteer-3.4 ou une version ultérieure, vous pouvez choisir n'importe quel nom de fonction comme gestionnaire. Si vous utilisez syn-nodejs-puppeteer-3.4 ou une version ultérieure, vous pouvez également stocker le script canary dans un dossier séparé tel que nodejs/node_modules/myFolder/my_canary_filename. Si vous le stockez dans un dossier séparé, spécifiez ce chemin dans le point d'entrée de votre script, tel que myFolder/my_canary_filename.functionName.

Modification d'un script Puppeteer existant pour l'utiliser en tant que script Canary Synthetics

Cette section explique comment prendre des scripts Puppeteer, pour ensuite les modifier afin qu'ils s'exécutent en tant que scripts Canary Synthetics. Pour plus d'informations sur Puppeteer, voir Puppeteer v1.14.0. API

Nous allons commencer avec cet exemple de script Puppeteer :

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({path: 'example.png'});

  await browser.close();
})();

Les étapes de conversion sont les suivantes :

• Créez et exportez une fonction handler. Le gestionnaire est la fonction de point d'entrée du script. Si vous utilisez une exécution antérieure à syn-nodejs-puppeteer-3.4, la fonction du gestionnaire doit être nommée handler. Si vous utilisez syn-nodejs-puppeteer-3.4 ou une version ultérieure, la fonction peut porter n'importe quel nom, mais il doit être identique à celui utilisé dans le script. De plus, si vous utilisez syn-nodejs-puppeteer-3.4 ou une version ultérieure, vous pouvez stocker vos scripts dans n'importe quel dossier et spécifier ce dossier dans le nom du gestionnaire.

  const basicPuppeteerExample = async function () {};
  
  exports.handler = async () => {
      return await basicPuppeteerExample();
  };

• Utilisez la dépendance Synthetics.

  var synthetics = require('Synthetics');

• Utilisez la fonction Synthetics.newPage pour obtenir un objet Page Puppeteer.

  const page = await synthetics.newPage();

  L'objet de page renvoyé par les Synthetics. newPage La fonction possède le page.on request response et les requestfailed événements sont instrumentés pour la journalisation. Synthetics HAR configure également la génération de fichiers pour les requêtes et les réponses sur la page, et ajoute le ARN canari aux en-têtes de l'agent utilisateur des demandes sortantes sur la page.

Le script est maintenant prêt à être exécuté en tant que script Canary Synthetics. Voici le script mis à jour :

var synthetics = require('Synthetics');  // Synthetics dependency

const basicPuppeteerExample = async function () {
    const page = await synthetics.newPage(); // Get instrumented page from Synthetics
    await page.goto('https://example.com');
    await page.screenshot({path: '/tmp/example.png'}); // Write screenshot to /tmp folder
};

exports.handler = async () => {  // Exported handler function 
    return await basicPuppeteerExample();
};

Variables d’environnement

Vous pouvez utiliser des variables d'environnement lorsque vous créez des scripts Canary. Cela vous permet d'écrire un seul script Canary, puis d'utiliser ce script avec des valeurs différentes pour créer rapidement plusieurs scripts Canary ayant une tâche similaire.

Par exemple, supposons que votre organisation dispose de points de terminaison tels que prod, dev et pre-release pour les différentes étapes de votre développement logiciel et que vous devez créer des scripts Canary pour tester chacun de ces points de terminaison. Vous pouvez écrire un seul script Canary qui teste votre logiciel, puis spécifier différentes valeurs pour la variable d'environnement de point de terminaison lorsque vous créez chacun des trois scripts Canary. Ensuite, lorsque vous créez un script Canary, vous spécifiez le script et les valeurs à utiliser pour les 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.

Important

Les clés et les valeurs des variables d'environnement ne sont pas chiffrées. Ne stockez pas d'informations sensibles dans celles-ci.

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 le niveau de vérification et le niveau de journalisation Synthetics URL qu'il utilise CloudWatch .

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;

C'est le script complet. 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('Synthetics');
const log = require('SyntheticsLogger');

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.newPage();
    //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 le API ou 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"
}'

Intégrer votre Canary à d'autres AWS services

Tous les canaris peuvent utiliser la AWS SDK bibliothèque. Vous pouvez utiliser cette bibliothèque lorsque vous écrivez votre canari pour intégrer le canari à d'autres AWS services.

Pour ce faire, vous devez ajouter le code suivant à votre script canary. Pour ces exemples, AWS Secrets Manager il est utilisé comme service auquel le canari s'intègre.

• Importez le AWS SDK.

  const AWS = require('aws-sdk');

• Créez un client pour le AWS service auquel vous souhaitez procéder à l'intégration.

  const secretsManager = new AWS.SecretsManager();

• Utilisez le client pour API appeler ce service.

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

L'extrait de code de script Canary suivant illustre une intégration à Secrets Manager de manière plus détaillée.

var synthetics = require('Synthetics');
const log = require('SyntheticsLogger');
 
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.newPage();
    
    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.

Pour forcer un script Canary à utiliser une adresse IP statique

1. Créez un nouveau VPC. Pour plus d'informations, consultez la section Utilisation DNS avec votre VPC.

2. Créez une nouvelle passerelle Internet. Pour plus d'informations, consultez la section Ajout d'une passerelle Internet à votre VPC.

3. Créez un sous-réseau public dans votre nouveauVPC.

4. Ajoutez une nouvelle table de routage auVPC.

5. Ajoutez un routage dans la nouvelle table de routage, qui va de 0.0.0.0/0 à la passerelle Internet.

6. Associez la nouvelle table de routage au sous-réseau public.

7. Créez une adresse IP Elastic. Pour plus d'informations, consultez Adresses IP élastiques.

8. Créez une nouvelle NAT passerelle et attribuez-la au sous-réseau public et à l'adresse IP élastique.

9. Créez un sous-réseau privé à l'intérieur duVPC.

10. Ajoutez une route à la table de routage VPC par défaut, qui va de 0.0.0.0/0 à la NAT passerelle

11. Créez votre script Canary.