🧠 1. 핵심 개념부터 잡고 가자

파이프라인 구성하기 전에, 각 서비스가 뭘 하는 녀석인지 정확히 알고 가야 해. 개념 없이 따라 하면 나중에 뭔가 안 될 때 왜 안 되는지 전혀 모르거든. 😤

🔨 AWS CodeBuild란?

CodeBuild는 AWS에서 제공하는 완전 관리형 빌드 서비스야. 쉽게 말하면, 소스 코드를 받아서 컴파일하고, 테스트 돌리고, 배포 가능한 아티팩트(결과물)를 만들어주는 서비스야.

중요한 특징들을 정리하면:

🚀 AWS CodeDeploy란?

CodeDeploy는 AWS에서 제공하는 완전 관리형 배포 서비스야. EC2 인스턴스, Lambda 함수, ECS 컨테이너 등 다양한 컴퓨팅 환경에 애플리케이션을 자동으로 배포해줘.

⚙️ AWS CodePipeline이란?

CodeBuild와 CodeDeploy를 연결해주는 오케스트레이터야. 소스 변경 감지 → 빌드 → 배포 단계를 하나의 파이프라인으로 묶어서 자동으로 실행해줘. 오늘 구성할 파이프라인의 "뼈대"라고 보면 돼.

🛠️ 2. 파이프라인 구성 전 사전 준비

본격적으로 파이프라인 만들기 전에 준비해야 할 것들이 있어. 이걸 빠뜨리면 나중에 "왜 안 되지?" 하면서 삽질하게 되니까 꼼꼼하게 체크하자. 📋

✅ 필요한 AWS 리소스 목록

🔐 IAM 역할 설정 (가장 중요!)

IAM 설정이 잘못되면 파이프라인이 아예 동작을 안 해. 각 서비스별로 필요한 권한을 정확히 부여해야 해.

① CodeBuild 서비스 역할에 필요한 정책:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "arn:aws:logs:*:*:*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:GetObjectVersion",
        "s3:PutObject",
        "s3:GetBucketAcl",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::your-artifact-bucket",
        "arn:aws:s3:::your-artifact-bucket/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "codebuild:CreateReportGroup",
        "codebuild:CreateReport",
        "codebuild:UpdateReport",
        "codebuild:BatchPutTestCases"
      ],
      "Resource": "arn:aws:codebuild:*:*:report-group/*"
    }
  ]
}

② CodeDeploy 서비스 역할에 필요한 정책:

CodeDeploy 서비스 역할은 AWS 관리형 정책인 AWSCodeDeployRole을 사용하면 돼. 이 정책에는 EC2, Auto Scaling, ELB, CloudWatch 등에 대한 필요한 권한이 모두 포함되어 있어.

③ EC2 인스턴스 프로파일에 필요한 정책:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:GetObjectVersion",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::your-artifact-bucket",
        "arn:aws:s3:::your-artifact-bucket/*",
        "arn:aws:s3:::aws-codedeploy-*"
      ]
    }
  ]
}

🤖 EC2에 CodeDeploy Agent 설치

EC2 배포를 사용한다면 대상 서버에 반드시 CodeDeploy Agent를 설치해야 해. 이 에이전트가 CodeDeploy 서비스로부터 배포 명령을 받아서 실제 작업을 수행하거든.

# Amazon Linux 2 / Amazon Linux 2023 기준
sudo yum update -y
sudo yum install -y ruby wget

# CodeDeploy Agent 설치 스크립트 다운로드
cd /home/ec2-user
wget https://aws-codedeploy-ap-northeast-2.s3.ap-northeast-2.amazonaws.com/latest/install

# 실행 권한 부여 및 설치
chmod +x ./install
sudo ./install auto

# 서비스 시작 및 상태 확인
sudo service codedeploy-agent start
sudo service codedeploy-agent status

Ubuntu 서버라면 이렇게 설치해:

# Ubuntu 기준
sudo apt-get update
sudo apt-get install -y ruby-full wget

cd /home/ubuntu
wget https://aws-codedeploy-ap-northeast-2.s3.ap-northeast-2.amazonaws.com/latest/install

chmod +x ./install
sudo ./install auto

# 서비스 상태 확인
sudo systemctl status codedeploy-agent

🚀 6. CodeDeploy 애플리케이션 & 배포 그룹 설정

CodeDeploy는 애플리케이션과 배포 그룹 두 가지 개념으로 구성돼. 애플리케이션은 배포할 앱의 논리적 단위고, 배포 그룹은 실제 배포 대상 서버와 배포 설정을 담고 있어.

