Skip to content

troubleshooting aws hub

Jump to bottom
JJong-03 edited this page Jun 18, 2026 · 6 revisions

트러블슈팅 — AWS Hub

Hub build/destroy 과정에서 발생한 AWS 관련 장애와 해결 방법을 정리한다.

MFA helper / AWS STS 접근 실패

현상

Codex sandbox 환경에서 Hub build 실행 중 MFA token 파일 쓰기와 AWS STS 접근이 실패했다.

/home/vicbear/.token_file: Read-only file system
aws: [ERROR]: Could not connect to the endpoint URL: "https://sts.ap-south-1.amazonaws.com/"

원인

기본 sandbox가 home 디렉터리 파일 쓰기와 외부 AWS API 네트워크 접근을 제한했다.

해결

Codex tooling에서는 AWS build 명령을 elevated execution으로 실행한다. 수동 운영 시에는 일반 로컬 shell에서 실행한다. AWS API, MFA token 파일, Terraform backend/state 접근이 필요한 명령은 sandbox 제약을 사전 점검한다.

EKS CloudWatch Log Group 중복 생성 실패

현상

Hub Terraform apply 중 EKS CloudWatch Log Group이 이미 존재해 생성에 실패했다.

Error: creating CloudWatch Logs Log Group (/aws/eks/AEGIS-EKS/cluster):
ResourceAlreadyExistsException: The specified log group already exists

원인

CloudWatch Log Group은 AWS에 이미 존재했으나 Terraform state entry가 tainted 상태여서 replacement 생성을 시도했다.

해결

AWS 리소스가 정상이고 state만 tainted라면 untaint한다.

terraform -chdir=infra/hub untaint 'module.eks.aws_cloudwatch_log_group.this[0]'

state에 없고 AWS에만 있으면 import한다.

terraform -chdir=infra/hub import \
  'module.eks.aws_cloudwatch_log_group.this[0]' \
  '/aws/eks/AEGIS-EKS/cluster'

재발 방지

Hub build preflight에서 tainted resource를 apply 전에 감지한다.

EC2 Security Group read-after-write UnknownError

현상

Terraform apply 중 막 생성된 Security Group 조회가 실패했다.

Error: reading Security Group (sg-...):
operation error EC2: DescribeSecurityGroups, StatusCode: 400, api error UnknownError

원인

AWS EC2 API의 read-after-write 시 일시적인 UnknownError.

해결

일시 오류이면 build를 재실행한다. 반복되면 AWS CLI로 직접 조회해 state와 비교한다.

aws ec2 describe-security-groups --group-ids sg-... --region ap-south-1

IAM ListRolePolicies timeout (408)

현상

Foundation Terraform refresh 중 IAM role inline policy 조회가 timeout으로 실패했다.

Error: reading inline policies for IAM role AEGIS-GitHubActions-ECRPush
operation error IAM: ListRolePolicies, StatusCode: 408, api error UnknownError

해결

재시도하고, 반복되면 Terraform parallelism을 낮춘다.

TF_CLI_ARGS_plan="-parallelism=1" \
TF_CLI_ARGS_apply="-parallelism=1" \
scripts/build/build-hub.sh

직접 IAM 상태 확인:

aws iam list-role-policies --role-name AEGIS-GitHubActions-ECRPush
aws iam get-role --role-name AEGIS-GitHubActions-ECRPush

CloudWatch ListTagsForResource timeout

현상

Hub Terraform refresh 중 EKS CloudWatch Log Group tag 조회가 반복 실패했다.

Error: listing tags for CloudWatch Logs Log Group
operation error CloudWatch Logs: ListTagsForResource, StatusCode: 408, api error UnknownError

해결

AWS API timeout 계열이므로 재시도하거나 parallelism을 낮춘다.

AWS_RETRY_MODE=adaptive AWS_MAX_ATTEMPTS=10 \
TF_CLI_ARGS_apply="-parallelism=1" \
scripts/build/build-hub.sh

Terraform apply 일반 재시도 원칙

AWS API timeout(408), read-after-write 일시 오류는 대부분 재실행으로 해소된다.

  1. 동일 명령을 재실행한다.
  2. 반복되면 TF_CLI_ARGS_apply="-parallelism=1"로 동시성을 낮춘다.
  3. state와 실제 AWS resource 불일치가 의심되면 terraform show, aws cli로 직접 확인한다.
  4. tainted resource는 untaint 또는 import로 교정한다.

