셀프 호스팅 Grafana 알림으로 AWS DevOps Agent의 인시던트 자동 조사 시작하기

이 글은 ‘셀프 호스팅 Grafana와 AWS DevOps Agent’ 시리즈의 2부로, 1부에서 다룬 VPC 내 프라이빗 서비스로의 보안 연결 설정에 이어 이번 편에서는 Webhook을 통한 자동 트리거 구성을 다룹니다.

왜 셀프 호스팅 Grafana인가

AWS DevOps Agent는 셀프 호스팅 Grafana와 Amazon Managed Grafana(AMG)를 모두 관측 데이터 소스로 연결할 수 있습니다. 다만 알림을 보내 조사를 시작하는 연결과 조사에 필요한 데이터를 조회하는 연결은 구분해야 합니다.

• ① 알림 전송: Webhook Contact Point
  Grafana에서 알림의 전송 대상과 방식을 설정하는 항목입니다. 알림 정책에 매칭된 알림을 DevOps Agent의 Webhook 엔드포인트로 HTTPS POST 요청으로 보냅니다. 인증에는 DevOps Agent에서 발급해 Grafana에 설정한 Webhook 시크릿을 사용합니다.
• ②~③ 데이터 조회: Service Account Token
  DevOps Agent가 Grafana API에서 메트릭과 대시보드 정보를 읽을 때 사용하는 인증 정보입니다. Grafana의 Viewer 서비스 계정에서 발급해 DevOps Agent에 등록합니다. Private Connection은 프라이빗 Grafana에 접근하는 네트워크 경로이며, 조회 결과는 같은 연결로 반환됩니다.

즉, Webhook 시크릿은 알림 전송용, 서비스 계정 토큰은 Grafana 조회용입니다. 이 두 연결을 기준으로 환경을 비교하면 다음과 같습니다.

따라서 이 글에서는 Grafana 알림을 DevOps Agent에 직접 전달해 자동 조사를 시작할 수 있도록 셀프 호스팅 Grafana를 사용합니다. 토큰 유효기간도 자체 정책에 맞게 관리할 수 있지만, 토큰 교체와 Grafana 보안 패치는 운영자가 관리해야 합니다.

이 글에서는 셀프 호스팅 Grafana 환경에서 Webhook 기반 자동 트리거를 구성하는 방법을 단계별로 안내합니다.

참고: AMG의 Contact Point 제한은 공식 문서에서, DevOps Agent 측 제한은 Connecting Grafana – Amazon Managed Grafana considerations에서 확인할 수 있습니다.

대상 환경

Agent Space 리전 선택: AWS DevOps Agent는 서울 리전(ap-northeast-2)을 포함한 여러 리전에서 제공됩니다. Agent Space에 AWS 계정을 연결하면 그 계정의 모든 리전에 있는 리소스를 탐색하고 조사하므로, 워크로드가 실행되는 리전마다 Agent Space를 만들 필요는 없습니다.

Agent Space와 조사·토폴로지·권장 사항 데이터는 생성한 리전에 저장되므로, 데이터 residency 요건을 확인한 뒤 리전을 선택합니다. 이 글의 예시는 us-east-1을 씁니다. 미리 보기 단계인 Release management와 Sandbox는 일부 리전에서만 제공되며, 기능별 제공 리전은 Supported Regions에서 확인할 수 있습니다.

1. 사전 요구 사항

이 글의 순서를 따라 구성하면, Grafana Alert 발생 시 DevOps Agent가 자동으로 인시던트를 조사하는 환경을 구현할 수 있습니다.

이 가이드를 따라 구성하기 전에 다음 항목을 준비합니다.

기본 요구 사항

Grafana 호스트 IAM 권한

CloudWatch를 데이터 소스로 쓰면 Grafana 호스트가 사용하는 IAM 역할에 조회 권한이 필요합니다. 이 권한이 없으면 CloudWatch 콘솔에는 지표가 보이는데 Grafana에서는 조회되지 않습니다. 계정 구성과 무관하게 적용됩니다.

항목별 필수 여부의 전체 목록은 Configure the Amazon CloudWatch data source의 Permissions reference에 정리되어 있습니다.

아래 정책을 Grafana 호스트가 사용하는 IAM 역할에 추가합니다. 이 글의 Alert Rule은 모두 지표 기반이므로 GrafanaCloudWatchMetrics만 있으면 동작합니다. Grafana 대시보드에서 CloudWatch Logs도 조회한다면 GrafanaCloudWatchLogs까지 함께 연결합니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "GrafanaCloudWatchMetrics",
      "Effect": "Allow",
      "Action": [
        "cloudwatch:ListMetrics",
        "cloudwatch:GetMetricData"
      ],
      "Resource": "*"
    },
    {
      "Sid": "GrafanaCloudWatchLogs",
      "Effect": "Allow",
      "Action": [
        "logs:DescribeLogGroups",
        "logs:StartQuery",
        "logs:StopQuery",
        "logs:GetQueryResults"
      ],
      "Resource": "*"
    }
  ]
}

