Recursos comuns do canário

É possível utilizar os seguintes recursos com todos os runtimes do canário.

Variáveis de ambiente

É possível usar variáveis de ambiente ao criar canários. Você pode escrever um único script de canário e utilizá-lo com valores diferentes para criar rapidamente vários canários para uma tarefa semelhante.

Por exemplo, suponha que sua organização tenha endpoints como prod, dev e pre-release para diferentes estágios de desenvolvimento de software. Você deve criar canários para testar cada endpoint. É possível escrever um único script de canário que testa seu software. Então, especifique valores de variáveis de ambiente de endpoint diferentes ao criar cada um dos três canários. Ao criar um canário, especifique o script e os valores de variáveis de ambiente.

Os nomes das variáveis de ambiente podem conter letras, números e o caractere de sublinhado. Devem começar com uma letra e ter pelo menos dois caracteres. O tamanho total das variáveis de ambiente não pode exceder 4 KB. Você não pode especificar nenhuma variável de ambiente reservada do Lambda como os nomes de suas variáveis de ambiente. Para obter mais informações sobre variáveis de ambiente reservadas, consulte Variáveis de ambiente do runtime.

O exemplo de script a seguir usa duas variáveis de ambiente. Esse script é para um canário que verifica se uma página da Web está disponível. Utiliza variáveis de ambiente para parametrizar tanto a URL que ele verifica como o nível de logs do CloudWatch Synthetics que ele usa.

Os trechos mostrados a seguir fazem parte do script completo mostrado abaixo.

A função a seguir define LogLevel para o valor da variável de ambiente LOG_LEVEL.

 synthetics.setLogLevel(process.env.LOG_LEVEL);

Essa função define URL para o valor da variável de ambiente URL.

const URL = process.env.URL;

O script completo mostrado a seguir demonstra as duas variáveis de ambiente. Ao criar um canário usando esse script, especifique os valores a serem usados para as variáveis de 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();
};

Aprovar variáveis de ambiente para seu script

Para transmitir variáveis de ambiente para o script ao criar um canário no console, especifique as chaves e os valores das variáveis de ambiente na seção Environment variables (Variáveis de ambiente) no console. Para obter mais informações, consulte Criar um canário.

Para transmitir variáveis de ambiente pela API ou pela AWS CLI, use o parâmetro EnvironmentVariables na seção RunConfig. O exemplo a seguir é um comando AWS CLI que cria um canário que usa duas variáveis de ambiente com chaves de Environment e 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"
}'

Como criptografar variáveis de ambiente em repouso com uma chave gerenciada pelo cliente

Por padrão, uma chave de propriedade da AWS criptografa variáveis de ambiente do canário em repouso. É possível especificar uma chave AWS KMS gerenciada pelo cliente para criptografar as variáveis de ambiente do canário em repouso. Com uma chave gerenciada pelo cliente, você tem controle total sobre a criptografia de dados de configuração confidenciais. As seções seguintes descrevem os requisitos, etapas de configuração e permissões para usar uma chave gerenciada pelo cliente.

Requisitos

Antes de configurar uma chave gerenciada pelo cliente, verifique se os requisitos a seguir estão sendo atendidos:

Configuração de uma chave gerenciada pelo cliente

Você pode configurar uma chave gerenciada pelo cliente ao criar ou atualizar um canário. Os procedimentos mostrados a seguir mostram como configurar a criptografia usando o console do Amazon CloudWatch e a API Synthetics.

Configure a criptografia no console

Para criar ou editar um canário no console do Amazon CloudWatch, expanda a seção Variáveis de ambiente. Em Configuração de criptografia em repouso, escolha Usar uma chave gerenciada pelo cliente e, em seguida, escolha ou especifique o ARN da sua chave AWS KMS.

Configurar a criptografia usando a API

Ao chamar CreateCanary ou UpdateCanary, especifique o parâmetro KmsKeyArn com o ARN da chave gerenciada pelo cliente. Para reverter para a chave gerenciada pela AWS, defina KmsKeyArn como uma string vazia.

Exemplo: solicitação CreateCanary com uma chave gerenciada pelo 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"
  }
}
}

Permissões necessárias para criptografia em repouso

Se você criar ou atualizar o canário, deverá ter as seguintes permissões na chave AWS KMS:

A função de execução do canário não requer permissões AWS KMS para criptografia em repouso. O Lambda utiliza a concessão para lidar com criptografia e descriptografia.

Canários multirregionais

Para canários multirregionais, cada local de réplica pode ter sua própria chave AWS KMS. Especifique KmsKeyArn no parâmetro AddReplicaLocations ao criar ou atualizar um canário. A chave deve ser criada na mesma Região da réplica.

Como criptografar variáveis de ambiente em trânsito

Além da criptografia em repouso, é possível criptografar valores individuais de variáveis de ambiente antes que o CloudWatch Synthetics os armazene. O CloudWatch Synthetics chama isso de criptografia em trânsito. Quando você criptografa um valor em trânsito, o console substitui o valor de texto simples por um texto cifrado codificado em base64 que somente seu canário pode descriptografar em runtime.

Como funciona a criptografia em trânsito

Quando você opta por criptografar um valor de variável de ambiente em trânsito:

Permissões necessárias para criptografia em trânsito

Você precisa das seguintes permissões para a criptografia em trânsito:

A seguir está um exemplo de política do IAM a ser anexada ao perfil de execução do canário:

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

Como descriptografar valores no script do canário

Para usar uma variável de ambiente criptografada no script do canário, descriptografe-a em runtime. O exemplo do Node.js mostrado a seguir mostra como descriptografar uma variável de 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');

Integrar o canário a outros produtos da AWS

Você pode usar a biblioteca do SDK da AWS em seu canário para integrar-se a outros serviços da AWS.

Para fazer isso, adicione o código a seguir ao canário. Nesses exemplos, o canário se integra com o AWS Secrets Manager.

O trecho de código de script do canário a seguir mostra como integrar ao Secrets Manager com mais detalhes.

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

Forçar seu canário a usar um endereço IP estático

É possível configurar um canário para que ele use um endereço IP estático.