Amazon Bedrock Agents와 AWS Support 자동화 워크플로우 (SAW)를 통한 AWS 리소스 문제 해결 간소화 Part 2 – 다양한 런북 통합 실전 가이드

이 글은 AWS Korea 기술 Blog에 게시된 Amazon Bedrock Agents와 AWS Support 자동화 워크플로우 (SAW)를 통한 AWS 리소스 문제 해결 간소화에 이어서 작성되었습니다. 해당 글을 함께 참조하시어 본 글에서 다룰 내용을 이해하시는 데 도움을 받으시길 바랍니다.

지난 글에서 우리는 Amazon Bedrock Agents와 AWS Support Automation Workflows (SAW) 런북을 활용하여 AWS 환경에서 발생하는 다양한 리소스 관련 문제를 자동으로 분석하고 해결할 수 있는 지능형 에이전트를 만드는 방법을 살펴보았습니다.

이번 글에서는 Part 1에서 구축한 솔루션을 기반으로 단일 인터페이스 (Amazon Bedrock 에이전트)를 통해 보다 다양한 SAW 런북을 활용하여 실제 운영 환경에서 발생할 수 있는 더 많은 문제를 처리할 수 있도록 솔루션을 확장하는 방법을 살펴보겠습니다.

사전 조건: 이번 글을 따라 실습을 진행하기 위해서는 지난 글의 ‘사전 요구사항’ 및 ‘솔루션 배포 섹션’을 참조하여 솔루션 배포를 우선 완료하셔야 합니다.

솔루션 개요

본 글에서 다루는 솔루션은 지난 글에서 살펴본 바와 같이 다양한 AWS Support Automation Workflows (SAW) 런북과 통합할 수 있는 유연한 구조를 가지고 있습니다. 이 글에서는 사용자가 희망하는 새로운 SAW 런북을 추가로 통합하여 정의하는 방법을 다루도록 하겠습니다.

아래 다이어그램은 Amazon Bedrock을 사용한 문제 해결 에이전트의 전반적인 개요를 보여줍니다.

본 솔루션은 원활하고 효율적인 문제 해결 경험을 제공하기 위해 다음과 같은 주요 구성 요소들로 이루어져 있습니다.

Amazon Bedrock 에이전트 – Amazon Bedrock 에이전트는 사용자와 AWS Support Automation Workflows (SAW) 사이의 지능형 인터페이스 역할을 합니다. 자연어 쿼리를 처리하여 문제의 맥락을 이해하고, 필요한 정보를 수집하기 위한 대화 흐름을 관리합니다. 사용자가 희망하는 파운데이션 모델 (Foundation Model, FM)을 활용하여 고급 추론과 응답 생성을 수행하며, 문제 해결 과정 전반에 걸쳐 자연스러운 상호작용을 가능하게 합니다.
Amazon Bedrock 에이전트 작업 그룹 – 이 작업 그룹은 Amazon Bedrock 에이전트가 호출할 수 있는 구조화된 API 작업을 정의합니다. OpenAPI 명세를 사용하여 에이전트와 AWS Lambda 함수 간의 인터페이스를 정의하며, 사용 가능한 작업, 필요한 매개변수, 예상되는 응답을 지정 (Specify)합니다. 각 작업 그룹은 Lambda 함수와 상호작용할 때 에이전트가 요청을 적절하게 포맷하고 응답을 해석하는 방법을 알려주는 API 스키마를 포함합니다.
Lambda 함수 – Lambda 함수는 Amazon Bedrock 에이전트와 AWS Support Automation Workflows (SAW) 간의 통합 계층 역할을 합니다. 에이전트로부터 받은 입력 매개변수를 검증하고 적절한 SAW 런북을 실행합니다. 기술적 출력을 구조화된 형식으로 처리하면서 자동화 진행 상황을 모니터링합니다. 런북 실행이 완료되면 사용자에게 보여줄 형식화된 결과를 에이전트에 반환합니다.
IAM 역할 – AWS Identity and Access Management (IAM) 역할은 Lambda 함수가 SAW 런북을 실행하고 필요한 AWS 서비스와 상호작용하는 데 필요한 권한을 제공합니다. 이 역할은 보안 모범 사례를 유지하기 위해 최소 권한 원칙 (Principle of Least Privilege)을 따릅니다.
AWS Support Automation Workflows (SAW) – AWS Support Engineering 팀에서 개발한 사전 구축된 진단 런북입니다. 이는 AWS 모범 사례를 기반으로 표준화되어 반복 가능한 방식으로 종합적인 시스템 점검을 실행합니다. AWS Support Engineering 팀의 문제 해결을 위한 전문 지식이 담겨 있으며 AWS 서비스와 일반적인 문제들을 광범위하게 다룰 수 있습니다.

