Características comunes de los canarios

Puede utilizar las siguientes características con todos los tiempos de ejecución de los canarios.

Variables de entorno

Puede utilizar variables de entorno al crear canarios. Puede escribir un único script de canario y utilizarlo con distintos valores para crear rápidamente varios canarios que realicen una tarea similar.

Por ejemplo, suponga que la organización tiene puntos de conexión como prod, dev y pre-release para distintas etapas del desarrollo de software. Debe crear canarios para probar cada punto de conexión. Puede escribir un único script de canario que pruebe el software. A continuación, especifique distintos valores para la variable de entorno del punto de conexión al crear cada uno de los tres canarios. Cuando cree un canario, especifique el script y los valores de las variables de entorno.

Los nombres de las variables de entorno pueden contener letras, números y guiones bajos. Deben comenzar con una letra y tener al menos dos caracteres. El tamaño total de las variables de entorno no puede superar los 4 KB. No es posible especificar variables de entorno reservadas de Lambda como claves para sus variables de entorno. Para obtener más información acerca de las variables de entorno reservadas, consulte Runtime environment variables (Variables de entorno en tiempo de ejecución).

En el siguiente ejemplo el script utiliza dos variables de entorno. Este script es para un valor controlado que verifica si hay una página web disponible. Utiliza variables de entorno para parametrizar tanto la URL que verifica como el nivel de registro de CloudWatch Synthetics que utiliza.

Los siguientes fragmentos forman parte del script completo que se muestra más adelante.

La siguiente función establece LogLevel al valor de la variable de entorno LOG_LEVEL.

 synthetics.setLogLevel(process.env.LOG_LEVEL);

La función establece URL al valor de la variable de entorno URL.

const URL = process.env.URL;

El siguiente script completo muestra el uso de ambas variables de entorno. Cuando se crea un valor controlado con este script, se especifican los valores para las variables de entorno LOG_LEVEL y 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();
};

Traspaso de las variables de entorno al script

Para pasar variables de entorno al script cuando cree un valor controlado en la consola, especifique las claves y los valores de las variables de entorno en la sección Variables de entorno en la consola. Para obtener más información, consulte Creación de un valor controlado.

Para pasar variables de entorno a través de la API o AWS CLI, utilice el parámetro EnvironmentVariables en la sección RunConfig. A continuación, se observa un ejemplo del comando de AWS CLI que crea un valor controlado que utiliza dos variables de entorno con claves de Environment y Region.

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

Cifrado en reposo de las variables de entorno mediante una clave administrada por el cliente

De forma predeterminada, una clave propiedad de AWS cifra en reposo las variables de entorno del canario. Puede especificar una clave de AWS KMS administrada por el cliente para cifrar en reposo las variables de entorno del canario. Con una clave administrada por el cliente, tiene control total sobre el cifrado de los datos de configuración confidenciales. Las siguientes secciones describen los requisitos, los pasos de configuración y los permisos necesarios para utilizar una clave administrada por el cliente.

Requisitos

Antes de configurar una clave administrada por el cliente, compruebe que cumple los siguientes requisitos:

Configuración de una clave administrada por el cliente

Puede configurar una clave administrada por el cliente al crear o actualizar un canario. Los siguientes procedimientos muestran cómo configurar el cifrado mediante la consola de Amazon CloudWatch y la API de Synthetics.

Configuración del cifrado en la consola

Para crear o editar un canario en la consola de Amazon CloudWatch, expanda la sección Variables de entorno. En Configuración del cifrado en reposo, seleccione Usar una clave administrada por el cliente y, a continuación, seleccione o especifique el ARN de la clave de AWS KMS.

Configuración del cifrado mediante la API

Al llamar a CreateCanary o UpdateCanary, especifique el parámetro KmsKeyArn con el ARN de la clave administrada por el cliente. Para volver a utilizar la clave administrada por AWS, establezca KmsKeyArn en una cadena vacía.

Ejemplo: solicitud CreateCanary con una clave administrada por el cliente

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

Permisos obligatorios para el cifrado en reposo

Para crear o actualizar el canario, debe disponer de los siguientes permisos para la clave de AWS KMS:

El rol de ejecución del canario no requiere permisos de AWS KMS para el cifrado en reposo. Lambda utiliza la concesión para gestionar el cifrado y el descifrado.

Canarios en varias ubicaciones

En el caso de los canarios en varias ubicaciones, cada ubicación de réplica puede tener su propia clave de AWS KMS. Especifique el KmsKeyArn en el parámetro AddReplicaLocations al crear o actualizar un canario. La clave debe estar en la misma región que la réplica.

Cifrado de las variables de entorno en tránsito

Además del cifrado en reposo, puede cifrar los valores individuales de las variables de entorno antes de que CloudWatch Synthetics los almacene. CloudWatch Synthetics denomina a este proceso cifrado en tránsito. Cuando cifra un valor en tránsito, la consola sustituye el valor de texto plano por un texto cifrado codificado en base64 que solo el canario puede descifrar durante el tiempo de ejecución.

Funcionamiento del cifrado en tránsito

Cuando elige cifrar en tránsito el valor de una variable de entorno:

Permisos obligatorios para el cifrado en tránsito

Se necesitan los siguientes permisos para el cifrado en tránsito:

A continuación, se muestra un ejemplo de una política de IAM que puede asociar al rol de ejecución del canario:

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

Descifrado de valores en el script del canario

Para utilizar una variable de entorno cifrada en el script del canario, descífrela durante el tiempo de ejecución. En el siguiente ejemplo de Node.js se muestra cómo descifrar una variable de entorno:

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

Integración del valor controlado con otros servicios de AWS

Puede utilizar la biblioteca del SDK de AWS en el canario para integrarlo con otros servicios de AWS.

Para ello, agregue el siguiente código al canario. En estos ejemplos, el canario se integra con AWS Secrets Manager.

En el siguiente fragmento de código del script del canario se muestra con más detalle cómo realizar la integración con 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();
};

Forzar al valor controlado para que utilice una dirección IP estática

Se puede configurar un valor controlado para que utilice una dirección IP estática.