Menulis skrip canary Node.js

Membuat kenari CloudWatch Synthetics dari awal

Berikut adalah contoh skrip Canary Synthetic minimal. skrip ini berhasil dijalani, dan mengembalikan rangkaian. Untuk melihat bentuk canary yang gagal, ubah let fail = false; untuk let fail = true;.

Anda harus menetapkan fungsi titik masuk untuk skrip canary. Untuk melihat cara mengunggah file ke lokasi Amazon S3 yang ditentukan sebagai ArtifactS3Location canary, buat file ini di bawah folder /tmp. Setelah skrip berjalan, status lulus/gagal dan metrik durasi dipublikasikan ke CloudWatch dan file di bawah/tmp diunggah ke 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();
};

Selanjutnya, kita akan memperluas script untuk menggunakan Synthetics logging dan membuat panggilan menggunakan SDK AWS . Untuk tujuan demonstrasi, skrip ini akan menciptakan klien Amazon DynamoDB dan memanggil API listTables DynamoDB. skrip ini mencatat respons terhadap permintaan dan log akan lulus atau gagal bergantung pada permintaan berhasil atau tidak.

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

Mengemas file kenari Node.js Anda

Jika Anda mengunggah skrip canary Anda menggunakan lokasi Amazon S3, file zip Anda harus menyertakan skrip Anda di bawah struktur folder ini: nodejs/node_modules/myCanaryFilename.js file.

Jika Anda memiliki lebih dari satu file .js tunggal atau Anda memiliki dependensi yang bergantung pada skrip, Anda dapat menggabungkan semuanya ke dalam satu paketan file ZIP yang memuat struktur folder nodejs/node_modules/myCanaryFilename.js file and other folders and files. Jika Anda menggunakan syn-nodejs-puppeteer-3.4 atau yang lebih baru, Anda dapat secara opsional meletakkan file canary Anda di folder lain dan membuat struktur folder Anda seperti ini: nodejs/node_modules/myFolder/myCanaryFilename.js file and other folders and files.

Nama handler

Pastikan untuk mengatur titik masuk skrip canary Anda (handler) myCanaryFilename.functionName agar cocok dengan nama file dari titik masuk skrip Anda. Jika Anda menggunakan runtime yang lebih awal dari syn-nodejs-puppeteer-3.4, functionName harus handler. Jika Anda menggunakan syn-nodejs-puppeteer-3.4 atau yang lebih baru, Anda dapat memilih nama fungsi apa pun sebagai handler. Jika Anda menggunakan syn-nodejs-puppeteer-3.4 atau lebih baru, Anda juga dapat secara opsional menyimpan canary di folder terpisah seperti nodejs/node_modules/myFolder/my_canary_filename. Jika Anda menyimpannya di folder terpisah, tentukan jalur itu di titik entri skrip Anda, seperti myFolder/my_canary_filename.functionName.

Mengubah skrip Puppeteer yang sudah ada untuk digunakan sebagai canary Synthetic

Bagian ini menjelaskan cara mengambil skrip Puppeteer dan memodifikasinya untuk berjalan sebagai skrip canary Synthetic. Untuk informasi selengkapnya tentang Puppeteer, silakan lihat API Puppeteer v1.14.0.

Kita akan mulai dengan contoh skrip 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();
})();

Langkah konversinya adalah sebagai berikut:

• Membuat dan mengekspor handler fungsi. Penanggung jawab adalah fungsi titik masuk untuk skrip. Jika Anda menggunakan runtime yang lebih awal dari syn-nodejs-puppeteer-3.4, fungsi handler harus diberi nama handler. Jika Anda menggunakan syn-nodejs-puppeteer-3.4 atau lebih baru, fungsi tersebut dapat memiliki nama apa pun, tetapi harus nama yang sama yang digunakan dalam skrip. Juga, jika Anda menggunakan syn-nodejs-puppeteer-3.4 atau yang lebih baru, Anda akan dapat menyimpan skrip Anda di bawah folder apa pun dan menentukan folder itu sebagai bagian dari nama handler.

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

• Gunakan dependensi Synthetics.

  var synthetics = require('Synthetics');

• Gunakan fungsi Synthetics.getPage untuk mendapatkan objek Page Puppeteer.

  const page = await synthetics.getPage();

  Objek halaman yang dikembalikan oleh fungsi Synthetics.getPage memiliki peristiwa page.on request, response dan requestfailed yang terinstrumentasi untuk pembuatan log. Synthetics juga mengatur pembuatan file HAR untuk permintaan dan respons di halaman tersebut, serta menambahkan ARN canary ke header agen-pengguna atas permintaan keluar di halaman tersebut.

skripnya sekarang siap untuk dijalankan sebagai canary Synthetics. Berikut adalah skrip yang diperbarui:

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

const basicPuppeteerExample = async function () {
    const page = await synthetics.getPage(); // 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();
};

Variabel-variabel lingkungan

Anda dapat menggunakan variabel lingkungan saat membuat canary. Hal ini memungkinkan Anda untuk menulis skrip canary tunggal dan kemudian menggunakan skrip tersebut dengan nilai yang berbeda untuk dengan cepat membuat beberapa canary yang memiliki tugas serupa.