다음 단계들은 본 솔루션에 새로운 SAW 런북을 추가하는 절차를 설명합니다.

런북 선정 및 분석: 솔루션에 통합하고자 하는 SAW 런북을 선정하고 해당 런북의 AWS 문서를 확인하여 필요한 입력 파라미터와 IAM 권한을 파악합니다.
결과 단계 식별: 런북 실행 결과를 확인할 수 있는 단계 (Step)를 식별합니다.
OpenAPI 스키마 정의: 새로운 런북을 위한 API 엔드포인트와 파라미터 스키마를 정의합니다.
Lambda 함수 업데이트: 새로운 런북을 호출하는 Lambda 함수 엔드포인트를 추가합니다.
IAM 권한 업데이트: 새로운 런북 실행에 필요한 IAM 권한을 추가합니다.
에이전트 작업 그룹 업데이트: Amazon Bedrock 에이전트의 작업 그룹에 새로운 API 스키마를 적용합니다.

이후 실제 문제 해결 과정은 다음과 같이 진행됩니다.

사용자 요청: 사용자가 Amazon Bedrock 채팅 콘솔을 통해 AWS 리소스 문제를 자연어로 설명합니다.
런북 실행: Lambda 함수가 적절한 Support Automation Workflow 런북을 실행합니다.
결과 수집: 런북이 진단 검사를 실행하고 결과를 JSON 형식으로 반환합니다.
지능형 분석: Amazon Bedrock 에이전트는 ReAct 기법을 기반으로 한 CoT 추론을 사용하여 리소스 진단 결과를 분석하고 문제 해결을 위한 가이드를 제공합니다.

솔루션 폴더 구조

솔루션의 폴더 구조는 다음과 같습니다.

bedrock-agent-saw
│
├── bin
│   └── bedrock-agent-saw.ts          # CDK app entry point
├── lib                               # CDK Stacks
│   └── bedrock-agent-saw-stack.ts    # Stack deploying the Bedrock Agent and Action Group 
├── lambda                            # Lambda functions
│   └── saw_troubleshooting           # Action Group functions
│       ├── app.py                    # Main Lambda handler and API endpoints
│       └── utils.py                  # Utility functions for SSM Automation
├── bedrock_agent_schemas             # OpenAPI schema for the Bedrock Agent
│   └── schema.json                   # Auto-generated schema for the agent

각 파일들의 상세 내용은 GitHub에서 확인이 가능합니다.

새로운 SAW 런북을 추가로 통합하기 위해서 수정이 필요한 파일들은 다음과 같습니다.

bedrock_agent_schemas/schema.json: OpenAPI 스키마에 새로운 런북을 위한 API 엔드포인트와 파라미터를 추가합니다.
lambda/saw_troubleshooting/app.py: 새로운 런북을 호출하는 Lambda 함수를 추가합니다.
lib/bedrock-agent-saw-stack.ts: 새로운 런북 실행에 필요한 IAM 권한을 추가합니다.

SAW 런북 통합 방법 예시

아래에서는 Amazon Bedrock 에이전트가 새로운 AWS 리소스 문제를 해결할 수 있도록 기존 솔루션에 추가 SAW 런북을 통합하는 방법을 단계 별로 살펴보겠습니다. 본 글에서는 AWSSupport-TroubleshootCloudWatchAgent 런북을 추가하겠습니다.

