다중 검사 블루프린트 카나리 생성

Amazon CloudWatch Synthetics 다중 검사 블루프린트는 간단한 JSON 구성을 제공하여 Synthetics 카나리를 생성하는 데 도움이 됩니다. 최대 10가지 유형의 HTTP/DNS/SSL/TCP 검사를 단계에 기반한 순차적인 방식으로 번들링하여 비용을 절감할 수 있습니다. 각 검사에는 검사 결과에 대한 기본적인 확인을 제공하는 어설션이 포함됩니다.

다중 검사 카나리는 헤드리스 브라우저 없이 기본 검사만 실행하면 되는 간단한 사용 사례를 위해 고안된 것입니다. 더 복잡한 사용 사례의 경우 Amazon CloudWatch Synthetics에서 제공하는 다른 카나리 유형을 검토하세요.

사전 조건

제한 사항

패키징 구조, JSON 스키마, 구성 설정

카나리에 사용할 JSON 검사 구성의 이름은 blueprint-config.json이어야 합니다. 구성은 스키마를 따르고 Node.js 다중 검사 블루프린트에 대한 JSON 구성 작성의 지침을 따라야 합니다.

blueprint-config.json을 ZIP 파일로 압축한 후 아래의 생성 워크플로 중 하나에 제공합니다. synthetics.json 구성이 있는 경우, 이 구성도 동일한 ZIP 파일에 압축됩니다. 다음은 multi-checks.zip이라는 zip 파일의 예제입니다.

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

AWS Management Console에서 다중 검사 카나리 생성

AWS Synthetics API를 사용하여 다중 검사 카나리 생성

CreateCanary API를 사용하고, Code 파라미터 내에서 Handler 대신 필드/값 BlueprintTypes="multi-checks"를 입력합니다. BlueprintTypes 및 Handler를 모두 지정하면 ValidationException이 표시됩니다. 제공된 런타임 버전은 syn-nodejs-3.0 이상이어야 합니다.

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" \
    ...
    

CloudFormation에서 다중 검사 카나리 생성

다중 검사 카나리용 CloudFormation 템플릿의 Code 파라미터 내에서 Handler 대신 필드/값 BlueprintTypes="multi-checks"를 제공합니다. BlueprintTypes 및 Handler를 모두 지정하면 ValidationException이 표시됩니다. 제공된 런타임 버전은 syn-nodejs-3.0 or later이어야 합니다.

템플릿 예제:

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"]
      ...
    

인증 구성

카나리가 인증된 엔드포인트에 HTTP 요청을 할 경우 기본, API 키, OAuth 클라이언트 자격 증명, SigV4라는 4가지 인증 유형 중 하나를 사용하도록 블루프린트 카나리의 단계를 구성할 수 있습니다. 요청 헤더를 직접 설정하는 대신 블루프린트 정의에서 인증 유형을 지정할 수 있으며, Synthetics는 지정된 인증 유형에 따라 HTTP 요청의 구성 요소를 제공된 인증 정보로 채웁니다.

인증 섹션을 사용하여 블루프린트 단계에서 인증 유형을 지정합니다. 사용할 인증 체계, 선택한 인증 체계에 필요한 속성을 지정하면 Synthetics에서는 제공된 정보를 사용하여 HTTP 요청에 대한 인증 헤더를 구성합니다.

보안 암호(예: 암호 또는 API 키)를 일반 텍스트로 저장하는 것은 보안 문제이므로, Synthetics에서는 AWS Secrets Manager와의 통합을 지원합니다. Synthetics 블루프린트 카나리에서 HTTP 요청을 인증하려는 경우 인증 정보를 저장하는 보안 암호를 참조할 수 있으며, Synthetics에서는 보안 암호를 검색한 후 이를 카나리에서 캐시 처리합니다. 이러한 접근 방식을 활용하면 보안 암호를 블루프린트 구성에 일반 텍스트로 지정하지 않고 안전하게 저장하면서, Synthetics에 보안 암호를 제공할 수 있습니다.

AWS Secrets Manager에 대한 자세한 내용은 AWS Secrets Manager란 무엇입니까?를 참조하세요.

기본 인증

Synthetics에서는 RFC 7617에 정의된 기본 HTTP 인증 체계를 구현합니다. 이 프로세스는 다음과 같이 작동합니다.

예를 들어 사용자 에이전트가 사용자 ID 'Aladdin', 암호 'open sesame'를 전송하려는 경우, Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 헤더 필드가 사용됩니다.

구성 예제:

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

API 키 인증

HTTP 요청을 인증하기 위한 API 키를 제공할 수 있습니다. API 키 인증을 사용하면 제공된 API 키가 'X-API-Key' HTTP 헤더에 입력됩니다. 이 헤더 이외의 헤더에서 API 키 헤더를 찾는 사용자 지정 리소스가 있을 경우, 사용자는 다른 헤더 이름을 지정하여 Synthetics가 API 키를 입력하도록 선택할 수 있습니다.

구성 예제:

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

SigV4 인증

