Caratteristiche comuni dei canarini

Puoi usare le seguenti funzionalità con tutti i runtime di Canary.

Variabili di ambiente

Puoi usare le variabili di ambiente quando crei canaries. Puoi scrivere un singolo script canarino e usarlo con valori diversi per creare rapidamente più canarini per un'attività simile.

Ad esempio, supponiamo che l'organizzazione disponga di endpoint come e pre-release per diverse prod fasi dev di sviluppo del software. È necessario creare canarini per testare ogni endpoint. Puoi scrivere un singolo script Canary per testare il tuo software. Quindi, specificate valori diversi per le variabili di ambiente dell'endpoint quando create ciascuno dei tre canarini. Quando create un canarino, specificate i valori dello script e delle variabili di ambiente.

I nomi delle variabili di ambiente possono contenere lettere, numeri e il carattere di sottolineatura. Devono iniziare con una lettera e avere almeno due caratteri. La dimensione totale delle variabili di ambiente non può superare i 4 KB. Non è possibile specificare alcuna variabile di ambiente riservato Lambda come nomi per le variabili di ambiente. Per ulteriori informazioni sulle variabili di ambiente riservate, consulta Variabili di ambiente di runtime.

Le variabili di ambiente non sono crittografate sul lato client

Per impostazione predefinita, AWS crittografa le chiavi e i valori delle variabili di ambiente inattivi utilizzando una AWS chiave proprietaria. Tuttavia, CloudWatch Synthetics non applica la crittografia lato client. Archivia le informazioni sensibili solo dopo averle crittografate in transito. Per ulteriori informazioni, consulta Crittografia delle variabili di ambiente in transito. Puoi anche utilizzare una AWS KMS chiave gestita dal cliente per crittografare le variabili di ambiente del tuo canarino a riposo. Per ulteriori informazioni, consulta Crittografia delle variabili di ambiente inattive con una chiave gestita dal cliente.

Lo script di esempio seguente utilizza due variabili di ambiente. Questo script è per un canary che controlla se una pagina Web è disponibile. Utilizza variabili di ambiente per parametrizzare sia l'URL che controlla sia il livello di registro Synthetics CloudWatch che utilizza.

I seguenti frammenti fanno parte dello script completo mostrato di seguito.

La seguente funzione imposta LogLevel al valore della variabile di ambiente LOG_LEVEL.

 synthetics.setLogLevel(process.env.LOG_LEVEL);

Questa funzione imposta URL al valore della variabile di ambiente URL.

const URL = process.env.URL;

Lo script completo seguente illustra entrambe le variabili di ambiente. Quando crei un canary utilizzando questo script, si specificano i valori per le variabili di ambiente LOG_LEVEL e 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();
};

Passare le variabili di ambiente allo script

Per passare le variabili di ambiente allo script quando crei un canary nella console, specifica le chiavi e i valori delle variabili di ambiente nella finestra Environment variables (Variabili di ambiente) della console. Per ulteriori informazioni, consulta Creazione di un Canary.

Per passare le variabili di ambiente tramite l'API oppure AWS CLI, utilizzate il EnvironmentVariables parametro nella RunConfig sezione. Di seguito è riportato un AWS CLI comando di esempio che crea un canarino che utilizza due variabili di ambiente con le chiavi Environment eRegion.

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

Crittografia delle variabili di ambiente inattive con una chiave gestita dal cliente

Per impostazione predefinita, una chiave AWS proprietaria crittografa le variabili di ambiente Canary a riposo. È possibile specificare una AWS KMS chiave gestita dal cliente per crittografare le variabili di ambiente Canary a riposo. Con una chiave gestita dal cliente, hai il pieno controllo sulla crittografia dei dati di configurazione sensibili. Le sezioni seguenti descrivono i requisiti, i passaggi di configurazione e le autorizzazioni per l'utilizzo di una chiave gestita dal cliente.

Requisiti

Prima di configurare una chiave gestita dal cliente, verifica di soddisfare i seguenti requisiti:

• La AWS KMS chiave deve essere una chiave di crittografia simmetrica.

• La policy chiave deve essere kms:CreateGrant concessa al chiamante (il principale IAM che chiama l'API Synthetics).

• AWS Lambda utilizza la concessione per crittografare e decrittografare le variabili di ambiente a riposo.

• La AWS KMS chiave deve trovarsi nella stessa AWS regione del canarino.

Configurazione di una chiave gestita dal cliente

Puoi configurare una chiave gestita dal cliente quando crei o aggiorni un canary. Le seguenti procedure mostrano come configurare la crittografia utilizzando la CloudWatch console Amazon e l'API Synthetics.

Configura la crittografia nella console

Per creare o modificare un canarino nella CloudWatch console Amazon, espandi la sezione Variabili di ambiente. In Configurazione Encryption at rest, scegli Usa una chiave gestita dal cliente, quindi scegli o specifica l'ARN della tua AWS KMS chiave.

Configura la crittografia utilizzando l'API

Quando chiami CreateCanary oUpdateCanary, specifica il KmsKeyArn parametro con l'ARN della chiave gestita dal cliente. Per tornare alla chiave AWS gestita, imposta KmsKeyArn una stringa vuota.

Esempio: CreateCanary richiesta con una chiave gestita dal 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"
  }
}
}