1단계: 런북 문서 (AWS 공식 문서) 분석

AWSSupport-TroubleshootCloudWatchAgent 런북의 공식 문서를 참조하여 아래 정보를 수집합니다.

필수 파라미터

InstanceId: CloudWatch Agent 문제를 해결할 EC2 인스턴스 ID

선택적 파라미터

S3UploadBucket: CloudWatch Agent 로그를 업로드할 S3 버킷 이름
S3BucketOwnerAccountId: S3 버킷을 소유한 AWS 계정 번호
CheckEC2Endpoint: append_dimensions 옵션 사용 시 EC2 API 엔드포인트 연결 테스트 여부
RunVpcReachabilityAnalyzer: 네트워크 문제 발견 시 VPC Reachability Analyzer 실행 여부
RetainVpcReachabilityAnalysis: VPC Reachability Analyzer 리소스 보존 여부
AutomationAssumeRole: 자동화 실행을 위한 IAM 역할 ARN

런북 실행 단계

getInstanceProfile: 제공된 Amazon EC2 인스턴스에 IAM 인스턴스 프로파일이 연결되어 있는지 확인합니다.
verifyIamPermissions: 인스턴스와 연결된 인스턴스 프로파일을 검사하여 필요한 IAM 권한이 적용되어 있는지 확인합니다.
getInstanceInformation: 인스턴스에 활성 Systems Manager 에이전트가 있는지 확인하고 인스턴스의 OS 유형을 가져옵니다.
getAgentStatus: 인스턴스에서 Amazon CloudWatch Agent의 상태를 확인합니다 (확장 검사).
analyzeLogs/analyzeLogsWindows: OS 유형에 따라 Amazon CloudWatch Agent 로그를 분석하고 결과를 출력합니다.
collectLogs/collectLogsWindows: OS 유형에 따라 관련 Amazon CloudWatch Agent 문제 해결 파일을 번들로 묶어 출력합니다.
checkEndpointReachability/checkEndpointReachabilityWindows: OS 유형에 따라 인스턴스가 필요한 엔드포인트에 도달할 수 있는지 확인합니다.
analyzeAwsEndpointReachabilityFromEC2: 선택된 인스턴스에서 필요한 엔드포인트로의 도달 가능성을 확인하기 위해 하위 자동화 런북을 호출합니다 (활성화된 경우).
outputFindings: 자동화 실행 단계들의 결과를 출력합니다.

필요한 IAM 권한

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeInstances",
                "iam:GetInstanceProfile",
                "iam:GetRole",
                "iam:ListAttachedRolePolicies",
                "iam:ListRolePolicies",
                "iam:GetRolePolicy",
                "iam:GetPolicy",
                "iam:GetPolicyVersion",
                "iam:SimulatePrincipalPolicy",
                "ssm:DescribeInstanceInformation",
                "ssm:SendCommand",
                "ssm:GetCommandInvocation",
                "ssm:DescribeInstanceAssociationsStatus",
                "ssm:StartAutomationExecution"
            ],
            "Resource": "*"
        }
    ]
}

런북 실행에 필요한 정보 판단

위와 같이 확인한 내용을 통해 AWSSupport-TroubleshootCloudWatchAgent 런북 실행을 위해서는 2개의 파라미터 (InstanceId, S3UploadBucket)가 필요하며 outputFindings 단계 (Step)에서 출력된 런북 실행 결과가 Amazon Bedrock 에이전트에 전달되어야 한다는 요구 사항을 파악할 수 있습니다.

2단계: OpenAPI 스키마 정의

OpenAPI 스키마 정의 – 경로 (Path)

bedrock_agent_schemas/schema.json 파일에 새로 추가할 SAW 런북을 위한 API 엔드포인트를 추가로 정의합니다. 이 스키마는 Bedrock 에이전트가 Lambda 함수를 호출할 때 사용할 인터페이스를 정의합니다.

스키마의 역할

