Criar um canário com esquema de múltiplas verificações

O esquema de múltiplas verificações do Amazon CloudWatch Synthetics ajuda a criar um canário do Synthetics por meio de uma configuração JSON simples. Você pode economizar custos empacotando até 10 tipos diferentes de verificações HTTP/DNS/SSL/TCP feitas em etapas sequenciais. Cada verificação inclui asserções que fornecem uma validação básica em relação ao resultado da verificação.

Os canários de múltiplas verificações são projetados para casos de uso simples que exigem apenas verificações básicas sem usar um navegador sem periféricos/sem interface gráfica. Para casos de uso mais complexos, revise os outros tipos de canários que o Amazon CloudWatch Synthetics oferece.

Pré-requisitos

Limitações

Estrutura de empacotamento, esquema JSON e definições de configuração

A configuração do JSON Checks que será usada para o canário deve será denominada blueprint-config.json. A configuração deve seguir o esquema e as instruções em Escrever uma configuração JSON para o esquema de múltiplas verificações do Node.js.

Compacte o blueprint-config.json em um arquivo ZIP e forneça-o em um dos seguintes fluxos de trabalho de criação. Quando existe uma configuração synthetics.json, ela também é compactada no mesmo arquivo ZIP. O exemplo a seguir é de arquivo denominado multi-checks.zip.

multi-checks.zip
├── blueprint-config.json
└── synthetics.json
    

Criar um canário de múltiplas verificações no Console de gerenciamento da AWS

Criar um canário de múltiplas verificações usando as APIs do AWS Synthetics

Use a API CreateCanary e, no parâmetro Code, forneça o campo/valor BlueprintTypes="multi-checks" em vez de Handler. Quando ambos BlueprintTypes e Handler são especificados, uma ValidationException é exibida. A versão do runtime deve ser syn-nodejs-3.0 or later.

aws synthetics create-canary \
    --name my-multi-check-canary \
    --code ZipFile="ZIP_BLOB",BlueprintTypes="multi-checks" \
    --runtime-version syn-nodejs-3.0 \
    ...

// Or if you wanted to use S3 to provide your code.

aws synthetics create-canary \
    --name my-multi-check-canary \
    --code S3Bucket="my-code-bucket",S3Key="my-zip-code-key",BlueprintTypes="multi-checks" \
    ...
    

Criar um canário de múltiplas verificações no CloudFormation

No modelo CloudFormation de um canário de múltiplas verificações, no Code parâmetro, forneça o campo/valor BlueprintTypes="multi-checks" em vez de Handler. Quando ambos BlueprintTypes e Handler são especificados, uma ValidationException é exibida. A versão do runtime deve ser syn-nodejs-3.0 or later.

Um exemplo de modelo:

SyntheticsCanary:
    Type: 'AWS::Synthetics::Canary'
    Properties:
      Name: MyCanary
      RuntimeVersion: syn-nodejs-3.0
      Schedule: {Expression: 'rate(5 minutes)', DurationInSeconds: 3600}
      ...
      Code:
        S3Bucket: "my-code-bucket"
        S3Key: "my-zip-code-key"
        BlueprintTypes: ["multi-checks"]
      ...
    

Configuração da autenticação

Quando o canário faz solicitações HTTP a um endpoint autenticado, você pode configurar as etapas do canário do esquema para usar um dos quatro tipos de autenticação: Basic, API Key, OAuth Client Credentials e SigV4. Em vez de configurar você mesmo os cabeçalhos de solicitação, é possível especificar um tipo de autenticação na definição do esquema, e o Synthetics seguirá o tipo de autenticação especificado para preencher os componentes da solicitação HTTP com as informações de autenticação fornecidas.

Você especifica um tipo de autenticação na etapa do esquema com a seção Autenticação. Você especifica o esquema de autenticação que quer usar, as propriedades requeridas para o esquema de autenticação escolhido, e o Synthetics usa as informações fornecidas para criar um cabeçalho de autenticação para a solicitação HTTP.

