# canary 블루프린트 사용 이 섹션에서는 각 canary 블루프린트 및 각 블루프린트가 가장 적합한 작업에 대해 자세히 설명합니다. 다음과 같은 canary 유형에 대해 블루프린트가 제공됩니다. **Topics** + [하트비트 모니터링](#CloudWatch_Synthetics_Canaries_Blueprints_Heartbeat) + [API canary](#CloudWatch_Synthetics_Canaries_Blueprints_API) + [잘못된 링크 검사기](#CloudWatch_Synthetics_Canaries_Blueprints_Broken_Links) + [시각적 모니터링 블루프린트](#CloudWatch_Synthetics_Canaries_Blueprints_VisualTesting) + [canary 레코더](#CloudWatch_Synthetics_Canaries_Blueprints_Recorder) + [GUI 워크플로 빌더](#CloudWatch_Synthetics_Canaries_Blueprints_GUI_Workflow) + [다중 검사 블루프린트](#CloudWatch_Synthetics_Canaries_Blueprints_Multichecks_Blueprint) + [다중 검사 블루프린트 카나리 생성](CloudWatch_Synthetics_Canaries_MultiCheck_Blueprint.md) 블루프린트를 사용하여 canary를 생성할 때 CloudWatch 콘솔에서 필드를 작성하면 페이지의 [**스크립트 편집기(Script editor)**] 영역에 생성 중인 canary가 Node.js 스크립트로 표시됩니다. 이 영역에서 canary를 편집하여 추가로 사용자 지정할 수도 있습니다. ## 하트비트 모니터링 하트비트 스크립트는 지정된 URL을 로드하고 페이지의 스크린샷과 HTTP 아카이브 파일(HAR 파일)을 저장합니다. 또한 액세스한 URL의 로그도 저장합니다. HAR 파일을 사용하여 웹페이지에 대한 자세한 성능 데이터를 볼 수 있습니다. 웹 요청 목록을 분석하고 항목에 대한 로드 시간과 같은 성능 문제를 파악할 수 있습니다. canary에서 `syn-nodejs-puppeteer-3.1` 이상의 런타임 버전을 사용하는 경우 하트비트 모니터링 블루프린트를 사용하여 여러 URL을 모니터링하고 canary 실행 보고서의 단계 요약에서 각 URL의 상태, 지속 시간, 관련 스크린샷, 실패 원인을 확인할 수 있습니다. ## API canary API canary는 REST API의 기본 읽기 및 쓰기 기능을 테스트할 수 있습니다. REST는 *representational state transfer*의 약어로 개발자가 API를 생성할 때 따르는 일련의 규칙입니다. 이러한 규칙 중 하나에는 특정 URL에 대한 링크가 데이터 조각을 반환해야 한다고 명시되어 있습니다. canary는 어느 API와도 함께 작동하며 모든 유형의 기능을 테스트할 수 있습니다. 각 canary는 여러 API를 호출할 수 있습니다. 런타임 버전 `syn-nodejs-2.2` 이상을 사용하는 canary에서 API canary 블루프린트는 API를 HTTP 단계로 모니터링하는 다단계 canary를 지원합니다. 단일 canary에서 여러 API를 테스트할 수 있습니다. 각 단계는 서로 다른 URL에 액세스하고 서로 다른 헤더를 사용하며 헤더 및 응답 본문을 캡처할지 여부에 대해 서로 다른 규칙을 사용할 수 있는 별도의 요청입니다. 헤더 및 응답 본문을 캡처하지 않음으로써 민감한 데이터가 기록되지 않도록 방지할 수 있습니다. API canary의 각 요청은 다음 정보로 구성됩니다. + *엔드포인트*: 사용자가 요청하는 URL입니다. + *메서드*: 서버로 전송되는 요청의 유형입니다. REST API는 GET(읽기), POST(쓰기), PUT(업데이트), PATCH(업데이트) 및 DELETE(삭제) 작업을 지원합니다. + *헤더*: 클라이언트와 서버 모두에 정보를 제공합니다. 이는 인증 및 본문 내용에 대한 정보를 제공하는 데 사용됩니다. 유효한 헤더 목록은 [HTTP 헤더](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)를 참조하세요. + *데이터*(또는 *본문*): 서버에 전송할 정보가 포함되어 있습니다. 이는 POST, PUT, PATCH 또는 DELETE 요청에만 사용됩니다. **참고** API 카나리 블루프린트는 Playwright 런타임에서 지원되지 않습니다. API canary 블루프린트는 GET 및 POST 메서드를 지원합니다. 이 블루프린트를 사용할 때는 헤더를 지정해야 합니다. 예를 들어 **Authorization**을 **키**로 지정하고 필요한 인증 데이터를 해당 키의 **값**으로 지정할 수 있습니다. POST 요청을 테스트하는 경우 **데이터** 필드에 게시할 콘텐츠도 지정합니다. **API Gateway와의 통합** API 블루프린트는 Amazon API Gateway와 통합됩니다. 이를 통해 API Gateway API를 선택하고 canary와 동일한 AWS 계정 및 리전에서 스테이징하거나 교차 계정 및 교차 리전 API 모니터링을 위해 API Gateway에서 Swagger 템플릿을 업로드할 수 있습니다. 그런 다음, Scratch에서 나머지 세부 정보를 입력하는 대신 콘솔에서 선택하여 canary를 생성할 수 있습니다. API Gateway에 대한 자세한 내용은 [Amazon API Gateway란?](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html) 단원을 참조하세요. **프라이빗 API 사용** Amazon API Gateway에서 프라이빗 API를 사용하는 canary를 생성할 수 있습니다. 자세한 내용은 [Amazon API Gateway에서 프라이빗 API 생성](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html)을 참조하세요. ## 잘못된 링크 검사기 잘못된 링크 검사기는 `document.getElementsByTagName('a')`을 사용하여 테스트 중인 URL 내부의 모든 링크를 수집합니다. 지정한 링크 수까지만 테스트하며, URL 자체가 첫 번째 링크로 계산됩니다. 예를 들어 5개의 링크가 포함된 페이지의 모든 링크를 검사하려면 canary가 6개의 링크를 따르도록 지정해야 합니다. `syn-nodejs-2.0-beta` 런타임 이상을 사용하여 생성된 잘못된 링크 검사기 canary는 다음과 같은 추가 기능을 지원합니다. + 확인된 링크, 상태 코드, 실패 원인(있는 경우), 소스 및 대상 페이지 스크린샷이 포함된 보고서를 제공합니다. + canary 결과를 살펴볼 때 잘못된 링크만 표시하도록 필터링한 다음, 실패 원인을 기반으로 링크를 수정할 수 있습니다. + 이 버전은 각 링크에 대해 주석이 달린 소스 페이지 스크린샷을 캡처하고 링크가 발견된 앵커를 강조 표시합니다. 숨겨진 구성 요소에는 주석이 달려 있지 않습니다. + 소스 페이지와 대상 페이지 모두, 소스 페이지만 또는 대상 페이지만 스크린샷을 캡처하도록 이 버전을 구성할 수 있습니다. + 이 버전은 첫 페이지에서 더 많은 링크를 스크레이프한 경우에도 첫 번째 잘못된 링크 이후에 canary 스크립트가 중지되는 이전 버전의 문제를 수정합니다. **참고** 끊어진 링크 검사기 블루프린트는 Playwright 런타임에서 지원되지 않습니다. `syn-1.0`을 사용하는 기존 카나리를 업데이트하여 새 런타임을 사용하려면 카나리를 삭제하고 다시 생성해야 합니다. 기존 canary를 새 런타임으로 업데이트해도 이러한 기능을 사용할 수는 없습니다. 잘못된 링크 검사기 canary는 다음과 같은 유형의 링크 오류를 감지합니다. + 404 페이지를 찾을 수 없음 + 잘못된 호스트 이름 + 잘못된 URL. 예를 들어 URL에 대괄호가 없거나 여분의 슬래시가 있거나 잘못된 프로토콜을 사용합니다. + 잘못된 HTTP 응답 코드 + 호스트 서버가 콘텐츠가 없고 응답 코드가 없는 빈 응답을 반환합니다. + HTTP 요청은 canary 실행 중에 지속적으로 시간 초과됩니다. + 호스트가 잘못 구성되었거나 사용 중이므로 계속 연결이 끊어집니다. ## 시각적 모니터링 블루프린트 시각적 모니터링 블루프린트에는 canary 실행 중에 생성한 스크린샷과 기준 canary 실행 중에 생성한 스크린샷을 비교하는 코드가 포함되어 있습니다. 두 스크린샷 간의 불일치가 임계 백분율을 초과하면 canary가 실패합니다. 시각적 모니터링은 **syn-puppeteer-node-3.2** 이상을 실행하는 canary에서 지원됩니다. 현재 Python 및 Selenium을 실행하거나, Playwright 런타임을 사용하는 카나리에서는 지원되지 않습니다. 시각적 모니터링 블루프린트에는 시각적 모니터링을 사용 설정하는 기본 블루프린트 canary 스크립트에 다음 코드 줄이 포함되어 있습니다. ``` syntheticsConfiguration.withVisualCompareWithBaseRun(true); ``` 이 줄을 스크립트에 추가한 후 canary가 처음 성공적으로 실행되면 해당 실행 중에 생성한 스크린샷을 비교를 위한 기준으로 사용합니다. 성공한 첫 번째 canary 실행 후 CloudWatch 콘솔을 사용하여 다음 중 하나를 수행하도록 canary를 편집할 수 있습니다. + canary의 다음 실행을 새 기준으로 설정합니다. + 현재 기준 스크린샷에 경계선을 그려서 시각적 비교 중에 무시할 스크린샷 영역을 지정합니다. + 스크린샷을 제거하여 시각적 모니터링에 사용되지 않도록 합니다. CloudWatch 콘솔을 사용하여 canary를 편집하는 방법에 대한 자세한 내용은 [canary 편집 또는 삭제](synthetics_canaries_deletion.md) 단원을 참조하세요. 또한 ` nextrun` 또는 `lastrun` 파라미터를 사용하거나 [UpdateCanary](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_UpdateCanary.html) API에서 canary 실행 ID를 지정하여 기준으로 사용되는 canary 실행을 변경할 수도 있습니다. 시각적 모니터링 청사진을 사용할 때 스크린샷을 생성할 URL을 입력하고 차이 임곗값을 백분율로 지정합니다. 기준 실행 후 해당 임곗값보다 큰 시각적 차이를 감지하는 canary의 향후 실행은 canary 실패를 트리거합니다. 기준 실행 후 canary를 편집하여 시각적 모니터링 중에 무시하려는 경계선을 기준 스크린샷에 ‘그릴’ 수도 있습니다. 시각적 모니터링 기능은 ImageMagick 오픈 소스 소프트웨어 도구 키트를 통해 제공됩니다. 자세한 내용은 [ImageMagick](https://imagemagick.org/index.php)을 참조하세요. ## canary 레코더 canary 레코더 블루프린트를 통해 CloudWatch Synthetics Recorder를 사용하여 웹 사이트에서의 클릭 및 입력 작업을 기록하고 동일한 단계를 따르는 canary를 생성하는 데 사용할 수 있는 Node.js 스크립트를 자동으로 생성할 수 있습니다. CloudWatch Synthetics Recorder는 Amazon에서 제공하는 Google Chrome 확장 프로그램입니다. 카나리 Recorder는 Playwright 런타임을 사용하는 카나리에서는 지원되지 않습니다. **크레딧**: CloudWatch Synthetics Recorder는 [헤드리스 레코더](https://github.com/checkly/headless-recorder)를 기반으로 합니다. 자세한 내용은 [Google Chrome용 CloudWatch Synthetics Recorder 사용](CloudWatch_Synthetics_Canaries_Recorder.md) 단원을 참조하세요. ## GUI 워크플로 빌더 GUI 워크플로 빌더 블루프린트는 웹 페이지에서 작업을 수행할 수 있는지 확인합니다. 예를 들어 웹 페이지에 로그인 양식이 있는 경우 canary는 사용자 및 암호 필드를 채우고 양식을 제출하여 웹 페이지가 올바르게 작동하는지 확인할 수 있습니다. 블루프린트를 사용하여 이 유형의 canary를 생성할 때 웹 페이지에서 canary가 수행할 작업을 지정합니다. 사용할 수 있는 작업은 다음과 같습니다. + **클릭** - 지정된 요소를 선택하고, 요소를 클릭하거나 선택하는 사용자를 시뮬레이션합니다. Node.js 스크립트에서 요소를 지정하려면 `[id=]` 또는 ` a[class=]`를 사용합니다. Python 스크립트에서 요소를 지정하려면 `xpath //*[@id=]` 또는 ` //*[@class=]`를 사용합니다. + **선택기 확인** - 지정된 요소가 웹 페이지에 있는지 확인합니다. 이 테스트는 이전 작업으로 인해 올바른 요소가 페이지를 채우는지 확인하는 데 유용합니다. Node.js 스크립트에서 확인할 요소를 지정하려면 `[id=]` 또는 ` a[class=]`를 사용합니다. Python 스크립트에서 확인할 요소를 지정하려면 `xpath //*[@id=]` 또는 `//*[class=]`를 사용합니다. + **텍스트 확인** - 지정된 문자열이 대상 요소 내에 포함되어 있는지 확인합니다. 이 테스트는 이전 작업으로 인해 올바른 텍스트가 표시되는지 확인하는 데 유용합니다. Node.js 스크립트에서 요소를 지정하려면 ` div[@id=]//h1`과 같은 형식을 사용합니다. 이 작업은 Puppeteer의 `waitForXPath` 함수를 사용하기 때문입니다. Python 스크립트에서 요소를 지정하려면 ` //*[@id=] ` 또는 //\$1[@class=] 같은 xpath 형식을 사용합니다. 이 작업은 Selenium의 `implicitly_wait` 함수를 사용하기 때문입니다. + **텍스트 입력** - 대상 요소에 지정된 텍스트를 작성합니다. Node.js 스크립트에서 확인할 요소를 지정하려면 `[id=]` 또는 ` a[class=]`를 사용합니다. Python 스크립트에서 확인할 요소를 지정하려면 `xpath //*[@id=]` 또는 `//*[@class=]`를 사용합니다. + **탐색과 함께 클릭** - 지정된 요소를 선택한 후 전체 페이지가 로드될 때까지 기다립니다. 이는 페이지를 다시 로드해야 할 때 가장 유용합니다. Node.js 스크립트에서 요소를 지정하려면 `[id=]` 또는 ` a[class=]`를 사용합니다. Python 스크립트에서 요소를 지정하려면 `xpath //*[@id=]` 또는 ` //*[@class=]`를 사용합니다. 예를 들어 다음 블루프린트는 Node.js를 사용합니다. 지정된 URL의 **firstButton**을 클릭하고, 예상 텍스트가 있는 예상 선택기가 나타나는지 확인하고, **이름(Name)** 필드에 `Test_Customer`라고 이름을 입력합니다. **로그인(Login)** 버튼을 클릭한 후 다음 페이지에서 **시작(Welcome)** 텍스트가 표시되는지 확인하여 로그인이 성공했는지 확인합니다. ![\[GUI 워크플로우 블루프린트에 대한 필드가 채워져 있는 콘솔의 canary 생성 페이지.\]](http://docs.aws.amazon.com/ko_kr/AmazonCloudWatch/latest/monitoring/images/canary_create_gui_workflow.PNG) 다음 런타임을 사용하는 GUI 워크플로 canary는 각 canary 실행에 대해 실행된 단계의 요약도 제공합니다. 각 단계와 관련된 스크린샷 및 오류 메시지를 사용하여 실패의 근본 원인을 찾을 수 있습니다. + `syn-nodejs-2.0` 이상 + `syn-python-selenium-1.0` 이상 ## 다중 검사 블루프린트 다중 검사 블루프린트는 카나리 생성을 간소화합니다. HTTP, DNS, SSL, TCP 검사 수행에 즉시 사용 가능한 기능을 제공하는 간단한 JSON 구성을 사용하여 비용을 절감합니다. 최대 10가지 검사를 구성할 수 있습니다. 각 검사를 순차적으로 실행되는 숫자 단계로 구성하여 카나리 흐름을 명확하게 이해할 수 있도록 합니다. 다중 검사 블루프린트는 다음을 지원합니다. + 기본 HTTP 요청, TCP 요청, DNS 레코드 검증, SSL 인증서 모니터링 + Secrets Manager와 통합된 Basic, API 키, OAuth, Sigv4 같은 HTTP 인증 방법 + 각 검사에 대한 어설션 자세한 내용은 [canary 생성](CloudWatch_Synthetics_Canaries_Create.md) 섹션을 참조하세요. # 다중 검사 블루프린트 카나리 생성 Amazon CloudWatch Synthetics 다중 검사 블루프린트는 간단한 JSON 구성을 제공하여 Synthetics 카나리를 생성하는 데 도움이 됩니다. 최대 10가지 유형의 HTTP/DNS/SSL/TCP 검사를 단계에 기반한 순차적인 방식으로 번들링하여 비용을 절감할 수 있습니다. 각 검사에는 검사 결과에 대한 기본적인 확인을 제공하는 어설션이 포함됩니다. 다중 검사 카나리는 헤드리스 브라우저 없이 기본 검사만 실행하면 되는 간단한 사용 사례를 위해 고안된 것입니다. 더 복잡한 사용 사례의 경우 Amazon CloudWatch Synthetics에서 제공하는 다른 카나리 유형을 검토하세요. **Topics** + [사전 조건](#CloudWatch_Synthetics_MultiCheck_Prerequisites) + [제한 사항](#CloudWatch_Synthetics_MultiCheck_Limitations) + [패키징 구조, JSON 스키마, 구성 설정](#CloudWatch_Synthetics_MultiCheck_Packaging) + [AWS Management Console에서 다중 검사 카나리 생성](#CloudWatch_Synthetics_MultiCheck_Console) + [AWS Synthetics API를 사용하여 다중 검사 카나리 생성](#CloudWatch_Synthetics_MultiCheck_API) + [CloudFormation에서 다중 검사 카나리 생성](#CloudWatch_Synthetics_MultiCheck_CloudFormation) + [인증 구성](#CloudWatch_Synthetics_MultiCheck_Authentication) + [문제 해결](#CloudWatch_Synthetics_MultiCheck_Troubleshooting) ## 사전 조건 + 다중 검사 카나리를 생성하려면 syn-nodejs-3.0\$1를 사용해야 합니다. + 인증 및 Secrets Manager 구성을 사용할 경우 카나리 [ExecutionRoleArn](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_CreateCanary.html)이 이러한 보안 암호에 액세스할 수 있는 권한을 허용하는지 확인해야 합니다. + Sigv4용 인증을 사용할 경우 카나리 [ExecutionRoleArn](https://docs.aws.amazon.com/AmazonSynthetics/latest/APIReference/API_CreateCanary.html)이 관련 역할에 액세스할 수 있는 권한을 허용하는지 확인해야 합니다. ## 제한 사항 + HTTP 응답 크기는 1MB를 초과할 수 없습니다. + 정의된 변수는 최대 10개입니다. + JSON RFC를 사용할 경우 Checks JSON에 중복 필드가 제공될 수도 있지만, 마지막 순차 필드만 사용됩니다. + AWS Management Console에서 다중 검사 카나리는 기본적으로 다중 검사 단계 지표를 표시하여 각 검사의 가용성을 쉽게 식별합니다. 검사가 제거된 경우에도 이 그래프는 지표가 최소 3시간 동안 활성 상태가 중지되지 않는 한 가용성 그래프에 검사가 계속 표시될 수 있습니다. ## 패키징 구조, JSON 스키마, 구성 설정 카나리에 사용할 JSON 검사 구성의 이름은 ` blueprint-config.json`이어야 합니다. 구성은 [스키마](https://github.com/aws-samples/synthetics-canary-local-debugging-sample/tree/main)를 따르고 [Node.js 다중 검사 블루프린트에 대한 JSON 구성 작성](CloudWatch_Synthetics_WritingCanary_Multichecks.md)의 지침을 따라야 합니다. `blueprint-config.json`을 ZIP 파일로 압축한 후 아래의 생성 워크플로 중 하나에 제공합니다. `synthetics.json` 구성이 있는 경우, 이 구성도 동일한 ZIP 파일에 압축됩니다. 다음은 `multi-checks.zip`이라는 zip 파일의 예제입니다. ``` multi-checks.zip ├── blueprint-config.json └── synthetics.json ``` ## AWS Management Console에서 다중 검사 카나리 생성 1. Amazon CloudWatch Synthetics 콘솔을 엽니다. 1. **Create Canary(canary 생성)**를 선택합니다. 1. **블루프린트 사용**에서 **다중 검사**를 선택합니다. **구성 검사** 아래에 **검사** 및 **카나리 구성**이라는 탭 2개가 표시됩니다. 1. 런타임 버전 **syn-nodejs-3.0** 이상을 선택합니다. 1. [Node.js 다중 검사 블루프린트에 대한 JSON 구성 작성](CloudWatch_Synthetics_WritingCanary_Multichecks.md)에 의거한 절차에 따라 수행하려는 검사를 설명합니다. 또는 콘솔에서 사용자가 빌드할 수 있는 기본 JSON 구성을 제공하기도 합니다. 1. **Create Canary(canary 생성)**를 선택합니다. ## 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란 무엇입니까?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)를 참조하세요. ### 기본 인증 Synthetics에서는 RFC 7617에 정의된 기본 HTTP 인증 체계를 구현합니다. 이 프로세스는 다음과 같이 작동합니다. + 사용자 이름과 암호 페어가 블루프린트 구성에서 제공됩니다. + 사용자 패스는 사용자 이름, 단일 콜론(":") 문자, 암호를 연결하여 생성됩니다. + 사용자 패스는 UTF-8로 인코딩된 다음, base64로 인코딩된 문자열로 변환됩니다. + base64로 인코딩된 이 사용자 패스는 'Authorization' 헤더에서 Authorization: Basic \$1base64-encoded-user-pass\$1 형식으로 제공됩니다. 예를 들어 사용자 에이전트가 사용자 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//` 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에서는 다음 단계를 수행합니다. + clientId 및 clientSecret과 함께 기본 인증 체계를 사용하여 소유자 토큰을 발급하는 엔드포인트인 tokenUrl에 대한 요청을 인증합니다. + 사용자가 선택적 범위, 대상, 리소스 파라미터를 제공할 경우 이는 토큰 요청에 포함됩니다. + tokenUrl에서 반환한 액세스 토큰을 사용하여 HTTP 요청을 인증합니다. + 향후 토큰 요청을 위해 tokenUrl에서 반환된 새로 고침 토큰을 안전하게 저장합니다. 구성 예제: ``` "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:}` 형식으로 참조하거나, 특정 키 ` ${aws_SECRET::}`를 참조할 수 있습니다. 예를 들어 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로 작성됩니다. 일반적인 실패에 대한 내용은 카나리 문제 해결 페이지 [실패한 카나리 문제 해결](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Troubleshoot.html)을 참조하세요. ### JSON 검사 구성 구문 오류 카나리의 JSON 검사 구성과 관련된 구문 오류가 있는 경우, 카나리 생성을 시도하면 AWS Management Console에서 실패 이유가 표시됩니다. API 또는 CloudFormation을 사용하여 카나리를 생성할 경우에는 카나리를 처음 실행하면 실패한 것으로 표시됩니다. 다중 검사 카나리에는 안전한 카나리 업데이트 워크플로를 사용하는 것이 좋습니다. 자세한 내용은 [안전한 카나리 업데이트 수행](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/performing-safe-canary-upgrades.html)을 참조하세요. ### 네트워킹 또는 제한 시간 실패 제한 시간, 네트워크 연결 실패(예: ENOTFOUND, ECONNRESET)와 관련하여 간헐적이거나 일관된 실패가 발생할 경우, ` DEBUG` 로그를 켜서 다음 실행 시 검사가 실패하는 이유에 대한 추가 세부 정보를 확인하는 것이 좋습니다. 이렇게 하려면 환경 변수 CW\$1SYNTHETICS\$1LOG\$1LEVEL: "DEBUG"를 제공합니다. 디버그할 수 없는 실패가 지속될 경우 AWS Support에 문의하거나, CloudWatch Synthetics에서 제공하는 다른 카나리 유형 중에서 해당 사용 사례에 더 알맞은 유형이 있는지 확인하는 것이 좋습니다.