Bedrock 에이전트가 수행할 수 있는 작업 정의
각 작업에 필요한 파라미터와 형식을 명시
에이전트가 자연어 요청을 적절한 API 호출로 변환하도록 가이드

{
  "paths": {
    ...
    "/troubleshoot-cw-agent": { // <-- 새 SAW 런북과 연결할 엔드포인트 경로를 정의합니다.
        "post": {
            "summary": "POST /troubleshoot-cw-agent",
            "description": "Troubleshoot Amazon CloudWatch Agent on your Amazon EC2 instance.",
            "operationId": "troubleshoot_cw_agent", // <-- 에이전트가 이 작업을 식별하는 고유 ID를 정의합니다.
            "requestBody": {
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Body_troubleshoot_cw_agent" // <-- 파라미터 스키마를 참조하도록 정의합니다.
                        }
                    }
                },
                "required": true 
            },
            "responses": {
                "200": {
                    "description": "Successful Response",
                    ...
                },
                "422": {
                    "description": "Validation Error", // <-- 파라미터 검증 실패 시 에러를 반환하도록 정의합니다.
                    ...
                }
            }
        }
    } // <-- 새 SAW 런북의 경로 정보를 추가합니다.
  },
  "components": {
    ...
  },
  ...
}

OpenAPI 스키마 정의 – 구성 요소 (Component)

components 섹션에는 API 요청에 필요한 파라미터의 구조를 정의합니다. 이는 데이터 검증과 에이전트의 파라미터 수집을 돕습니다.

구성 요소의 역할

각 파라미터의 데이터 유형과 설명 정의
필수/선택 파라미터 구분
에이전트가 사용자에게 누락된 정보를 요청할 경우 사용할 설명 제공

{
  "paths": {
    ...
  },
  "components": {
    ...
    "Body_troubleshoot_cw_agent": { // <-- 새 SAW 런북의 구성요소 정보를 추가합니다.
      "properties": {
        "instance_id": {
          "type": "string",
          "title": "Instance Id",
          "description": "The ID of the Amazon EC2 instance you want to troubleshoot the Amazon CloudWatch Agent on."
          // <-- 에이전트가 본 설명을 참고하여 사용자에게 대상 EC2 인스턴스 ID를 요청할 수 있습니다.
        },
        "s3_upload_bucket": {
          "type": "string",
          "title": "S3 Upload Bucket",
          "description": "The name of an Amazon S3 bucket to upload the collected Amazon CloudWatch Agent logs."
        }
      },
      "type": "object",
      "required": ["instance_id", "s3_upload_bucket"],
      "title": "Body_troubleshoot_cw_agent"
    }
  }, // <-- 새 SAW 런북의 구성요소 정보를 추가합니다.
  ...
}

3단계: Lambda 함수 정의

lambda/saw_troubleshooting/app.py 파일에 새로운 SAW 런북을 지원하기 위한 새 엔드포인트 (Lambda 함수)를 추가합니다.

함수는 아래와 같은 역할을 수행합니다

Bedrock 에이전트로부터 파라미터를 받아 검증
파라미터를 SAW 런북이 요구하는 형식으로 변환
execute_automation 헬퍼 함수를 통해 SAW 런북 실행
런북 실행 결과를 Bedrock 에이전트에 반환

@app.post("/troubleshoot-cw-agent", description="Troubleshoot Amazon CloudWatch Agent on your Amazon EC2 instance.")
@tracer.capture_method
def troubleshoot_cw_agent(
    instance_id: str = Body(description="The ID of the Amazon EC2 instance you want to troubleshoot the Amazon CloudWatch Agent on."),
    s3_upload_bucket: str = Body(description="The name of an Amazon S3 bucket to upload the collected Amazon CloudWatch Agent logs.")
) -> Annotated[dict, Body(description="The output of the Automation execution")]:
    """
    The AWSSupport-TroubleshootCloudWatchAgent runbook automates troubleshooting the Amazon CloudWatch Agent on your Amazon Elastic Compute Cloud (Amazon EC2) instances.
    ...
    AWSSupport-TroubleshootCloudWatchAgent 런북을 실행하여 EC2 인스턴스의 CloudWatch Agent 문제를 자동으로 진단합니다.
    """
    
    return execute_automation(
        'AWSSupport-TroubleshootCloudWatchAgent',                            # 실행할 SAW 런북의 이름
        {'InstanceId': [instance_id], 'S3UploadBucket': [s3_upload_bucket]}, # 런북에 전달할 파라미터
        'outputFindings'                                                     # 결과를 가져올 런북 실행 단계 이름
    )