Grafana에서 CloudWatch 데이터 소스 설정을 열고 Save & test를 선택합니다. 지표 API와 로그 API에 각각 도달했다는 두 줄이 표시되면 권한이 반영된 것입니다. 실패하면 /var/log/grafana/grafana.log에서 원인을 확인합니다.

2. 멀티 계정 환경 구성 (Cross-Account Observability)

단일 계정 환경이면 3장으로 바로 진행합니다.

이 예제는 중앙 운영 계정 A에 Grafana와 Agent Space를 두고, 워크로드 계정 B·C·D의 리소스를 모니터링하고 조사하는 구성입니다. 계정 A는 CloudWatch의 모니터링 계정(monitoring account)이자 DevOps Agent의 primary 계정이며, B·C·D는 각각 소스 계정(source account)이자 보조 계정(secondary account)입니다.

DevOps Agent(중앙 운영 계정 A)가 워크로드 계정(B·C·D)의 CloudWatch 메트릭과 로그를 조회하려면 Cross-Account Observability를 사전 구성해야 합니다. Grafana도 중앙 운영 계정 A에 있으므로, 이 구성을 마치면 Grafana의 CloudWatch 데이터 소스에서도 워크로드 계정 지표를 조회할 수 있습니다(쿼리에서 Account ID를 해당 워크로드 계정으로 지정). 즉 Alert Rule을 중앙 운영 계정 A의 Grafana에 두고 워크로드 계정의 리소스를 감시하는 구성이 가능합니다.

이 구성에서는 지표·로그 공유 조회와 워크로드 리소스 직접 조사를 구분해야 합니다.

• 지표·로그 공유 조회: OAM 구성
  OAM(Observability Access Manager)은 여러 계정의 CloudWatch 지표·로그를 중앙 모니터링 계정에서 조회할 수 있도록 공유 연결을 구성하는 기능입니다. 계정 A에 Sink와 Sink Policy를 설정하고, B·C·D 각각에 Link를 생성해 연결합니다. Grafana는 호스트 IAM 역할의 권한으로 CloudWatch를 조회하고, 워크로드 계정의 지표를 대상으로 알림 규칙을 평가합니다. 그림 상단의 화살표는 워크로드 계정이 지표·로그를 계정 A와 공유하는 연결을 나타냅니다.
• 워크로드 리소스 직접 조사: 보조 계정 IAM 역할 구성
  OAM 연결만으로 DevOps Agent가 워크로드 계정의 리소스를 직접 조사할 수 있는 것은 아닙니다. B·C·D 각각에 조사용 IAM 역할을 만들고 Agent Space의 보조 계정으로 연결해야 합니다. DevOps Agent는 해당 역할을 AssumeRole하여 허용된 범위의 리소스를 조사합니다.

Grafana에서 알림이 발생하면 ① Webhook으로 자동 조사를 시작합니다. 그림의 ②-a~c는 실행 순서가 아닌 조사용 접근 경로입니다.

실제 조사에서 사용하는 경로와 조회 대상은 연결된 도구와 권한에 따라 달라지며, 모든 경로를 항상 사용하는 것은 아닙니다.

OAM은 동일 리전 안에서 동작하며, Sink는 계정당 리전별로 하나만 생성할 수 있습니다. 따라서 아래 1~3단계는 계정 A와 B·C·D에서 동일한 워크로드 리전을 지정해 실행합니다. 워크로드가 여러 리전에 있다면 리전별로 반복합니다.

1. 중앙 운영 계정(A)에서 Monitoring Account 설정:

중앙 운영 계정 A에서 Sink 관리 권한(oam:CreateSink, oam:PutSinkPolicy 등)이 있는 IAM 사용자 또는 역할로 실행합니다. 계정별 필요 권한은 Link monitoring accounts with source accounts의 Necessary permissions에 정리되어 있습니다. 먼저 Sink를 만들고 출력된 Sink ARN을 기록해 둡니다.

# 중앙 운영 계정(A)에서 실행. REGION은 워크로드 지표를 모을 리전
REGION=<region>

SINK_ARN=$(aws oam create-sink --region "$REGION" \
  --name "devops-agent-monitoring" --query 'Arn' --output text)
echo "$SINK_ARN"

Sink를 만든 것만으로는 워크로드 계정이 연결할 수 없습니다. 연결을 허용할 계정과 공유할 리소스 유형을 Sink 정책으로 지정해야 합니다. 아래 정책은 워크로드 계정 B·C·D가 지표와 로그만 공유하는 Link를 만들거나 수정하도록 허용하며, sink-policy.json으로 저장합니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "AWS": ["<account-B-id>", "<account-C-id>", "<account-D-id>"] },
      "Action": ["oam:CreateLink", "oam:UpdateLink"],
      "Resource": "*",
      "Condition": {
        "ForAllValues:StringEquals": {
          "oam:ResourceTypes": ["AWS::CloudWatch::Metric", "AWS::Logs::LogGroup"]
        }
      }
    }
  ]
}