📱 CodeDeploy 애플리케이션 생성

# CodeDeploy 애플리케이션 생성
aws deploy create-application \
  --application-name my-app \
  --compute-platform Server

# 생성된 애플리케이션 확인
aws deploy get-application --application-name my-app

👥 배포 그룹 생성

배포 그룹 생성 시 가장 중요한 건 배포 대상 지정과 배포 설정이야. EC2 인스턴스를 태그로 지정하는 방법이 가장 일반적이야:

# 배포 그룹 생성 (EC2 태그 기반)
aws deploy create-deployment-group \
  --application-name my-app \
  --deployment-group-name my-app-production \
  --deployment-config-name CodeDeployDefault.OneAtATime \
  --ec2-tag-filters Key=Environment,Value=production,Type=KEY_AND_VALUE \
  --service-role-arn arn:aws:iam::123456789012:role/CodeDeployServiceRole \
  --auto-rollback-configuration enabled=true,events=DEPLOYMENT_FAILURE,DEPLOYMENT_STOP_ON_ALARM \
  --deployment-style deploymentType=IN_PLACE,deploymentOption=WITHOUT_TRAFFIC_CONTROL

⚙️ 배포 설정(Deployment Config) 종류

🔵🟢 Blue/Green 배포 설정

무중단 배포를 원한다면 Blue/Green 배포를 사용해야 해. ALB(Application Load Balancer)와 함께 사용하는 게 일반적이야:

# Blue/Green 배포 그룹 생성
aws deploy create-deployment-group \
  --application-name my-app \
  --deployment-group-name my-app-bluegreen \
  --deployment-config-name CodeDeployDefault.AllAtOnce \
  --service-role-arn arn:aws:iam::123456789012:role/CodeDeployServiceRole \
  --deployment-style deploymentType=BLUE_GREEN,deploymentOption=WITH_TRAFFIC_CONTROL \
  --load-balancer-info targetGroupInfoList=[{name=my-app-tg}] \
  --blue-green-deployment-configuration '{
    "terminateBlueInstancesOnDeploymentSuccess": {
      "action": "TERMINATE",
      "terminationWaitTimeInMinutes": 5
    },
    "deploymentReadyOption": {
      "actionOnTimeout": "CONTINUE_DEPLOYMENT",
      "waitTimeInMinutes": 0
    },
    "greenFleetProvisioningOption": {
      "action": "COPY_AUTO_SCALING_GROUP"
    }
  }' \
  --auto-scaling-groups my-app-asg

⚙️ 7. CodePipeline으로 전체 파이프라인 연결하기

드디어 모든 조각을 하나로 연결할 시간이야! 🎉 CodePipeline이 소스 → 빌드 → 배포 단계를 자동으로 실행하도록 설정해보자.

📄 파이프라인 JSON 정의

# pipeline.json
{
  "pipeline": {
    "name": "my-app-pipeline",
    "roleArn": "arn:aws:iam::123456789012:role/CodePipelineServiceRole",
    "artifactStore": {
      "type": "S3",
      "location": "your-artifact-bucket"
    },
    "stages": [
      {
        "name": "Source",
        "actions": [
          {
            "name": "SourceAction",
            "actionTypeId": {
              "category": "Source",
              "owner": "ThirdParty",
              "provider": "GitHub",
              "version": "1"
            },
            "configuration": {
              "Owner": "your-github-org",
              "Repo": "your-repo",
              "Branch": "main",
              "OAuthToken": "{{resolve:secretsmanager:github-token:SecretString:token}}",
              "PollForSourceChanges": "false"
            },
            "outputArtifacts": [
              {"name": "SourceOutput"}
            ]
          }
        ]
      },
      {
        "name": "Build",
        "actions": [
          {
            "name": "BuildAction",
            "actionTypeId": {
              "category": "Build",
              "owner": "AWS",
              "provider": "CodeBuild",
              "version": "1"
            },
            "configuration": {
              "ProjectName": "my-app-build"
            },
            "inputArtifacts": [
              {"name": "SourceOutput"}
            ],
            "outputArtifacts": [
              {"name": "BuildOutput"}
            ]
          }
        ]
      },
      {
        "name": "Deploy",
        "actions": [
          {
            "name": "DeployAction",
            "actionTypeId": {
              "category": "Deploy",
              "owner": "AWS",
              "provider": "CodeDeploy",
              "version": "1"
            },
            "configuration": {
              "ApplicationName": "my-app",
              "DeploymentGroupName": "my-app-production"
            },
            "inputArtifacts": [
              {"name": "BuildOutput"}
            ]
          }
        ]
      }
    ]
  }
}

