Terraform을 사용하여 AWS DevOps Agent 배포하기
요약
Terraform을 사용하여 AWS DevOps Agent를 배포하는 방법을 안내합니다. 이 AI 기반 서비스는 운영 장애 조사, 근본 원인 분석 및 예방 조치 권장을 통해 SRE 팀의 운영을 지원합니다.
핵심 포인트
- AWS DevOps Agent는 AI 기반 운영 어시스턴트 역할을 수행함
- 로그, 메트릭, 트레이스 및 인프라 변경 사항의 상관 분석 지원
- 에이전트 스페이스를 통해 접근 범위 및 논리적 경계 제어 가능
- Terraform 1.0 이상 및 AWS CLI를 활용한 인프라 자동화 배포
AWS DevOps Agent 소개
AWS DevOps Agent는 운영 장애를 조사하고, 텔레메트리 (telemetry) 및 인프라 변경 사항을 상관 분석하며, 유력한 근본 원인을 식별하고, 예방적 개선 사항을 권장하도록 설계된 AI 기반 운영 서비스입니다.
이 서비스는 AWS 리소스, 관측성 (observability) 플랫폼, 코드 저장소, CI/CD 시스템, 런북 (runbooks) 및 티켓팅 시스템과 함께 작동할 수 있습니다.
AWS DevOps Agent는 DevOps 및 사이트 신뢰성 엔지니어링 (Site Reliability Engineering, SRE) 팀을 위한 운영 어시스턴트 역할을 합니다.
주요 기능:
- AWS 리소스 및 리소스 간의 관계 발견
- 애플리케이션 토폴로지 (topology) 구축
- 로그, 메트릭 (metrics), 트레이스 (traces), 배포 및 구성 변경 사항의 상관 분석
- 장애 조사
- 근본 원인 분석 (root-cause analysis) 생성
- 복구 및 예방 조치 권장
- 외부 관측성 및 엔지니어링 도구와 통합
AWS는 에이전트가 접근할 수 있는 범위를 제어하는 논리적 경계로 에이전트 스페이스 (Agent Space)를 정의합니다. 각 에이전트 스페이스는 고유한 AWS 계정 액세스, 외부 통합, 운영자 권한, 조사 데이터 및 채팅 기록을 가집니다.
에이전트 스페이스는 일반적으로 애플리케이션, 비즈니스 서비스, 플랫폼 또는 온콜 (on-call) 소유권 경계와 일치해야 합니다.
지원되는 AWS 리전 (Regions)
AWS 계정이 에이전트 스페이스와 연결되면 AWS DevOps Agent는 여러 리전에 걸쳐 리소스를 조사할 수 있습니다. 모든 워크로드 리전마다 별도의 에이전트 스페이스를 생성할 필요는 없습니다.
하지만 에이전트 스페이스 자체는 지원되는 리전에 생성되어야 합니다.
이 글을 작성하는 시점을 기준으로 지원되는 리전은 다음과 같습니다:
us-east-1
us-west-2
ca-central-1
...
운영 기능은 모든 지원되는 리전에서 사용할 수 있지만, 일부 프리뷰 (preview) 기능은 리전별 가용성이 더 제한적일 수 있습니다.
유럽 워크로드의 경우, 지연 시간 (latency), 데이터 레지던시 (data residency) 및 조직 요구 사항에 따라 eu-west-1 또는 eu-central-1이 적절할 수 있습니다.
배포 요구 사항
시작하기 전에 다음 사항을 확인하십시오:
- Terraform 1.0 이상
- AWS CLI 설치됨
- AWS CLI 자격 증명 (credentials) 설정됨
- IAM 역할 (roles) 및 정책 (policies) 생성 권한
- AWS DevOps Agent 리소스 생성 권한
- Agent Space를 위한 하나의 AWS 계정
- 선택 사항: 하나 이상의 추가 워크로드 (workload) 계정
설치된 도구 확인:
- terraform version
terraform version
Terraform v1.15.8
- AWS CLI 버전
aws --version
aws-cli/2.24.0 Python/3.12.6 Windows/11 exe/AMD64
- AWS 신원 (identity) 확인:
aws sts get-caller-identity
예상 출력:
{
...
로컬 테스트를 위해 AWS CLI 프로필 (profile)을 사용할 수 있습니다:
`aws configure --profile devops-agent-admin`
프로덕션 CI/CD의 경우, 장기 실행 액세스 키 (long-lived access keys)를 저장하는 대신 OpenID Connect 또는 AWS 역할 (role)을 통해 임시 자격 증명을 사용하십시오.
## Terraform 프로젝트 구조
소규모 환경의 경우 다음 구조를 사용할 수 있습니다:
aws-devops-agent-terraform/
├── backend.tf
├── versions.tf
...
대규모 환경의 경우, 배포를 재사용 가능한 모듈 (module)로 추출하십시오:
aws-devops-agent-terraform/
├── modules/
│ └── devops-agent/
...
## 단계
**1단계: Terraform 버전 설정**
versions.tf 파일을 생성합니다:
terraform {
required_version = ">= 1.6.0"
...
AWS DevOps Agent 리소스는 AWS Cloud Control을 통해 노출되므로 awscc 프로바이더 (provider)가 중요합니다.
time 프로바이더 (provider)는 Agent Space를 생성하기 전 IAM 전파 지연 (propagation delays)을 처리하는 데 사용할 수 있습니다.
**2단계: 프로바이더 설정**
providers.tf 파일을 생성합니다:
provider "aws" {
region = var.aws_region
profile = var.aws_profile
...
로컬 개발의 경우 프로필 (profile) 사용이 허용됩니다. CI/CD에서는 프로필을 제거하고 프로바이더가 파이프라인 환경으로부터 임시 자격 증명을 가져오도록 하십시오:
provider "aws" {
region = var.aws_region
...
아래와 같이 프로바이더 내부에 액세스 키 (access keys)를 직접 넣는 것은 피하십시오:
provider "aws" {
access_key = "AKIA..."
secret_key = "..."
...
**3단계: 변수 정의**
variables.tf를 생성합니다:
variable "aws_region" {
description = "Agent Space가 생성될 AWS Region입니다."
type = string
...
**4단계: 공통 태그 (common tags) 생성**
locals.tf를 생성합니다:
locals {
common_tags = merge(
{
...
태그는 다음과 같은 작업에 도움이 됩니다:
- 소유권 (Ownership)
- 비용 할당 (Cost allocation)
- 장애 라우팅 (Incident routing)
- 컴플라이언스 (Compliance)
- Terraform 리소스 검색 (Terraform resource discovery)
- 운영 거버넌스 (Operational governance)
**5단계: 현재 AWS 계정 정보 가져오기**
data.tf를 생성합니다:
data "aws_caller_identity" "current" {}
data "aws_partition" "current" {}
...
이러한 데이터 소스 (data sources)를 사용하면 AWS 계정 ID, 파티션 (partition), 그리고 리전 (Region)을 하드코딩하는 것을 방지할 수 있습니다.
**6단계: DevOps Agent IAM 역할 생성**
AWS DevOps Agent는 서비스가 맡을 수 있는(assume) IAM 역할 (role)이 필요합니다.
iam-agent.tf를 생성합니다:
data "aws_iam_policy_document" "devops_agent_assume_role" {
statement {
sid = "AllowAWSDevOpsAgent"
...
> 배포 전에 공식 AWS 문서에서 현재 AWS 관리형 정책 (AWS-managed policy) 이름을 확인하십시오. 서비스 정책은 기능이 추가됨에 따라 변경될 수 있습니다.
**7단계: 운영자 웹 애플리케이션 역할 생성**
운영자 역할 (operator role)은 엔지니어가 AWS DevOps Agent 웹 애플리케이션을 통해 수행할 수 있는 작업을 제어합니다.
iam-operator.tf를 생성합니다:
data "aws_iam_policy_document" "operator_assume_role" {
statement {
sid = "AllowAWSDevOpsAgentOperatorApp"
...
에이전트 역할 (agent role)과 운영자 역할 (operator role)을 분리하는 것이 중요합니다:
- **에이전트 역할 (agent role)**은 에이전트가 검사할 수 있는 인프라와 텔레메트리 (telemetry)를 제어합니다.
- **운영자 역할 (operator role)**은 사람이 Agent Space 웹 애플리케이션에서 수행할 수 있는 작업을 제어합니다.
이러한 책임들을 하나의 역할로 결합하지 마십시오.
**8단계: IAM 전파 (propagation) 처리**
IAM은 최종 일관성 (eventually consistent) 모델을 따릅니다. DevOps Agent 서비스는 Agent Space가 생성되는 동안 역할 신뢰 정책 (role trust policies)을 검증합니다.
짧은 지연 시간을 추가합니다:
resource "time_sleep" "wait_for_iam_propagation" {
create_duration = "30s"
...
AWS 공식 Terraform 예제 또한 IAM 전파 (IAM propagation)를 고려하고 있습니다. 만약 역할 검증 (role validation)이 여전히 실패한다면, 잠시 기다린 후 `terraform apply`를 다시 실행함으로써 Terraform이 기존 IAM 리소스로부터 작업을 계속할 수 있도록 할 수 있습니다.
**단계 9: Agent Space 생성**
`devops-agent.tf` 파일을 생성합니다:
resource "awscc_devopsagent_agent_space" "this" {
name = var.agent_space_name
description = var.agent_space_description
...
정확한 리소스 스키마 (resource schema)는 AWS Cloud Control 리소스가 진화함에 따라 변경될 수 있습니다. 다음 명령어로 현재 인자 (arguments)를 확인하십시오:
`terraform providers schema -json`
또한 리소스 문서를 검사할 수도 있습니다:
terraform init
terraform providers
**단계 10: 모니터링 계정 연결**
계정 연결 (account association)은 현재 AWS 계정을 Agent Space에 연결합니다.
`associations.tf` 파일을 생성합니다:
resource "awscc_devopsagent_association" "monitoring_account" {
agent_space_id = awscc_devopsagent_agent_space.this.agent_space_id
...
AWS Cloud Control 스키마는 프로바이더 (provider) 릴리스마다 다를 수 있으므로, 구성을 게시하거나 적용하기 전에 속성 이름 (property names)을 현재 Terraform Registry 스키마와 비교하십시오.
정확한 `awscc_devopsagent_association` 구성을 위한 가장 안전한 기준점은 AWS 공식 샘플입니다. AWS는 이 연결이 모니터링 계정을 Agent Space에 링크함을 확인해 줍니다.
**단계 11: 출력 (outputs) 정의**
`outputs.tf` 파일을 생성합니다:
output "agent_space_id" {
description = "AWS DevOps Agent Space ID."
value = awscc_devopsagent_agent_space.this.agent_space_id
...
**단계 12: 환경 설정**
`terraform.tfvars.example` 파일을 생성합니다:
aws_region = "eu-west-1"
aws_profile = "devops-agent-admin"
...
파일을 복사합니다:
`cp terraform.tfvars.example terraform.tfvars`
`terraform.tfvars` 파일에 계정별 데이터나 민감한 정보가 포함된 경우, 절대로 커밋 (commit)하지 마십시오.
`.gitignore`에 추가합니다:
.terraform/
*.tfstate
.tfstate.
...
.terraform.lock.hcl 파일을 커밋하여 개발 및 CI/CD 환경 전반에서 동일한 프로바이더 (provider) 버전이 사용되도록 하십시오.
**Step 13: Agent Space 배포하기**
코드 포맷팅 (Format):
terraform fmt -recursive
Terraform 초기화 (Initialize):
...
구성 (configuration) 검증:
terraform validate
저장된 플랜 (plan) 생성:
terraform plan -
-out=tfplan
플랜을 주의 깊게 검토하고 적용 (apply) 하십시오:
terraform apply tfplan
배포 후, 출력값 (outputs)을 확인하십시오:
terraform output
예시:
agent_space_id = "abc123"
agent_space_arn = "arn:aws:aidevops:eu-west-1:123456789876:agentspace/abc123"
agent_space_name = "payments-production"
...
**Step 14: 배포 확인**
AWS CLI를 사용하십시오:
aws devops-agent get-agent-space -
--agent-space-id "$(terraform output -raw agent_space_id)" -
--region "$(terraform output -raw aws_region 2>/dev/null || echo eu-west-1)"
또는:
AGENT_SPACE_ID=$(terraform output -raw agent_space_id)
aws devops-agent get-agent-space
...
IAM 역할 (roles)이 존재하는지도 확인할 수 있습니다:
aws iam get-role -
--role-name "$(terraform output -raw devops_agent_role_arn | awk -F/ '{print $NF}')"
그 다음 AWS DevOps Agent 콘솔을 열어 다음 사항을 확인하십시오:
- Agent Space가 활성 (active) 상태인지.
- 운영자 앱 (operator app)이 활성화되었는지.
- 현재 AWS 계정이 연결되었는지.
- 리소스 검색 (Resource discovery)이 시작되었는지.
- 애플리케이션 토폴로지 (Application topology)가 채워지고 있는지.
# 배포 모범 사례 (Deployment Best Practices)
**1) 원격 Terraform 백엔드 (remote Terraform backend) 사용**
운영 환경의 Terraform 상태 (state)를 엔지니어의 노트북에만 저장하지 마십시오.
S3 백엔드 예시:
terraform {
backend "s3" {
bucket = "company-terraform-state-prod"
...
백엔드 버킷은 다음 사항을 갖추어야 합니다:
- 버전 관리 (Versioning) 활성화
- 암호화 (Encryption) 활성화
- 퍼블릭 액세스 차단
- 엄격한 버킷 정책 (bucket policy)
- 필요한 경우 액세스 로깅 (Access logging)
- 상태 잠금 (State locking) 활성화
- 백업 및 복구 절차
Terraform은 아직 존재하지 않는 백엔드 (backend)를 사용할 수 없으므로, 백엔드를 별도로 부트스트랩 (Bootstrap) 하십시오.
**2) 관측성 데이터 (observability data) 보호**
에이전트 (agent)는 로그 (logs), 메트릭 (metrics), 트레이스 (traces), 티켓 메타데이터 (ticket metadata), 리소스 태그 (resource tags) 및 기타 운영 정보를 처리할 수 있습니다.
다음 항목을 로그, 태그 또는 인시던트 설명 (incident descriptions) 내부에 포함하지 마십시오:
- 비밀번호 (Passwords)
- API 키 (API keys)
- 인증 토큰 (Authentication tokens)
- 고객 개인 정보 (Customer personal information)
- 결제 카드 정보 (Payment card information)
- 개인 인증서 (Private certificates)
AWS는 데이터가 요약될 때 개인 식별 정보 (personally identifiable information)가 자동으로 제거되지 않는다고 명시하고 있습니다. 따라서 민감한 정보는 관측성 시스템 (observability systems)에 진입하기 전에 반드시 마스킹 (redacted) 처리되어야 합니다.
# 일반적인 Terraform 문제
**1) 리소스 유형을 찾을 수 없음 (Resource type not found)**
예시:
Error: Invalid resource type
The provider hashicorp/aws does not support resource type
...
원인:
AWS DevOps Agent 리소스는 AWS Cloud Control 프로바이더 (provider)를 사용합니다.
해결 방법:
```hcl
required_providers {
awscc = {
source = "hashicorp/awscc"
...
사용 예시:
awscc_devopsagent_agent_space
awscc_devopsagent_association
공식 AWS 문서에 따르면 이러한 리소스에는 awscc 프로바이더가 필요합니다.
2) IAM 신뢰 정책 (trust policy) 검증 실패
예시:
The operator role trust policy is invalid
가능한 원인:
- IAM 전파 지연 (propagation delay)
- 잘못된 서비스 주체 (service principal)
- 잘못된 소스 계정 (source account)
- 잘못된 Agent Space ARN
- 작업을 차단하는 Organizations SCP (Service Control Policy)
해결 방법:
- 신뢰 정책 (trust policy)을 확인합니다.
- 현재 계정 ID를 확인합니다.
- IAM 전파를 위해 잠시 기다립니다.
terraform apply를 다시 실행합니다.- CloudTrail에서 거부된 API 호출을 확인합니다.
- Organizations SCP 및 권한 경계 (permission boundaries)를 검토합니다.
3) Agent Space 생성 중 액세스 거부 (Access denied)
호출자 신원 (caller identity)을 확인합니다:
aws sts get-caller-identity
그 다음, 배포 주체 (deployment principal)가 다음을 수행할 수 있는지 확인합니다:
- IAM 역할 (IAM roles) 생성
- IAM 정책 (IAM policies) 연결
- 필요한 IAM 역할 (IAM roles) 전달 (Pass)
- AWS DevOps Agent 리소스 생성
- 계정 연결 (account associations) 생성
- 필요한 경우 서비스 연결 역할 (service-linked roles) 생성
또한, 다음을 차단하는 SCP (Service Control Policy)가 있는지 확인하십시오:
aidevops:*
iam:CreateServiceLinkedRole
iam:PassRole
단순히 정책 문제를 우회하기 위해 제한 없는 관리자 권한 (unrestricted administrator access)을 영구적으로 부여하지 마십시오.
정리 (Cleanup)
환경을 제거하려면:
terraform plan -destroy -out=destroy.tfplan
terraform apply destroy.tfplan
또는:
terraform destroy
Agent Space를 삭제하면 조사 기록 (investigation history), 권장 사항 (recommendations) 및 관련 데이터가 영구적으로 삭제될 수 있습니다. 따라서 삭제하기 전에 보존 요구 사항 (retention requirements)을 검토하십시오.
AI 자동 생성 콘텐츠
본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기