Policy 값은 줄바꿈 없는 JSON 문자열이어야 하므로 jq -c로 한 줄로 만들어 적용한 뒤, 적용된 정책을 다시 조회해 확인합니다.

# 중앙 운영 계정(A), Sink와 같은 리전에서 실행
aws oam put-sink-policy --region "$REGION" \
  --sink-identifier "$SINK_ARN" \
  --policy "$(jq -c . sink-policy.json)"

aws oam get-sink-policy --region "$REGION" \
  --sink-identifier "$SINK_ARN" --query 'Policy' --output text

Sink 정책을 바꿀 때: put-sink-policy는 기존 정책 전체를 새 정책으로 교체하므로, 워크로드 계정을 추가할 때는 기존 계정까지 모두 포함한 정책을 다시 적용합니다. Link가 공유하려는 리소스 유형이 Sink 정책에서 허용한 유형보다 많으면 Link 생성이 실패하므로, X-Ray 트레이스도 공유하려면 oam:ResourceTypes에 AWS::XRay::Trace를 추가합니다. 계정 목록 대신 AWS Organizations 조직 단위로 허용하려면 Principal을 "*"로 두고 aws:PrincipalOrgID 조건으로 조직 ID를 지정합니다. 정책 예시는 PutSinkPolicy API 참조에서 확인할 수 있습니다.

2. 워크로드 계정(B·C·D)에서 Source Account 링크 생성:

워크로드 계정마다 Link 관리 권한(oam:CreateLink 등)과 공유할 데이터 유형별 권한(지표는 cloudwatch:Link, 로그는 logs:Link)이 있는 IAM 사용자 또는 역할로 실행합니다. 리전은 1단계의 Sink와 같아야 하며, --sink-identifier에는 1단계에서 기록한 Sink ARN을 넣습니다.

# 워크로드 계정(B·C·D) 각각에서 실행. REGION은 1단계와 같은 리전
REGION=<region>

aws oam create-link --region "$REGION" \
  --label-template '$AccountName' \
  --resource-types "AWS::CloudWatch::Metric" "AWS::Logs::LogGroup" \
  --sink-identifier "arn:aws:oam:<region>:<account-A-id>:sink/<sink-id>"

3. 공유 리소스 확인:

링크가 실제로 붙었는지, 그리고 어떤 리소스 유형이 공유되는지는 중앙 운영 계정(A)에서 확인합니다. Sink ARN을 찾아 그 Sink에 연결된 소스 계정 링크를 조회합니다.

# 중앙 운영 계정(A), Sink와 같은 리전에서 실행
SINK_ARN=$(aws oam list-sinks --region "$REGION" --query 'Items[0].Arn' --output text)

aws oam list-attached-links --region "$REGION" --sink-identifier "$SINK_ARN" \
  --query 'Items[].{Label:Label,ResourceTypes:ResourceTypes}' --output table

워크로드 계정 항목이 나오고, 각 항목의 ResourceTypes에 2단계에서 지정한 유형이 표시됩니다. 이 구성에서 필요한 유형은 지표와 로그 두 가지이며, 트레이스는 선택입니다.

• AWS::CloudWatch::Metric – CloudWatch Metrics
• AWS::Logs::LogGroup – CloudWatch Logs
• AWS::XRay::Trace – X-Ray Traces (선택)

콘솔에서는 CloudWatch → Settings의 모니터링 계정 관리에서 연결된 소스 계정 목록을 볼 수 있습니다.

참고: 상세 절차는 CloudWatch Cross-Account Observability 문서를 참조하세요.

4. DevOps Agent 리소스 조사용 Cross-Account IAM 역할:

OAM은 지표·로그의 가시성만 공유합니다. 워크로드 계정(B·C·D)의 리소스를 직접 조사하려면 각 계정을 Agent Space의 보조 계정으로 연결해야 합니다. 계정마다 IAM 역할이 하나 필요하고, 그 역할에는 다음 세 가지가 붙습니다.

• Trust policy – DevOps Agent 서비스(aidevops.amazonaws.com)가 이 역할을 AssumeRole 하도록 허용합니다. 역할 도용을 막도록 중앙 운영 계정 A의 Agent Space가 보낸 요청만 허용하는 조건(aws:SourceAccount=중앙 운영 계정 A, aws:SourceArn=Agent Space ARN)을 답니다.
• AIDevOpsAgentAccessPolicy (AWS 관리형) – 조사용 read-only 권한.
• Inline policy – 콘솔이 자동 생성하는 추가 권한.

보조 계정에 만들 역할의 Trust policy 예시:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Service": "aidevops.amazonaws.com" },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": { "aws:SourceAccount": "<account-A-id>" },
      "ArnLike": { "aws:SourceArn": "arn:aws:aidevops:<agentspace-region>:<account-A-id>:agentspace/*" }
    }
  }]
}

콘솔에서 보조 계정을 연결하는 절차는 다음과 같습니다. 콘솔과 보조 계정 IAM을 번갈아 오가는 흐름이므로 순서대로 진행합니다.