Autorizzazioni richieste per la crittografia a riposo

Se crei o aggiorni il canarino, devi disporre delle seguenti autorizzazioni sulla chiave: AWS KMS

• kms:CreateGrant, kms:Encrypt —Necessario per configurare una chiave gestita dal cliente per il canarino.

• kms:Decrypt—Necessario per visualizzare e gestire le variabili di ambiente crittografate con una chiave gestita dal cliente.

• kms:DescribeKey—Necessario per convalidare la chiave.

Il ruolo Canary Execution non richiede AWS KMS autorizzazioni per la crittografia a riposo. Lambda utilizza la concessione per gestire la crittografia e la decrittografia.

Multi-location canarini

Per i canarini con più sedi, ogni posizione di replica può avere la propria chiave. AWS KMS Specificalo KmsKeyArn nel AddReplicaLocations parametro quando crei o aggiorni un canarino. La chiave deve trovarsi nella stessa regione della replica.

Crittografia delle variabili di ambiente in transito

Oltre alla crittografia a riposo, è possibile crittografare i valori delle singole variabili di ambiente prima CloudWatch che Synthetics li memorizzi. CloudWatch Synthetics chiama questa crittografia in transito. Quando crittografate un valore in transito, la console sostituisce il valore in chiaro con un testo cifrato con codifica Base64 che solo il vostro canary può decifrare in fase di esecuzione.

Come funziona la crittografia in transito

Quando scegli di crittografare un valore di variabile di ambiente in transito:

1. La console chiama kms:Encrypt con la AWS KMS chiave selezionata per crittografare il valore in chiaro.

2. Il testo cifrato crittografato (con codifica base64) sostituisce il valore di testo in chiaro nella configurazione della variabile di ambiente.

3. In fase di esecuzione, lo script canary decrittografa il valore chiamando. kms:Decrypt

Autorizzazioni richieste per la crittografia in transito

Sono necessarie le seguenti autorizzazioni per la crittografia in transito:

• Utente della console o chiamante dell'API: kms:Encrypt sulla AWS KMS chiave. È necessaria questa autorizzazione per crittografare il valore prima di archiviarlo.

• Ruolo di esecuzione di Canary: kms:Decrypt sulla AWS KMS chiave. La funzione Lambda di Canary necessita di questa autorizzazione per decrittografare il valore in fase di esecuzione.

Di seguito è riportato un esempio di policy IAM da allegare al ruolo di esecuzione di 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"
  }
]
}

Decifrare i valori nel tuo script canary

Per utilizzare una variabile di ambiente crittografata nel tuo script canary, decriptala in fase di esecuzione. L' Node.js esempio seguente mostra come decrittografare una variabile di ambiente:

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

Integrare il tuo canarino con altri AWS services

Puoi utilizzare la libreria AWS SDK del tuo canarino per integrarti con altri servizi. AWS

Per farlo, aggiungi il seguente codice al tuo canarino. In questi esempi, il canarino si integra con. AWS Secrets Manager

• Importa l'SDK. AWS

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

• Crea un client per il AWS servizio con cui ti stai integrando.

  const secretsManager = new AWS.SecretsManager();

• Utilizzare il client per effettuare chiamate API a tale servizio.

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

Il seguente frammento di codice di script Canary mostra come integrarsi con Secrets Manager in modo più dettagliato.

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

Forzare il canary a utilizzare un indirizzo IP statico

Puoi configurare un canary in modo che utilizzi un indirizzo IP statico.

Per forzare un canary a utilizzare un indirizzo IP statico

1. Crea un nuovo VPC. Per ulteriori informazioni, consulta Utilizzo del DNS con il tuo VPC.

2. Crea un nuovo gateway Internet. Per ulteriori informazioni, consulta la pagina relativa all'Aggiunta di un gateway Internet al VPC.

3. Crea una sottorete pubblica all'interno del tuo nuovo VPC.

4. Aggiungi una nuova tabella di routing al VPC.

5. Aggiungi un percorso nella nuova tabella delle rotte che va dal gateway 0.0.0.0/0 Internet.

6. Associa la nuova tabella di routing alla sottorete pubblica.

7. Crea un indirizzo IP elastico. Per ulteriori informazioni, consulta Indirizzi IP elastici.

8. Crea un nuovo gateway NAT e assegnalo alla sottorete pubblica e all'indirizzo IP elastico.

9. Per creare una sottorete privata all'interno del VPC.

10. Aggiungi un percorso alla tabella di routing predefinita del VPC che va dal gateway 0.0.0.0/0 NAT.

11. Crea il tuo canary.