4단계: IAM 권한 업데이트

Lambda 함수가 SAW 런북을 실행하려면 적절한 IAM 권한이 필요합니다. lib/bedrock-agent-saw-stack.ts 파일에서 SAW 런북 (본 경우 CloudWatch Agent 런북) 실행에 필요한 권한을 추가합니다.

주의사항

1단계에서 확인한 SAW 런북 실행을 위한 권한을 정확히 반영해야 합니다.
권한이 부족한 경우 런북 실행 중 AccessDenied 에러가 발생합니다.

{
    "Sid": "CloudWatchAgentPermissions",
    "Effect": "Allow",
    "Action": [
        // EC2 인스턴스 정보 조회
        "ec2:DescribeInstances",

        // IAM 권한 검증을 위한 작업 권한
        "iam:GetInstanceProfile",
        "iam:GetRole",
        "iam:ListAttachedRolePolicies",
        "iam:ListRolePolicies",
        "iam:GetRolePolicy",
        "iam:GetPolicy",
        "iam:GetPolicyVersion",
        "iam:SimulatePrincipalPolicy",

        // SSM 관련 작업 권한
        "ssm:DescribeInstanceInformation",
        "ssm:SendCommand",
        "ssm:GetCommandInvocation",
        "ssm:DescribeInstanceAssociationsStatus"
    ],
    "Resource": "*"
}

5단계: CDK 솔루션 재배포 (스택 업데이트)

AWS CDK를 사용해 2~4단계에서 작업한 변경 사항들이 반영되도록 솔루션을 재배포합니다. 재배포가 완료되면, Amazon Bedrock 에이전트가 새로운 런북을 호출할 수 있게 됩니다.

$ cdk deploy --all

만약 본 솔루션 배포가 처음인 경우, 지난 글의 ‘사전 요구사항’ 및 ‘솔루션 배포 섹션’을 참조하여 솔루션 배포에 도움을 받으시길 바랍니다.

6단계: Bedrock 에이전트 테스트

솔루션이 배포된 리전의 Amazon Bedrock Agents 콘솔로 이동하여 배포된 Amazon Bedrock 에이전트를 찾으세요. 에이전트와 상호작용하여 EC2 인스턴스에서 구동 중인 CloudWatch 에이전트의 문제를 진단하고 해결할 수 있습니다. 다음과 같은 예시 질문을 사용할 수 있습니다.

내 Amazon EC2 인스턴스에서 동작하고 있는 CloudWatch Agent에 발생한 문제를 분석하고 싶어. CW Agent가 동작하고 있는 인스턴스 Id는 ‘<INSTANCE_ID>’ 이고 S3 버킷 ‘<BUCKET_NAME>’에 분석한 로그를 저장해주면 좋겠어.

아래의 스크린샷은 실제 AWSSupport-TroubleshootCloudWatchAgent 런북 통합 이후 확인한 동작 사항입니다.

사용자가 프롬프트 메시지를 통해 EC2 인스턴스 ‘i-0123456789abcdefg’에서 동작 중인 CloudWatch Agent에 문제가 발생하여 원인 진단 및 분석을 요청합니다.

Bedrock 에이전트는 사용자의 요청을 이해하고 새로 추가된 Lambda 함수 ‘troubleshoot_cw_agent’를 호출하여 AWSSupport-TroubleshootCloudWatchAgent 런북을 실행시킵니다.