Como manter segredos (como senhas ou chaves de API) armazenados em texto simples é um problema de segurança, o Synthetics é compatível com a integração com o AWS Secrets Manager. Quando quiser autenticar uma solicitação HTTP em um canário de esquema do Synthetics, consulte o segredo que contém suas informações de autenticação, e o Synthetics recuperará o segredo e o colocará em cache no canário. Essa abordagem fornece segredos ao Synthetics e, ao mesmo tempo, os mantém armazenados com segurança, sem especificá-los em texto simples na configuração do esquema.

Para obter mais informações sobre o AWS Secrets Manager, consulte O que é AWS Secrets Manager?

Autenticação básica

O Synthetics implementa o esquema de autenticação Basic HTTP definido na RFC 7617. O processo funciona da seguinte maneira:

Por exemplo, se o agente do usuário quiser enviar o ID de usuário “Aladin” e a senha “abra-te sésamo”, ele usará o seguinte campo de cabeçalho: Autorização: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Exemplo de configuração:

"Authentication": {
    "type": "BASIC",
    "username": MY_USERNAME, // Required
    "password": MY_PASSWORD // Required
}
      

Autenticação de chave de API

Você pode fornecer uma chave de API para autenticar as solicitações HTTP. Quando você usa a autenticação de chave de API, a chave de API fornecida é colocada no cabeçalho HTTP “X-API-Key”. Se você tiver um recurso personalizado que procura cabeçalhos de chave de API em outro cabeçalho, terá a opção de especificar outro nome de cabeçalho no qual o Synthetics deverá colocar a chave de API.

Exemplo de configuração:

"Authentication": {
    "type": "API_KEY",
    "apiKey": S0A1M2P3L4E5, // Required
    "header": X-Specific-Header // Optional, defaults to "X-API-Key"
}
      

Autenticação SigV4

AWS SigV4 (Signature Version 4) é o protocolo de assinatura da AWS para adição de informações de autenticação às solicitações de API da AWS. Para fazer uma solicitação autenticada por SigV4, especifique a região e o serviço aos quais as solicitações são feitas, bem como um ARN (nome do recurso da AWS) do perfil do IAM que você deseja que o canário assuma ao fazer essa solicitação do SigV4. O Synthetics assume o perfil do IAM fornecido no roleArn e usa-o para autenticar a solicitação de API da AWS.

Exemplo de configuração:

"Authentication": {
    "type": "SIGV4",
    "region": us-west-2, // Required
    "service": s3, // Required
    "roleArn": arn:AWS:iam:12345678912:role/SampleRole // Required
}
      

Considerações sobre a autenticação SigV4

Para que o Synthetics assuma o perfil fornecido na seção de autenticação do SigV4, a política de confiança anexada a esse perfil deve ser configurada para permitir que o canário assuma o roleArn fornecido. A entidade principal da AWS em que você precisa confiar é o perfil que o canário assumiu por meio do AWS STS. Ele assume o formato aws:sts::{account_running_the_canary}:assumed-role/<canary_name>/<assumed_role_name>arn:.

Por exemplo, se você tiver um canário em execução na conta 0123456789012, denominado test-canary, e o perfil que ele assumiu for denominado canary-assume-role, a política de confiança precisará incluir essa instrução para que o canário assuma corretamente o roleArn para a autenticação SigV4:

{
    "Effect": "Allow",
    "Principal": {
        "AWS": "arn:AWS:sts::123456789012:assumed-role/test-canary/"
    },
    "Action": "sts:AssumeRole"
}
        

Credenciais de cliente OAuth

O Synthetics implementa o tipo de concessão OAuth Client Credentials conforme definido na seção 4.4 da RFC 6479. Se quiser fazer uma solicitação HTTP a um endpoint autenticado com um token ao portador emitido por um endpoint de token OAuth, o Synthetics pode solicitar e gerenciar um token de portador para você. Quando você usa o esquema OAuth, o Synthetics executa as seguintes etapas:

Exemplo de configuração:

"Authentication": {
    "type": "OAUTH_CLIENT_CREDENTIALS",
    "tokenUrl": ..., // Required
    "clientId": ..., // Required
    "clientSecret": ..., // Required
    "scope": ..., // Optional
    "audience": ..., // Optional
    "resource": ..., // Optional
}
      

Considerações sobre o OAuth

O Synthetics atualiza os tokens OAuth quando uma resposta 401 ou 407 é retornada.

AWS Secrets ManagerIntegração do

Para evitar o armazenamento de valores secretos (como senhas ou chaves de API) em texto simples, o Synthetics fornece uma integração com o AWS Secrets Manager. Você pode referenciar um valor secreto inteiro na configuração do esquema com o formato ${aws_SECRET:<secret_name>} ou referenciar uma chave ${aws_SECRET:<secret_name>:<secret_key>} específica.

Por exemplo, se você tiver um segredo denominado login/basic-auth-credentials, o armazenamento de um nome de usuário e senha com a seguinte estrutura JSON:

{
    "username": "Aladdin",
    "password": "open sesame"
}
      

Você pode referenciar o nome de usuário e senha na configuração do esquema do seguinte modo, e o Synthetics recuperará o valor do segredo e usará suas chaves para autenticar a solicitação:

"Authentication": {
    "type": "BASIC",
    "username": ${AWS_SECRET:login/basic-auth-credentials:username},
    "password": ${AWS_SECRET:login/basic-auth-credentials:password}
}
      

Para permitir que o Synthetics recupere o segredo especificado, o ARN do perfil assumido pelo canário precisa ter as permissões secretsManager:GetSecretValue. Se o segredo for criptografado com uma chave gerenciada pelo cliente em vez da chave gerenciada pela AWS AWS/secretsmanager, o perfil também precisará das permissões kms:Decrypt para essa chave.

Exemplo de permissões:

{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "secretsmanager:GetSecretValue",
            "Resource": "arn:AWS:secretsmanager:us-east-1:123456789012:secret:secretName-AbCdEf"
        },
        {
            "Effect": "Allow",
            "Action": "kms:Decrypt",
            "Resource": "arn:AWS:kms:us-east-1:123456789012:key/key-id"
        }
    ]
}
      

Solução de problemas

Falhas comuns da solução de problemas

O código subjacente do esquema de múltiplas verificações é escrito em Typescript. Consulte a página de solução de problemas do canário para ver as falhas comuns: Solução de problemas de um canário com falha.

Erros de sintaxe de configuração de verificação JSON

Quando houver algum erro de sintaxe relacionado à configuração da verificação JSON do canário, o Console de gerenciamento da AWS apresentará um motivo de falha quando você tentar criar o canário. Se você criar um canário usando uma API ou o CloudFormation, verá a falha quando o canário for executado a primeira vez. Para um canário de múltiplas verificações, é recomendável usar o fluxo de trabalho de atualizações seguras do canário. Para saber mais, consulte Execução de atualizações seguras para o canário.

Falhas de rede ou de tempo limite esgotado

Para falhas intermitentes ou consistentes relacionadas a tempos limite esgotados, falhas de conexão de rede (por exemplo, ENOTFOUND, ECONNRESET), considere ativar os logs DEBUG para que a próxima execução forneça mais detalhes sobre por que as verificações estão apresentando falhas. Para isso, forneça a variável de ambiente CW_SYNTHETICS_LOG_LEVEL: “DEBUG”.

Se ainda houver falhas que você não consegue depurar, considere entrar em contato com o AWS Support ou verificar se algum dos outros tipos de canário fornecidos pelo CloudWatch Synthetics é mais adequado ao seu caso de uso.