Misalnya, andaikan organisasi Anda memiliki titik akhir seperti prod, dev, dan pre-release untuk berbagai tahap pengembangan perangkat lunak Anda, dan Anda perlu membuat canary untuk menguji setiap titik akhir ini. Anda dapat menulis skrip canary tunggal yang menguji perangkat lunak Anda dan kemudian menentukan nilai yang berbeda untuk variabel lingkungan titik akhir ketika Anda membuat masing-masing dari tiga canary. Kemudian, ketika Anda membuat canary, Anda menentukan skrip dan nilai-nilai yang akan digunakan untuk variabel lingkungan.

Nama-nama variabel lingkungan dapat memuat huruf, angka, dan karakter garis bawah. Nama variavel harus dimulai dengan sebuah huruf dan setidaknya dua karakter. Ukuran total variabel lingkungan Anda tidak dapat lebih dari 4 KB. Anda tidak dapat menentukan variabel lingkungan yang dicadangkan Lambda sebagai nama variabel lingkungan Anda. Untuk informasi selengkapnya tentang variabel lingkungan yang dicadangkan, silakan lihat Variabel lingkungan runtime.

penting

Kunci dan nilai variabel lingkungan tidak dienkripsi. Jangan menyimpan informasi sensitif di dalamnya.

Contoh skrip berikut menggunakan dua variabel lingkungan. Skrip ini adalah untuk canary yang memeriksa apakah sebuah halaman web tersedia. Ini menggunakan variabel lingkungan untuk membuat parameter URL yang diperiksa dan tingkat log CloudWatch Synthetics yang digunakannya.

Fungsi berikut menetapkan LogLevel ke nilai variabel lingkungan LOG_LEVEL.

 synthetics.setLogLevel(process.env.LOG_LEVEL);

Fungsi ini menetapkan URL ke nilai variabel lingkungan URL.

const URL = process.env.URL;

Ini adalah skrip yang lengkap. Ketika Anda membuat canary menggunakan skrip ini, Anda menentukan nilai untuk variabel lingkungan LOG_LEVEL dan 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.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();
};

Meneruskan variabel lingkungan ke script Anda

Untuk meneruskan variabel lingkungan ke skrip Anda ketika Anda membuat canary di konsol, tentukan kunci dan nilai-nilai variabel lingkungan di bagian Variabel lingkungan pada konsol. Untuk informasi selengkapnya, lihat Membuat canary.

Untuk meneruskan variabel lingkungan melalui API atau AWS CLI, gunakan EnvironmentVariables parameter di RunConfig bagian. Berikut ini adalah contoh AWS CLI perintah yang menciptakan kenari yang menggunakan dua variabel lingkungan dengan kunci Environment danRegion.

aws synthetics create-canary --cli-input-json '{
   "Name":"nameofCanary",
   "ExecutionRoleArn":"roleArn",
   "ArtifactS3Location":"s3://cw-syn-results-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"
}'

Mengintegrasikan kenari Anda dengan layanan lain AWS

Semua kenari dapat menggunakan pustaka AWS SDK. Anda dapat menggunakan perpustakaan ini ketika Anda menulis kenari Anda untuk mengintegrasikan kenari dengan layanan lain AWS .

Untuk melakukan hal itu, Anda perlu menambahkan kode berikut ke canary. Untuk contoh-contoh AWS Secrets Manager ini, digunakan sebagai layanan yang terintegrasi dengan kenari.

• Impor AWS SDK.

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

• Buat klien untuk AWS layanan yang Anda integrasikan.

  const secretsManager = new AWS.SecretsManager();

• Gunakan klien untuk melakukan panggilan API ke layanan tersebut.

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

Kode skrip snippet canary berikut menunjukkan contoh integrasi dengan Secrets Manager secara lebih terperinci.

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

Menyempurnakan canary Anda untuk menggunakan alamat IP statis

Anda dapat menyiapkan canary sehingga menggunakan alamat IP statis.

Untuk memaksa canary menggunakan alamat IP statis

1. Buat VPC baru. Untuk informasi selengkapnya, silakan lihat Menggunakan DNS dengan VPC Anda.

2. Membuat gateway internet baru. Untuk informasi selengkapnya, silakan lihat Menambahkan gateway internet ke VPC Anda.

3. Buat subnet publik di dalam VPC Anda yang baru.

4. Tambahkan tabel rute baru ke VPC.

5. Tambahkan rute di tabel rute baru, yang dimulai dari 0.0.0.0/0 ke gateway internet.

6. Kaitkan tabel rute baru dengan subnet publik.

7. Buat alamat IP elastis. Untuk informasi selengkapnya, silakan lihat Alamat IP elastis.

8. Buat gateway NAT baru dan tetapkan ke subnet publik dan alamat IP elastis.

9. Buat subnet privat di dalam VPC.

10. Tambahkan rute ke tabel rute bawaan VPC, yang dimulai dari 0.0.0.0/0 ke gateway NAT

11. Buat canary Anda.