AWS Systems Manager 콘솔에 접속하여 Automation 실행 목록을 확인하면 Bedrock 에이전트가 AWSSupport-TroubleshootCloudWatchAgent 런북을 실행시킨 것을 AWS Systems Manager 콘솔에서 확인할 수 있습니다.

SAW 런북 실행이 완료되면 Bedrock 에이전트가 그 결과를 확인하여 사용자에게 진단 내용 및 문제 해결을 위한 방법을 안내합니다.

이와 같은 방식으로 다른 SAW 런북들도 동일한 패턴을 따라 솔루션에 통합할 수 있습니다.

자원 정리

Amazon Bedrock 에이전트를 구현할 때 리소스 구성에 대한 추가 비용은 발생하지 않습니다. 하지만 Amazon Bedrock에서 임베딩 모델과 텍스트 모델을 호출할 때는 사용된 각 FM의 가격을 기준으로 비용이 발생합니다. 본 사용 사례에서는 Lambda 호출에 대한 비용도 발생합니다.

향후 요금이 발생하는 것을 방지하려면 AWS CDK에 의해 생성된 리소스를 삭제하세요. 리포지토리 폴더의 루트 경로에서 다음 명령어를 실행하여 리소스를 삭제할 수 있습니다.

$ npm run cdk destroy --all

결론

이번 글에서는 Amazon Bedrock Agents와 AWS Support Automation Workflows를 활용한 문제 해결 솔루션을 다양한 AWS 서비스로 확장하는 실전 통합 패턴을 상세히 살펴보았습니다. AWSSupport-TroubleshootCloudWatchAgent 런북을 예시로 OpenAPI 스키마 정의부터 Lambda 함수 구현, IAM 권한 설정까지의 전체 통합 과정을 단계별로 다루었습니다.

본 글에서 소개한 6단계 통합 패턴을 따르면 AWS에서 제공하는 300개 이상의 SAW 런북을 동일한 방식으로 통합할 수 있습니다. 이 반복 가능한 프로세스를 통해 조직의 특정 요구사항에 맞춰 EC2, EKS, RDS, VPC, CloudWatch, Lambda, Elastic Beanstalk 등 AWS 인프라 전반에 걸친 포괄적인 문제 해결 플랫폼을 구축할 수 있습니다.

이 솔루션의 핵심 가치는 AWS Support Engineering 팀의 전문 지식이 담긴 표준화된 런북들을 자연어 인터페이스를 통해 접근할 수 있다는 점입니다. 사내 운영팀은 복잡한 CLI 명령어 입력이나 콘솔 탐색 없이도 “EC2 인스턴스의 CloudWatch Agent에 발생한 문제를 진단해줘”와 같은 간단한 요청만으로 체계적인 문제 해결 프로세스를 시작할 수 있습니다. 또한 각 런북의 실행 결과를 Amazon Bedrock의 Foundation Model이 분석하여 기술적 출력을 이해하기 쉬운 형태로 변환하고, 추가적인 해결 방안까지 제시함으로써 운영 효율성을 크게 향상시킬 수 있습니다.

특히 이 솔루션은 AWS 계정에 Bedrock 에이전트를 직접 배포하여 사용함으로써, 트러블슈팅 에이전트가 직접 계정 내 리소스에 접근하여 이슈 원인을 파악하고 해결 방안을 제시한다는 점에서 차별화됩니다. 주로 일반적인 이슈 상황에 대한 질의 응답만 가능한 다른 GenAI 도구와는 달리, AWS 계정 내 리소스의 상태를 직접 파악하고 그에 따른 문제 해결에 보다 적극적인 도움을 받을 수 있습니다. 이는 단순한 자동화를 넘어서 지능형 운영 지원 시스템으로의 진화를 의미하며, 조직의 AWS 운영 성숙도를 한 단계 끌어올리는 데 기여할 것입니다.

이 솔루션을 시작점으로 활용하여 조직의 요구에 맞는 포괄적인 문제 해결 플랫폼을 구축하시는 데 도움을 얻으시길 바랍니다.

그럼, 즐거운 코딩 되시길 바랍니다!

AWS 기술 블로그