AWS SigV4(Signature Version 4)는 AWS API 요청에 인증 정보를 추가하기 위한 AWS 서명 프로토콜입니다. SigV4 인증 요청을 하려면 요청할 리전 및 서비스를 지정하고, 이 SigV4 요청을 할 때 카나리가 수임할 IAM 역할을 식별하는 ARN(AWS 리소스 이름)을 지정해야 합니다. Synthetics에서는 roleArn에 제공된 IAM 역할을 수임하며, 이를 사용하여 AWS API 요청을 인증합니다.

구성 예제:

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

SigV4 고려 사항

Synthetics가 SigV4 인증 섹션에서 제공한 역할을 수임하려면, 제공된 roleArn을 카나리가 수임할 수 있도록 해당 역할에 연결된 신뢰 정책을 구성해야 합니다. 신뢰해야 하는 AWS 보안 주체는 카나리가 AWS STS를 통해 수임한 역할입니다. 이는 aws:sts::{account_running_the_canary}:assumed-role/<canary_name>/<assumed_role_name>arn: 형식을 사용합니다.

예를 들어 계정 0123456789012에서 실행 중인 카나리가 test-카나리라는 이름이고 카나리-assume-role이라는 역할을 수임한 경우, 신뢰 정책에 이 문을 포함해야 해당 카나리가 SigV4 인증을 위한 roleArn을 올바르게 수임할 수 있습니다.

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

OAuth 클라이언트 자격 증명

Synthetics에서는 RFC 6479 섹션 4.4에 정의된 OAuth 클라이언트 자격 증명 권한 부여 유형을 구현합니다. OAuth 토큰 엔드포인트에서 발급한 소유자 토큰으로 인증된 엔드포인트에 HTTP 요청을 하려는 경우, Synthetics에서는 소유자 토큰을 자동으로 요청하고 관리할 수 있습니다. OAuth 체계를 사용하는 경우 Synthetics에서는 다음 단계를 수행합니다.

구성 예제:

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

OAuth 고려 사항

401 또는 407 응답이 반환되면 Synthetics에서는 OAuth 토큰을 새로 고칩니다.

AWS Secrets Manager 통합

보안 암호 값(예: 암호 또는 API 키)을 일반 텍스트로 저장하는 것을 방지하기 위해 Synthetics에서는 AWS Secrets Manager와 통합할 수 있는 기능을 제공합니다. 블루프린트 구성의 전체 보안 암호 값을 ${aws_SECRET:<secret_name>} 형식으로 참조하거나, 특정 키 ${aws_SECRET:<secret_name>:<secret_key>}를 참조할 수 있습니다.

예를 들어 login/basic-auth-credentials라는 보안 암호가 있는 경우, 다음과 같은 JSON 구조의 사용자 이름과 암호가 저장됩니다.

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

블루프린트 구성의 사용자 이름과 암호를 다음과 같이 참조할 수 있으며, Synthetics에서는 보안 암호 값 검색 및 키 사용을 처리하여 요청을 인증합니다.

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

Synthetics가 지정된 보안 암호를 검색하도록 허용하려면 카나리가 수임한 역할 ARN에 secretsManager:GetSecretValue 권한이 있어야 합니다. AWS 관리형 키 AWS/secretsmanager 대신 고객 관리형 키를 사용하여 보안 암호를 암호화할 경우, 해당 키에 대한 kms:Decrypt 권한도 필요합니다.

권한 예제:

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

문제 해결

일반적인 문제 해결 실패

다중 검사 블루프린트의 기본 코드는 Typescript로 작성됩니다. 일반적인 실패에 대한 내용은 카나리 문제 해결 페이지 실패한 카나리 문제 해결을 참조하세요.

JSON 검사 구성 구문 오류

카나리의 JSON 검사 구성과 관련된 구문 오류가 있는 경우, 카나리 생성을 시도하면 AWS Management Console에서 실패 이유가 표시됩니다. API 또는 CloudFormation을 사용하여 카나리를 생성할 경우에는 카나리를 처음 실행하면 실패한 것으로 표시됩니다. 다중 검사 카나리에는 안전한 카나리 업데이트 워크플로를 사용하는 것이 좋습니다. 자세한 내용은 안전한 카나리 업데이트 수행을 참조하세요.

네트워킹 또는 제한 시간 실패

제한 시간, 네트워크 연결 실패(예: ENOTFOUND, ECONNRESET)와 관련하여 간헐적이거나 일관된 실패가 발생할 경우, DEBUG 로그를 켜서 다음 실행 시 검사가 실패하는 이유에 대한 추가 세부 정보를 확인하는 것이 좋습니다. 이렇게 하려면 환경 변수 CW_SYNTHETICS_LOG_LEVEL: "DEBUG"를 제공합니다.

디버그할 수 없는 실패가 지속될 경우 AWS Support에 문의하거나, CloudWatch Synthetics에서 제공하는 다른 카나리 유형 중에서 해당 사용 사례에 더 알맞은 유형이 있는지 확인하는 것이 좋습니다.