AWS CodePipeline 실패 해결법: CI/CD 파이프라인 문제 분석부터 복구까지

CodePipeline 실패 해결법: CI/CD 파이프라인 문제 분석부터 복구까지

AWS CodePipeline은 서버리스 CI/CD 서비스로, 코드 변경부터 배포까지 자동화된 워크플로우를 제공합니다. 하지만 복잡한 인프라 환경에서 권한 오류, 아티팩트 누락, 빌드 스크립트 실패 등 다양한 문제가 발생할 수 있습니다. 이 가이드에서는 CodePipeline의 기본 구성부터 모니터링, 트러블슈팅, 예방 조치까지 단계별로 설명합니다. 실제 동작하는 코드 예제와 AWS 공식 문서를 참고해 문제를 체계적으로 해결하는 방법을 제시합니다.

1. 튜토리얼: CodePipeline 기본 구성 및 모니터링

1.1 CodePipeline 구조 이해

CodePipeline은 Source → Build → Deploy 3단계로 구성됩니다. 각 단계는 독립적인 액션으로 관리되며, 실패 시 롤백이 가능합니다. 예를 들어, GitHub에서 코드를 가져온 후 CodeBuild로 빌드하고, CodeDeploy로 EC2에 배포하는 파이프라인을 구성할 수 있습니다.

팁: 파이프라인 설계 시 각 단계의 출력 아티팩트가 다음 단계로 전달되는지 확인해야 합니다. S3 버킷 권한 문제로 아티팩트가 누락되면 파이프라인이 중단됩니다.

1.2 CloudWatch 로그 연동 방법

CodePipeline 자체의 로그는 제한적이므로, 각 단계에서 CloudWatch Logs를 활성화해야 합니다. 예를 들어 CodeBuild 프로젝트의 로그 그룹을 생성하려면 다음 AWS CLI 명령어를 사용합니다:

# CodeBuild 로그 그룹 생성
aws logs create-log-group \
  --log-group-name /aws/codebuild/your-project-name \
  --retention-in-days 14

1.3 파이프라인 상태 확인

  • AWS Management Console: CodePipeline 대시보드에서 각 액션의 상태(Success/Failed)를 확인할 수 있습니다. 실패 시 상세 오류 메시지를 클릭하면 원인(예: IAM 역할 권한 부족)이 표시됩니다.
  • AWS CLI: 다음 명령어로 파이프라인 실행 기록을 조회할 수 있습니다:

aws codepipeline get-pipeline-execution-history
–pipeline-name my-pipeline
–max-results 10


> **주의**: CLI 사용 시 `AWSCodePipelineRole` 정책이 IAM 사용자/역할에 부여되어 있어야 합니다.

---

## 2. 트러블슈팅: 주요 오류 유형 및 해결 전략

### 2.1 권한 오류 (IAM Role/Policy)
**증상**: `User is not authorized to perform` 오류 발생. **원인**: IAM 역할이나 정책이 특정 AWS 서비스(예: S3, CodeBuild) 접근 권한을 누락한 경우.

**해결 방법**:
1. IAM 콘솔에서 `CodePipeline-Service-Role` 또는 `CodeBuild-Service-Role`을 선택합니다.
2. `AWSCodePipelineRole` 및 `AWSCodeBuildServiceRole` 정책이 연결되었는지 확인합니다.
3. S3 버킷 접근 권한이 필요한 경우 `AmazonS3ReadOnlyAccess`를 추가합니다.

```json
// IAM Policy 예시: S3 접근 권한 추가
{
"Version": "2012-10-17",
"Statement": [
  {
    "Effect": "Allow",
    "Action": [
      "s3:GetObject",
      "s3:PutObject"
    ],
    "Resource": "arn:aws:s3:::your-bucket-name/*"
  }
]
}

2.2 아티팩트 누락 (S3 버킷 권한)

증상: Artifact not found 오류 발생. 원인: S3 버킷 정책 또는 CodePipeline의 아티팩트 스토어 설정이 잘못된 경우.

해결 방법:

  1. S3 버킷 정책에서 CodePipeline 서비스 프린시팔(codepipeline.amazonaws.com)에 s3:GetObject 및 s3:PutObject 권한을 부여합니다.
  2. CodePipeline 콘솔에서 아티팩트 스토어 위치를 확인하고, 필요시 버킷을 변경합니다.
# CloudFormation 템플릿 예시: S3 버킷 정책
Resources:
  PipelineBucketPolicy:
    Type: AWS::S3::BucketPolicy
    Properties:
      Bucket: !Ref PipelineBucket
      PolicyDocument:
        Statement:
          - Effect: Allow
            Principal:
              Service: codepipeline.amazonaws.com
            Action:
              - s3:GetObject
              - s3:PutObject
            Resource: !Join ['', [!GetAtt PipelineBucket.Arn, '/*']]

2.3 빌드 스크립트 오류

증상: CodeBuild 단계에서 Command failed 오류 발생. 원인: 빌드 스크립트(예: buildspec.yml)의 문법 오류 또는 의존성 누락.

해결 방법:

  1. buildspec.yml 파일을 로컬에서 테스트합니다.
  2. CodeBuild 로그에서 실패한 단계를 확인합니다.
  3. 필요한 경우 pip install 또는 npm install 명령어를 추가합니다.
# buildspec.yml 예시
version: 0.2
phases:
  install:
    runtime-versions:
      python: 3.9
    commands:
      - pip install -r requirements.txt
  build:
    commands:
      - python app.py test
artifacts:
  files:
    - dist/*

3. 검증 및 예방 조치

3.1 테스트 파이프라인 구축

실제 파이프라인을 변경하기 전, 테스트 브랜치를 사용해 검증 환경을 구축합니다. 예를 들어, dev 브랜치에서 파이프라인을 실행한 후 성공 시 main 브랜치로 병합하는 전략을 적용할 수 있습니다.

3.2 SNS 연동으로 실시간 알림 설정

파이프라인 실패 시 Slack 또는 이메일로 알림을 받으려면 SNS 토픽을 연동합니다.

# SNS 토픽 생성 및 CodePipeline에 연결
SNS_TOPIC_ARN=$(aws sns create-topic --name codepipeline-alerts \
  --query 'TopicArn' --output text)

aws codepipeline update-pipeline \
  --pipeline-name my-pipeline \
  --pipeline-configuration \
    '{