1. 중앙 운영 계정 A의 AWS DevOps Agent 콘솔에서 대상 Agent Space를 열고 Capabilities 탭 → Cloud 섹션 → Secondary sources → Add를 선택합니다.
2. 콘솔이 보조 계정에 만들 IAM 역할 이름을 자동으로 제안합니다(DevOpsAgentRole-AgentSpace-<임의 문자열> 형태). 제안된 이름을 그대로 써도 되고 원하는 고정 이름을 지정해도 됩니다. 이 이름과 함께 trust policy(신뢰 정책)·inline policy를 화면에 보여줍니다 – 이 값들을 복사해 둡니다.
3. 보조 계정의 IAM 콘솔로 이동해 지정한(또는 제안된) 이름으로 역할을 새로 만듭니다. 이 역할에는 세 가지를 붙입니다: 앞서 복사한 Custom trust policy, AWS 관리형 정책 AIDevOpsAgentAccessPolicy(조사용 read-only 권한), 그리고 콘솔이 함께 안내한 inline policy(추가 권한).
4. 역할 생성을 마쳤으면 중앙 운영 계정 A의 DevOps Agent 콘솔로 돌아와 Next를 선택합니다.
5. Configure Actions Role(선택) 단계가 나옵니다. Actions Role은 이 계정에 변경(생성·수정·삭제)을 수행하는 역할이며(매 변경마다 승인 필요), 읽기 전용 관찰에서는 No, not right now를 선택합니다(나중에 Edit 페이지에서 추가 가능). Next를 선택합니다.
6. Connect to Agent 단계에서 보조 계정의 Account ID를 넣고, Role Name이 2단계에서 정한 이름과 같은지 확인한 뒤 Add를 선택합니다.
7. 해당 보조 계정 연결의 상태가 Valid로 표시되는지 확인합니다. Valid가 되면 DevOps Agent가 그 계정의 리소스를 조사할 수 있습니다.

중요 – iam:PassRole 권한: 보조 계정을 추가하거나 업데이트할 때 DevOps Agent는 요청을 보낸 주체가 IAM 역할을 전달(iam:PassRole)할 수 있는지 검사합니다. 이 주체는 중앙 운영 계정 A에서 요청을 보내는 IAM 사용자 또는 역할이며, iam:PassRole이 없으면 aidevops:*가 있어도 HTTP 403 AccessDeniedException (iam:PassRole)로 실패합니다.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "iam:PassRole",
    "Resource": "arn:aws:iam::<account-A-id>:role/*",
    "Condition": {
      "StringEquals": { "iam:PassedToService": "aidevops.amazonaws.com" }
    }
  }]
}