# 파이프라인 생성
aws codepipeline create-pipeline --cli-input-json file://pipeline.json

# 파이프라인 상태 확인
aws codepipeline get-pipeline-state --name my-app-pipeline

# 파이프라인 수동 실행 (테스트용)
aws codepipeline start-pipeline-execution --name my-app-pipeline

🔔 GitHub Webhook 설정 (자동 트리거)

PollForSourceChanges: false로 설정하면 CodePipeline이 GitHub를 주기적으로 폴링하지 않아. 대신 Webhook을 설정해서 코드 푸시 시 즉시 파이프라인이 트리거되도록 해야 해. 이게 더 빠르고 효율적이야:

# Webhook 생성
aws codepipeline put-webhook \
  --webhook '{
    "name": "my-app-webhook",
    "targetPipeline": "my-app-pipeline",
    "targetAction": "SourceAction",
    "filters": [
      {
        "jsonPath": "$.ref",
        "matchEquals": "refs/heads/main"
      }
    ],
    "authentication": "GITHUB_HMAC",
    "authenticationConfiguration": {
      "SecretToken": "your-webhook-secret"
    }
  }'

# Webhook 등록 (GitHub에 실제로 등록)
aws codepipeline register-webhook-with-third-party \
  --webhook-name my-app-webhook

✅ 승인 단계 추가 (선택사항)

프로덕션 배포 전에 수동 승인 단계를 추가할 수 있어. 스테이징 배포 후 QA 팀이 확인하고 승인하면 프로덕션에 배포되는 방식이야:

# 파이프라인에 승인 단계 추가 (Deploy 단계 앞에 삽입)
{
  "name": "Approval",
  "actions": [
    {
      "name": "ManualApproval",
      "actionTypeId": {
        "category": "Approval",
        "owner": "AWS",
        "provider": "Manual",
        "version": "1"
      },
      "configuration": {
        "NotificationArn": "arn:aws:sns:ap-northeast-2:123456789012:deployment-approval",
        "CustomData": "프로덕션 배포 승인 요청. 스테이징 환경을 확인해주세요.",
        "ExternalEntityLink": "https://staging.your-app.com"
      }
    }
  ]
}

📊 8. 파이프라인 모니터링 & 알림 설정

파이프라인 만들었다고 끝이 아니야! 배포가 실패했을 때 빠르게 알아채고 대응할 수 있도록 모니터링과 알림 설정도 꼭 해줘야 해. 🔔

📧 SNS + Lambda로 Slack 알림 설정

CodePipeline은 상태 변경 시 EventBridge(CloudWatch Events)로 이벤트를 발생시켜. 이걸 SNS와 Lambda로 연결해서 Slack 알림을 보낼 수 있어:

# EventBridge 규칙 생성 (파이프라인 실패 감지)
aws events put-rule \
  --name "codepipeline-failure-notification" \
  --event-pattern '{
    "source": ["aws.codepipeline"],
    "detail-type": ["CodePipeline Pipeline Execution State Change"],
    "detail": {
      "state": ["FAILED", "SUCCEEDED"],
      "pipeline": ["my-app-pipeline"]
    }
  }' \
  --state ENABLED

# Lambda 함수 (Slack 알림 발송) - Python
import json
import urllib.request
import os

def lambda_handler(event, context):
    detail = event['detail']
    pipeline = detail['pipeline']
    state = detail['state']
    
    # 이모지 설정
    emoji = "✅" if state == "SUCCEEDED" else "❌"
    color = "#36a64f" if state == "SUCCEEDED" else "#ff0000"
    
    message = {
        "attachments": [
            {
                "color": color,
                "title": f"{emoji} CodePipeline 배포 알림",
                "fields": [
                    {"title": "파이프라인", "value": pipeline, "short": True},
                    {"title": "상태", "value": state, "short": True},
                    {"title": "실행 ID", "value": detail.get('execution-id', 'N/A'), "short": False}
                ],
                "footer": "AWS CodePipeline",
                "ts": int(event['time'][:10])
            }
        ]
    }
    
    webhook_url = os.environ['SLACK_WEBHOOK_URL']
    data = json.dumps(message).encode('utf-8')
    req = urllib.request.Request(webhook_url, data=data, headers={'Content-Type': 'application/json'})
    urllib.request.urlopen(req)
    
    return {'statusCode': 200}

📈 CloudWatch 메트릭 & 대시보드

CodeBuild와 CodeDeploy는 자동으로 CloudWatch 메트릭을 발행해. 주요 메트릭들을 알아두자:

🔍 빌드 로그 확인

빌드가 실패했을 때 원인을 파악하려면 CloudWatch Logs를 확인해야 해:

# 최근 빌드 로그 그룹 확인
aws logs describe-log-groups \
  --log-group-name-prefix /aws/codebuild/my-app-build

# 특정 빌드의 로그 스트림 확인
aws logs describe-log-streams \
  --log-group-name /aws/codebuild/my-app-build \
  --order-by LastEventTime \
  --descending \
  --max-items 5

# 로그 내용 확인
aws logs get-log-events \
  --log-group-name /aws/codebuild/my-app-build \
  --log-stream-name "build-id/phase-context"

🎯 9. 실무에서 꼭 알아야 할 고급 설정 & 팁

기본 파이프라인은 만들었어. 이제 실무에서 진짜 쓸 수 있는 수준으로 업그레이드할 차례야. 재능넷에서 DevOps 전문가들이 공유하는 노하우 수준의 팁들을 모아봤어! 💪

🌿 브랜치별 파이프라인 전략

⚡ 빌드 속도 최적화

🔒 보안 강화 설정

# buildspec.yml에서 민감 정보 안전하게 처리
version: 0.2

env:
  secrets-manager:
    # Secrets Manager에서 안전하게 가져오기
    DB_HOST: "prod/myapp/db:host"
    DB_PASSWORD: "prod/myapp/db:password"
    API_SECRET: "prod/myapp/api:secret_key"
  parameter-store:
    # SSM Parameter Store에서 가져오기 (SecureString 타입)
    JWT_SECRET: "/prod/myapp/jwt_secret"

phases:
  build:
    commands:
      # 환경 변수는 로그에 출력하지 않도록 주의!
      - echo "빌드 시작 (민감 정보는 로그에 출력 안 함)"
      - npm run build
      
      # 빌드 결과물에 민감 정보가 포함되지 않도록 확인
      - grep -r "password\|secret\|key" dist/ || echo "민감 정보 없음 확인"

🔄 자동 롤백 설정

# CodeDeploy 배포 그룹에 자동 롤백 설정
aws deploy update-deployment-group \
  --application-name my-app \
  --current-deployment-group-name my-app-production \
  --auto-rollback-configuration '{
    "enabled": true,
    "events": [
      "DEPLOYMENT_FAILURE",
      "DEPLOYMENT_STOP_ON_ALARM"
    ]
  }' \
  --alarm-configuration '{
    "enabled": true,
    "alarms": [
      {"name": "my-app-error-rate-alarm"},
      {"name": "my-app-cpu-alarm"}
    ]
  }'

CloudWatch 알람과 연동하면 배포 후 에러율이 급증하거나 CPU가 치솟을 때 자동으로 롤백이 트리거돼. 진짜 강력한 안전망이야!

📦 Terraform으로 파이프라인 IaC 관리

파이프라인 설정을 Terraform으로 코드화하면 버전 관리가 가능하고, 동일한 파이프라인을 여러 환경에 쉽게 복제할 수 있어:

# main.tf - CodePipeline 리소스 정의
resource "aws_codepipeline" "my_app_pipeline" {
  name     = "my-app-pipeline"
  role_arn = aws_iam_role.codepipeline_role.arn

  artifact_store {
    location = aws_s3_bucket.artifact_bucket.bucket
    type     = "S3"
  }

  stage {
    name = "Source"
    action {
      name             = "Source"
      category         = "Source"
      owner            = "ThirdParty"
      provider         = "GitHub"
      version          = "1"
      output_artifacts = ["source_output"]

      configuration = {
        Owner      = var.github_owner
        Repo       = var.github_repo
        Branch     = var.github_branch
        OAuthToken = var.github_token
      }
    }
  }

  stage {
    name = "Build"
    action {
      name             = "Build"
      category         = "Build"
      owner            = "AWS"
      provider         = "CodeBuild"
      input_artifacts  = ["source_output"]
      output_artifacts = ["build_output"]
      version          = "1"

      configuration = {
        ProjectName = aws_codebuild_project.my_app_build.name
      }
    }
  }

  stage {
    name = "Deploy"
    action {
      name            = "Deploy"
      category        = "Deploy"
      owner           = "AWS"
      provider        = "CodeDeploy"
      input_artifacts = ["build_output"]
      version         = "1"

      configuration = {
        ApplicationName     = aws_codedeploy_app.my_app.name
        DeploymentGroupName = aws_codedeploy_deployment_group.production.deployment_group_name
      }
    }
  }
}