Terraform validate 자체가 provider schema/handshake 문제로 실패하면 Terraform 1.15.0+ 환경인지 먼저 확인한다. 특히 infra/data-pipeline 등 A-side root는 최신 Terraform 기준으로 validate를 재실행한 뒤 실제 코드 또는 state 문제인지 판단한다.

Terraform backend migration / state ownership

현상

  • terraform init이 새 backend로 migration 또는 state copy를 제안한다.
  • terraform state list가 비어 있거나 예상과 다른 리소스를 표시한다.
  • Hub가 Foundation output을 읽지 못한다.
  • 같은 AWS 리소스를 생성하려 하거나 대량 destroy가 plan에 나타난다.

원인

현재 통합 기준 infra/foundation, infra/hub, infra/data-pipeline, infra/reporting은 S3 backend를 사용하며 root별 key로 state를 분리한다. 증상이 발생하면 backend key, remote state output, state list, 실제 AWS 리소스 소유권이 서로 일치하는지 먼저 확인한다.

해결 원칙

backend migration은 apply/destroy와 별도 변경 작업으로 다룬다. 이미 S3 backend가 적용된 root에서는 임의로 terraform init -migrate-state를 반복하지 않는다. backend 변경이 필요한 경우 다음 조건이 모두 충족된 뒤 별도 작업으로 수행한다.

  1. 유효한 AWS/MFA 인증으로 refresh-only plan 완료
  2. normal plan에 예상하지 않은 변경과 destroy 없음
  3. state backup 생성
  4. 대상 S3 bucket/key 소유권과 기존 객체 확인
  5. remote-state 설정 변경 계획 승인
  6. migration 후 state list와 plan No changes 검증

S3 bucket drift, MFA explicit deny, provider schema/handshake 오류가 확인되면 해소 전 migration/apply/destroy를 중단한다.

Terraform init 실패

점검

terraform -chdir=infra/foundation init
terraform -chdir=infra/hub init
terraform -chdir=infra/data-pipeline init
terraform -chdir=infra/reporting init

init 실패를 -reconfigure나 .terraform 삭제로 즉시 우회하지 않는다. 먼저 오류가 provider download, backend credentials, lock, backend 변경 감지 중 무엇인지 구분한다.

안전한 처리

  • AWS explicit deny: MFA 조건을 만족하는 session으로 재시도
  • backend 접근 실패: bucket/region/key와 IAM 권한 확인
  • lock 충돌: 실제 실행 중인 Terraform이 없는지 확인 후 lock owner 조사
  • backend 설정 변경: migration 승인 없이는 -migrate-state 금지
  • S3 backend root: bucket/region/key와 lock 상태를 확인하고 임의 migration을 반복하지 않음

init 후에는 항상 terraform state list로 기대한 state를 읽었는지 확인한다.

CloudInfraSlowCollector EKS access 401

현상

SlowCollector 로그나 CLOUD#infra/LATEST.slow에 EKS/Kubernetes 401, node/pod/ArgoCD 조회 실패가 나타난다. Hub를 재생성한 뒤 주로 발생한다.

원인

Hub EKS cluster가 새 ID로 생성됐지만 data-pipeline의 SlowCollector IAM role에 대한 EKS access entry와 AmazonEKSAdminViewPolicy association이 새 cluster에 적용되지 않았다.

해결

Hub와 data-pipeline state가 모두 올바른지 먼저 확인한다.

scripts/build/reconcile-data-pipe-eks-access.sh --plan-only
# infra/data-pipeline/tfplan.eks-access 검토
scripts/build/reconcile-data-pipe-eks-access.sh

정상적인 build-hub.sh는 SlowCollector role이 존재하면 이 reconcile을 자동 실행한다. 자동 경로를 건너뛴 경우 RECONCILE_DATA_PIPE_EKS_ACCESS 값도 확인한다.

스크립트는 FastCollector의 현재 Lambda environment에서 필수 Terraform 변수를 복원하고 EKS access 두 리소스만 target apply한다. 이후 전체 plan이 No changes가 아니면 실패하므로 남은 diff를 별도로 해결한다.

검증:

aws logs tail /aws/lambda/AEGIS-Lambda-CloudInfraSlowCollector --since 10m

tfplan.eks-access는 민감한 plan artifact이므로 저장소에 커밋하지 않는다.

관련 문서

Aegis-Pi Wiki

홈 · 대표 문서 목록은 홈의 문서 탐색 표 참조

시작하기

요구사항

핵심 개념

아키텍처

컴포넌트 (Edge → Cloud → Dashboard)

Dashboard & 운영

시나리오 · 사례 · 참조

Clone this wiki locally