Resource는 역할 와일드카드(arn:aws:iam::<account-A-id>:role/* 또는 *)여야 하며, 특정 ARN으로 좁히면 통과하지 못합니다. 검사는 보조 계정 추가·업데이트 시마다 실행되고, 기존 연결은 다음 업데이트 전까지 유지됩니다.

부착 방법: 이 정책은 중앙 운영 계정 A에서 보조 계정 연결·수정 작업을 실제 수행하는 IAM 사용자 또는 역할에 부여합니다. Web App의 Operator access 역할과는 구분합니다.

• 콘솔 – 중앙 운영 계정 A IAM에서 해당 역할 선택 → Add permissions → Create inline policy → JSON에 위 정책 붙여넣기(<account-A-id> 치환) → 이름 지정 → 생성.
• CLI – 정책을 passrole.json으로 저장 후 aws iam put-role-policy --role-name <역할명> --policy-name DevOpsAgentPassRole --policy-document file://passrole.json (IAM 사용자면 put-user-policy --user-name).

권한이 permission boundary나 조직 SCP로 막혀 있으면 그쪽에서도 iam:PassRole을 허용해야 합니다.

참고 – 역할 두 종류: DevOps Agent는 조사 대상 계정에 따라 서로 다른 역할을 사용합니다.

• primary 역할 – 중앙 운영 계정 A 자신의 리소스를 조사할 때 씁니다. Agent Space를 만들 때 지정하며, 직접 만들기보다 Auto-create a new AWS DevOps Agent role 옵션으로 콘솔이 자동 생성하도록 하는 것을 권장합니다.
• 보조 계정 역할 – 앞의 절차에서 만든 역할로, 보조 계정 B·C·D의 리소스를 조사할 때 씁니다(계정마다 하나).

정리하면 중앙 운영 계정 A는 primary 역할로 자기 리소스를, 보조 계정 역할로 B·C·D의 리소스를 조사합니다. 자세한 내용은 Creating an Agent Space와 Connecting multiple AWS Accounts를 참조하세요.

5. Grafana의 크로스 계정 조회 권한:

1장에서 연결한 정책에 아래 statement를 더합니다. Grafana가 Sink에 연결된 계정 목록을 찾는 데 필요하며, 이 권한이 없으면 쿼리 편집기에 Account 필드가 나타나지 않습니다.

{
  "Sid": "GrafanaCrossAccountObservability",
  "Effect": "Allow",
  "Action": [
    "oam:ListSinks",
    "oam:ListAttachedLinks"
  ],
  "Resource": "*"
}

연결한 뒤 쿼리 편집기의 Account 목록에 워크로드 계정이 나타나는지 확인합니다. 목록이 비어 있으면 이 권한이나 앞의 OAM Link 구성을 다시 점검합니다.

크로스 계정 조회의 범위: 이 기능은 CloudWatch API로 조회하는 지표와 로그에만 적용됩니다. EC2 인스턴스 속성은 EC2 API에서 오므로 계정 간 조회가 되지 않으며, 해당 템플릿 변수는 Grafana가 있는 계정의 값만 채웁니다.

3. End-to-End 자동화 흐름

• Grafana Alert Rule이 임계치 위반을 감지하면, Webhook Contact Point로 DevOps Agent에 HTTP POST를 보냅니다.
• DevOps Agent는 인시던트를 생성한 뒤, Private Connection으로 Grafana 메트릭을 조회하면서 CloudWatch Logs·배포 이력 등을 함께 상관 분석합니다.
• 조사가 끝나면 RCA 리포트가 생성되고, Console/Slack에서 결과를 확인할 수 있습니다.

중요: Grafana 연동은 read-only입니다. DevOps Agent는 Viewer 권한의 Service Account 토큰으로 연결해 메트릭 조회와 대시보드 참조만 수행합니다. (별도의 Actions Role은 AWS 계정 리소스의 변경(생성·수정·삭제, 매 변경 승인)용이며 Grafana와는 무관합니다 – Actions Role을 켜도 Grafana는 계속 read-only입니다.)

4. Webhook 기반 자동 트리거 구성

Step 1: Webhook URL과 시크릿 확보

Grafana를 Agent Space에 연결하면 통합 전용 Webhook이 자동 생성됩니다. AWS DevOps Agent 콘솔 → Agent Space → Capabilities 탭 → Webhooks 테이블에서 Identifier(Grafana 엔드포인트)로 해당 항목을 찾습니다.

URL은 Copy URL을 선택합니다. 시크릿은 Edit → Rotate webhook을 선택합니다. URL은 그대로 유지되고 새 시크릿이 생성되며, Download .csv file로 저장할 수 있습니다.

Webhook URL은 다음 형식이며, <webhook-id>는 UUID입니다.

https://event-ai.<agentspace-region>.api.aws/webhook/generic/<webhook-id>

참고: URL 자체는 시크릿이 아니지만 계정의 수신 엔드포인트를 식별하므로, 외부에 공유하는 문서에는 넣지 않는 것을 권장합니다.

중요: 시크릿은 생성 시점에 한 번만 표시되며 콘솔·API·IaC 어디에서도 다시 조회할 수 없습니다. 분실했다면 Rotate로 재발급해야 합니다. Rotate 하면 이전 시크릿은 즉시 무효화되므로, 발신 측(Grafana Contact Point) 설정을 함께 갱신해야 합니다.

참고: CloudFormation·CDK·Terraform으로 Webhook을 만든 경우 시크릿이 스택 출력값으로 반환되지 않습니다. 배포 후 Rotate로 시크릿을 받아야 합니다.

Step 2: Notification Template 생성

Grafana → Alerting → Notification configuration → Templates에서 새 템플릿을 만듭니다.

Template Name: devops-agent-payload

{{ define "devops-agent-payload" }}
{
  "eventType": "incident",
  "incidentId": "{{ (index .Alerts 0).Labels.alertname }}-{{ (index .Alerts 0).Fingerprint }}",
  "action": "{{ if eq .Status "resolved" }}resolved{{ else }}created{{ end }}",
  "priority": "{{ if eq .Status "resolved" }}MEDIUM{{ else }}HIGH{{ end }}",
  "title": "{{ (index .Alerts 0).Labels.alertname }}",
  "description": "{{ (index .Alerts 0).Annotations.summary }}",
  "service": "{{ if (index .Alerts 0).Labels.job }}{{ (index .Alerts 0).Labels.job }}{{ else }}grafana{{ end }}",
  "timestamp": "{{ (index .Alerts 0).StartsAt }}",
  "data": {
    "metadata": {
      {{ range $k, $v := (index .Alerts 0).Labels }}
      "{{ $k }}": "{{ $v }}",
      {{ end }}
      "_source": "grafana"
    }
  }
}
{{ end }}

이 템플릿이 만들어 내는 페이로드 스키마는 다음과 같습니다. 템플릿을 조직 상황에 맞게 수정할 때 필수 필드와 허용 값을 벗어나지 않도록 확인합니다.

Step 3: Webhook Contact Point 생성

Grafana → Alerting → Notification configuration → Contact points에서 새 Contact Point를 추가합니다.

Grafana 통합 Webhook은 Bearer 토큰 인증을 사용합니다(HMAC이 아닙니다). Grafana Contact Point의 Optional Webhook settings에서 Authorization 헤더를 설정하면 됩니다.

Step 4: Notification Policy 설정

Step 3에서 Contact Point를 만들었지만, 아직 어떤 Alert도 그 Contact Point로 가지 않습니다. Alert을 Contact Point로 보내는 것은 Notification Policy입니다.

이 Step은 이미 운영 중인 Alert Rule을 대상으로 합니다. 기존 규칙은 Notification Policy 트리를 따라 Slack이나 PagerDuty로 알림을 보내고 있으므로, 규칙을 하나하나 수정하지 않고 정책 한 줄을 추가해 DevOps Agent를 경로에 끼워 넣습니다. 새로 만드는 규칙은 규칙 생성 화면의 Configure notifications에서 Contact point를 직접 지정해 정책을 건너뛸 수도 있지만, 같은 화면의 Advanced options 토글을 켜면 새 규칙도 이 정책 트리를 따릅니다. 6장 Step 3의 End-to-End 테스트는 이 정책까지 검증하려고 토글을 켠 경로를 사용합니다.

Notification Policy는 트리 구조입니다. 모든 Alert은 Default policy에서 평가된 뒤 하위 정책으로 내려가며, 라벨 matcher가 일치하는 정책의 Contact Point로 전달됩니다. 여기서 Default policy의 Contact Point를 devops-agent-webhook으로 바꾸면 기존 알림이 끊깁니다. Default policy는 그대로 두고 하위에 중첩 정책을 하나 추가해, 기존 경로와 병행하도록 구성합니다.

정책은 위에서 아래로 평가되며, 매칭되면 기본적으로 거기서 멈춥니다. ①에 Continue matching subsequent sibling nodes를 켜야 ① 전달 후에도 형제 정책 평가가 계속되어 ②까지 함께 발송됩니다. 이 옵션이 “기존 알림 유지”의 핵심이며, 형제 정책의 순서도 함께 확인해야 합니다. 위쪽 정책에서 이 옵션을 켜지 않으면 아래 정책은 평가되지 않습니다.

중첩 정책 생성

1. Grafana → Alerting → Notification configuration → Notification policies로 이동합니다.
2. Default policy 영역에서 + Add route를 선택합니다.
3. 아래 표대로 값을 채우고 정책을 저장합니다.

타이밍을 조정할 때: 기본값은 Group wait 30초(30s) · Group interval 5분(5m) · Repeat interval 4시간(4h)입니다. 자동 조사는 첫 웹훅이 도착한 시점에 시작되므로, 조사 착수를 앞당기려면 Group wait을 줄이는 것이 가장 직접적입니다. 다만 짧게 두면 아직 묶이지 않은 Alert이 개별 인시던트로 흩어질 수 있어, 조사 지연과 인시던트 분산 사이의 균형을 보고 정합니다. 검증 단계에서 임시로 짧게 줄였다면 운영 전환 시 반드시 원래 값으로 되돌립니다.

라벨과 matcher가 어긋나면 DevOps Agent로 전달되지 않습니다: 이 정책은 지정한 라벨에만 반응합니다. Alert Rule에 해당 라벨이 없거나 값이 다르면 정책에 매칭되지 않고, Alert은 Default policy의 Contact Point로만 전달됩니다. Alert은 firing인데 인시던트가 생기지 않는 증상이 나타나면 라벨 철자와 값을 먼저 확인합니다.

5. Slack 채널 연동 (선택 – 조사 결과 수신)

DevOps Agent가 생성한 인시던트 조사 결과·근본 원인 분석·완화 방안을 Slack 채널로 받으려면, Slack을 먼저 Capability Providers에 등록한 뒤 Agent Space에 채널을 연결합니다. End-to-End 흐름의 ❻ 리포트 전달 경로가 동작하려면 이 설정이 선행되어야 합니다. Slack을 쓰지 않는 환경이면 이 장을 건너뛰어도 자동 조사 파이프라인은 동일하게 동작하며, 조사 결과는 DevOps Agent Web App에서 확인합니다.

Capability Providers에서 Slack 등록

1. AWS DevOps Agent 콘솔 → Capability Providers → Communication 섹션의 Available에서 Slack을 찾아 Register를 선택합니다.
2. Slack 인증 페이지로 이동하면 조직(Enterprise Grid)이 아닌 워크스페이스 단위로 설치합니다.
3. 요청된 스코프를 확인하고 Allow로 인증하면 콘솔로 돌아옵니다.

등록 1건은 Slack 워크스페이스 1개에 연결됩니다. 단일 워크스페이스를 여러 AWS 계정·Agent Space에서 공유할 수 있으며(CMK 암호화 포함), 각 등록은 독립적입니다.

Agent Space에 Slack 채널 연결

1. 대상 Agent Space의 Capabilities 탭에서 Communications 섹션으로 이동해 Add integration 버튼을 선택합니다.
2. 목록에서 Slack(Registered 상태)을 찾아 Add를 선택합니다.
3. 안내에 따라 Channel ID를 입력해 연결을 완료합니다.
4. Slack 채널에서 봇을 초대합니다: /invite @AWS DevOps Agent – US East (N. Virginia). Agent Space 리전에 해당하는 앱 이름을 씁니다.

6. 연동 테스트 및 검증

Webhook 구성이 끝나면 아래 세 단계로 검증합니다. 검증 범위를 좁은 것부터 넓혀 가므로, 실패한 단계가 곧 원인 구간이 됩니다.

Step 1: Webhook 엔드포인트 직접 호출 (curl)

Grafana를 거치지 않고 직접 POST해 엔드포인트와 인증이 유효한지 먼저 확정합니다.

WEBHOOK_URL="https://event-ai.<agentspace-region>.api.aws/webhook/generic/<webhook-id>"   # 4장 Step 1에서 확보
WEBHOOK_SECRET="<webhook-secret>"
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)

curl -i -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WEBHOOK_SECRET" \
  -H "x-amzn-event-timestamp: $TIMESTAMP" \
  -d '{
    "eventType": "incident",
    "incidentId": "test-connectivity-'"$(date +%s)"'",
    "action": "created",
    "priority": "HIGH",
    "title": "LabWebhookConnectivityTest",
    "description": "Initial connectivity test",
    "service": "test-service",
    "timestamp": "'"$TIMESTAMP"'"
  }'

200과 함께 webhook received 같은 응답을 받으면 인증과 헤더가 통과한 것이며, DevOps Agent Web App → Incidents에서 생성된 인시던트를 확인할 수 있습니다. 페이로드 각 필드의 필수 여부와 허용 값은 4장 Step 2의 스키마 표를 참고하세요.

응답 코드별 진단

Step 1의 curl 응답으로 원인을 좁힐 수 있습니다. 아래 표에 해당하지 않는 응답이 나오면 페이로드와 헤더를 다시 확인한 뒤 Step 2로 넘어갑니다.

Step 2: Webhook 전달 경로 확인 (Contact Point 테스트)

Step 1이 성공했다면 엔드포인트는 정상입니다. 이제 Grafana가 그 엔드포인트까지 도달하는지 확인합니다.

1. Grafana → Alerting → Notification configuration → Contact points로 이동합니다.
2. devops-agent-webhook 옆의 Edit 버튼을 선택한 뒤 Test 버튼을 선택합니다.
3. Send test notification을 선택합니다.
4. DevOps Agent Web App에서 테스트 인시던트가 생성되는지 확인합니다.

Step 1은 성공했는데 Step 2가 실패하면 엔드포인트가 아니라 Grafana 호스트의 아웃바운드 경로가 원인입니다. Grafana가 프라이빗 서브넷에 있다면 NAT Gateway 경로와 보안 그룹 아웃바운드 규칙을 확인하고, Grafana 서버 로그에서 전송 실패 기록을 함께 봅니다.

Step 3: Alert Rule End-to-End 테스트

마지막으로 Alert Rule부터 RCA까지 전체 파이프라인을 검증합니다. 조건이 항상 참인 테스트 규칙을 만들어 즉시 발동시킵니다. Alerting → Alert rules → + New alert rule을 선택한 뒤 아래 순서로 입력합니다.

1. Enter alert rule name – TestWebhookE2E를 입력합니다. 이 값이 alertname 라벨이 되고, 4장 Step 2의 템플릿이 이를 인시던트 title로 전달합니다.
2. Define query and alert condition – 데이터 소스가 CloudWatch인 경우, 쿼리 모드가 CloudWatch Metrics인 상태에서 Code 탭에 TIME_SERIES(1)을 입력합니다. Period는 60으로 지정합니다. 조건은 WHEN Last OF query IS ABOVE 0으로 둡니다. TIME_SERIES(1)은 모든 값이 1인 시계열을 반환하는 Metric Math 함수이므로 조건이 늘 참이 됩니다. Preview로 값이 1로 나오는지 확인합니다. 데이터 소스가 Prometheus인 경우 Code 탭에서 vector(1)을 입력합니다. 조건은 WHEN Last OF query IS ABOVE 0으로 둡니다. vector(1)은 항상 1을 반환하므로 조건이 늘 참이 되며, Prometheus 인스턴트 벡터는 별도 Reduce 표현식 없이 바로 조건에 쓸 수 있습니다. Preview로 값이 1로 나오는지 확인합니다.
3. Add folder and labels – 폴더를 선택하거나 새로 만들고, 라벨에 severity = warning을 추가합니다. 이 라벨이 Step 4 정책의 matcher severity =~ critical|warning에 걸려 devops-agent-webhook으로 라우팅됩니다. 라벨은 템플릿의 data.metadata에도 복사되지만 조사 컨텍스트에는 포함되지 않으므로, 조사에 필요한 정보는 6번의 Summary에 넣습니다. 식별용으로 team = test를 함께 넣어도 됩니다.
4. Set evaluation behavior – Evaluation group and interval에서 평가 그룹을 선택하거나 + New evaluation group으로 새로 만듭니다. 새로 만들 때는 평가 간격을 함께 지정하며, 테스트에서는 결과를 빨리 보기 위해 짧게(예: 10s) 둡니다. 같은 그룹에 속한 규칙은 이 간격으로 동시에 평가됩니다. 이어서 Pending period를 0으로 지정합니다. 조건 위반이 확인된 즉시 Firing으로 전환되며, 값을 남기면 그 시간만큼 Pending 상태에 머문 뒤 발동합니다.
5. Configure notifications – Advanced options 토글을 켭니다. 그러면 Contact point를 직접 지정하는 대신 Default policy부터 Notification Policy 트리를 따라 라우팅되므로, Step 4에서 추가한 정책까지 함께 검증됩니다. 토글을 끈 기본 상태에서는 Contact point가 필수 입력이 되고 정책은 거치지 않습니다.
6. Configure notification message – Summary에 End-to-end webhook integration test를 입력합니다. 템플릿이 이 값을 인시던트 description으로 전달합니다. 입력을 마치면 규칙을 저장합니다.

검증 순서(End-to-End 흐름 대응):

1. Alert → Policy → Webhook: Alert Rule이 firing되면 Notification Policy가 severity 라벨로 경로를 정하고, 매칭된 Contact Point로 DevOps Agent에 HTTP POST가 전달됩니다. Grafana Alerting → Active notifications에서 어느 Contact Point로 전송됐는지 확인할 수 있습니다.
2. 인시던트 생성 → 자동 조사: DevOps Agent Web App에 인시던트가 생성되고, Private Connection으로 Grafana 메트릭을 조회하면서 CloudWatch Logs·배포 이력 등을 함께 상관 분석하는지 확인합니다(멀티계정이면 워크로드 계정의 메트릭·로그 포함).
3. RCA → Console/Slack: 조사가 완료되면 RCA 리포트가 생성되고, Console/Slack에서 근본 원인·근거·조회한 데이터 소스를 확인할 수 있습니다.
4. 정리: Alert Rule을 삭제하면 resolved 이벤트가 전달되어 인시던트가 종료되는지 확인합니다.

테스트 규칙은 반드시 삭제합니다: TestWebhookE2E는 조건이 항상 참이므로 방치하면 계속 firing 상태로 남아 반복 알림과 불필요한 인시던트를 만듭니다. 검증이 끝나면 삭제하세요.

7. AWS 서비스별 장애 시나리오와 DevOps Agent 활용

다음은 Grafana Alert과 DevOps Agent를 연동하여 자동 조사가 가능한 장애 시나리오의 한 예시입니다. 각 시나리오마다 적절한 Alert Rule을 구성하면 Webhook이 DevOps Agent의 자동 조사를 트리거합니다.

Elastic Load Balancing (ALB)

Amazon EKS

Auto Scaling Group

Amazon EC2

EC2 표준 지표(AWS/EC2)에는 메모리·디스크 사용률이 없어 위 값은 CloudWatch agent가 게시하는 커스텀 지표를 씁니다. 네임스페이스 기본값 CWAgent는 Manually create or edit the CloudWatch agent configuration file, 지표 이름과 Partition 차원은 Create the CloudWatch agent configuration file with the wizard를 참조하세요.

정리

이 글에서는 셀프 호스팅 Grafana의 Webhook Contact Point를 활용하여 AWS DevOps Agent의 자동 인시던트 조사를 트리거하는 방법을 단계별로 안내했습니다.

• 셀프 호스팅 Grafana를 선택한 이유: Webhook Contact Point를 지원하고, Service Account Token의 만료 제약이 없기 때문입니다.
• 조회 권한을 먼저 확인합니다: Grafana 호스트의 IAM 역할에 cloudwatch:ListMetrics·cloudwatch:GetMetricData가 없으면 CloudWatch 콘솔에는 지표가 보여도 Grafana에서는 조회되지 않습니다. 멀티 계정 환경이라면 OAM 구성과 oam: 권한까지 갖춘 뒤 쿼리 편집기의 Account 목록에 워크로드 계정이 나타나는지 확인합니다.
• Webhook은 4단계로 구성합니다: 엔드포인트 확인 → 템플릿 → Contact Point → Policy 순으로 진행합니다.
• 검증은 세 단계로 좁혀 갑니다: curl로 엔드포인트와 인증을 먼저 확정하고, Contact Point 테스트로 Grafana의 전달 경로를 확인한 뒤, 항상 firing되는 테스트 Alert Rule로 Alert → Webhook → 자동 조사 → RCA(Console/Slack)까지 End-to-End를 점검합니다. 실패한 단계가 곧 원인 구간입니다.

관련 리소스

• AWS DevOps Agent
• Connecting Grafana – 사용자 가이드
• Private Connection 설정 (1부)
• CloudWatch Cross-Account Observability
• AWS DevOps Agent 요금 – 2개월 무료 체험