🚀 Jenkins를 활용한 CI/CD 파이프라인 구축 (GitHub → Docker → ECR 업로드)

🚀 Mac에서 Jenkins를 Docker로 실행하기

이 가이드는 MacOS 환경에서 Docker를 이용해 Jenkins를 실행하는 방법을 설명합니다.

Jenkins를 빠르게 설치하고 CI/CD 파이프라인을 구축해봅시다.!!

---

1️⃣ 사전 준비

필수 도구 설치

1. Docker Desktop 다운로드

   • Mac에서 Docker가 실행되는지 확인 (docker --version)

2. Jenkins 실행을 위한 디렉토리 생성
   

   mkdir -p ~/jenkins_home
   chmod 777 ~/jenkins_home
   

---

2️⃣ Docker로 Jenkins 실행

Jenkins 컨테이너 실행

docker run -d \
  --name jenkins \
  -p 8080:8080 -p 50000:50000 \
  -v ~/jenkins_home:/var/jenkins_home \
  -v /var/run/docker.sock:/var/run/docker.sock \
  jenkins/jenkins:lts

✅ 실행 옵션 설명

• d : 백그라운드 실행
• -name jenkins : 컨테이너 이름
• p 8080:8080 : 웹 UI 포트 매핑
• p 50000:50000 : 에이전트 통신 포트
• v ~/jenkins_home:/var/jenkins_home : Jenkins 데이터 유지
• v /var/run/docker.sock:/var/run/docker.sock : Docker 내부에서 Docker 실행 지원

컨테이너 실행 확인

docker ps

Jenkins 컨테이너가 정상적으로 실행 중인지 확인하세요.

---

3️⃣ 초기 패스워드 확인 및 Jenkins 접속

초기 관리자 패스워드 찾기

docker logs jenkins | grep -A 5 "Administrator password"

출력 예시:

Jenkins initial setup is required. An admin user has been created and a password generated.
Please use the following password to proceed to installation:

123asdkjalskdjqlkweasd1234125

This may also be found at: /var/jenkins_home/secrets/initialAdminPassword

installation: 바로 아래 있는 문자열을 복사한 후 브라우저에서 Jenkins에 로그인하세요.

Jenkins 웹 UI 접속

1. 브라우저에서 http://localhost:8080 접속
   

2. 초기 패스워드 입력 후 로그인

3. "Install suggested plugins" 선택
   

   

4. 관리자 계정 생성 후 Jenkins 설정 완료
   

5. Main 화면 입장
   

---

4️⃣ Jenkins 설정 및 플러그인 설치 (GitHub 연동 및 ECR 배포 준비)

🔹 1. Jenkins 필수 플러그인 설치

Jenkins에서 GitHub와 Docker 빌드, AWS ECR 업로드를 원활하게 수행하기 위해 다음 플러그인을 설치해야 합니다.

📌 필요한 플러그인

• Git Plugin (GitHub 연동)
• Pipeline Plugin (Pipeline 작성)
• Docker Pipeline (Docker 빌드 및 푸시)
• Amazon ECR Plugin (AWS ECR 업로드)

📌 설치 방법

1. Jenkins 관리자 페이지 → Manage Jenkins → Plugin Manager 이동
2. Available 탭에서 위 플러그인 검색 및 설치
3. 설치 후 Jenkins 재시작

---

5️⃣ GitHub 인증 설정 (SSH 키 또는 PAT 방식)

Jenkins가 GitHub에서 코드를 가져오려면 인증이 필요합니다.

GitHub에 접근하는 방식은 SSH 키 인증과 Personal Access Token (PAT) 인증 두 가지 방법이 있습니다.

🔹 1. SSH 키 방식

1. Jenkins 서버에서 SSH 키 생성

   ssh-keygen -t rsa -b 4096 -C "your-email@example.com" 

   • 기본 경로: /var/jenkins_home/.ssh/id_rsa
   • id_rsa.pub 키를 복사

2. GitHub에 SSH 키 등록

   • GitHub → Settings → SSH and GPG keys → New SSH Key
   • id_rsa.pub 내용 붙여넣기

3. Jenkins에서 SSH 키 등록

   • Manage Jenkins → Manage Credentials → System → Global credentials
   • "Add Credentials" 클릭
     • Kind: SSH Username with Private Key
     • Username: git
     • Private Key: id_rsa 내용 붙여넣기

✅ GitHub SSH 인증 확인

ssh -T git@github.com

출력 예시

Hi your-username! You've successfully authenticated, but GitHub does not provide shell access.

---

🔹 2. GitHub Personal Access Token (PAT) 방식

✔️ GitHub 계정의 비밀번호를 대체하는 토큰을 발급받아 사용할 수도 있습니다.

1. GitHub에서 PAT 발급
   • GitHub 로그인 → Settings → Developer settings → Personal access tokens
   • Generate new token 클릭
   • repo 및 workflow 권한 선택 후 Generate token 클릭
   • 발급된 토큰 복사 (한 번만 확인 가능)
2. Jenkins에서 PAT 등록
   • Manage Jenkins → Manage Credentials → System → Global credentials
   • "Add Credentials" 클릭
     • Kind: Username with password
     • Username: GitHub 사용자명
     • Password: 발급받은 GitHub 토큰
     • ID: github-token

---

6️⃣ Jenkins에서 GitHub 저장소 연결

Jenkins에서 GitHub 저장소를 연동하여 코드를 가져와 빌드할 수 있도록 설정합니다.

🔹 1. GitHub 저장소 연결

1. Jenkins → New Item → Pipeline 선택

2. Pipeline Name 입력 후 OK 클릭

3. General → GitHub Project 체크 후 Repository URL 입력

   https://github.com/your-repo/your-project.git

4. Build Triggers → GitHub hook trigger for GITScm polling 체크

   • GitHub에서 변경 사항이 감지될 때 자동 빌드 트리거

---

7️⃣ Jenkins Pipeline Script 설정 (Jenkinsfile 활용)

Jenkins에서는 GitHub의 Jenkinsfile을 사용해 빌드 파이프라인을 정의합니다.

프로젝트 루트에 Jenkinsfile을 추가하여 Jenkins가 자동으로 파이프라인을 실행할 수 있도록 설정합니다.

pipeline {
    agent any

    environment {
        AWS_REGION = "ap-northeast-2"  // AWS 리전 설정
        AWS_ACCOUNT_ID = "123456789012"  // AWS 계정 ID (ECR 저장소 소유자)
        ECR_REPO = "${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/my-jenkins-image" // AWS ECR 저장소 URL
        IMAGE_TAG = "latest"  // 기본 태그 설정
    }

    stages {
        stage('Ensure ECR Exists') {
            steps {
                script {
                    // ECR 저장소가 존재하는지 확인하고 없으면 생성
                    sh """
                    aws ecr describe-repositories --repository-names my-jenkins-image --region ${AWS_REGION} || \
                    aws ecr create-repository --repository-name my-jenkins-image --region ${AWS_REGION}
                    """
                }
            }
        }

        stage('Checkout') {
            steps {
                // GitHub 저장소에서 코드 가져오기
                git branch: 'main', credentialsId: 'your-credentials-id', url: 'git@github.com:your-repo/your-project.git'
            }
        }

        stage('Build Docker Image') {
            steps {
                script {
                    // Docker 이미지 빌드 (태그 포함)
                    sh "docker build -t ${ECR_REPO}:${IMAGE_TAG} ."
                }
            }
        }

        stage('AWS ECR Login') {
            steps {
                script {
                    // AWS ECR 로그인 수행
                    sh "aws ecr get-login-password --region ${AWS_REGION} | docker login --username AWS --password-stdin ${ECR_REPO}"
                }
            }
        }

        stage('Push Docker Image to ECR') {
            steps {
                script {
                    // Docker 이미지를 ECR에 Push
                    sh "docker push ${ECR_REPO}:${IMAGE_TAG}"
                }
            }
        }
    }
}

---

📌 Jenkinsfile 코드 상세 설명

이 Jenkinsfile은 GitHub에서 코드를 가져와 Docker 이미지를 빌드하고, AWS ECR에 업로드하는 전체 CI/CD 과정을 수행합니다.

🔹 1. pipeline { agent any }

• Jenkins 파이프라인의 실행 환경을 설정합니다.
• agent any는 어떤 Jenkins 노드에서든 실행할 수 있도록 허용하는 설정입니다.

---

🔹 2. environment {} (환경 변수 설정)

• AWS 관련 환경 변수를 설정합니다.

  AWS_REGION = "ap-northeast-2"
  AWS_ACCOUNT_ID = "123456789012"
  ECR_REPO = "${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/my-jenkins-image"
  IMAGE_TAG = "latest"

• AWS_REGION → AWS에서 사용할 리전 (서울 리전 "ap-northeast-2")
• AWS_ACCOUNT_ID → AWS 계정 ID, ECR 리포지토리 소유자의 ID
• ECR_REPO → ECR 저장소 URL
• IMAGE_TAG → Docker 이미지 태그 (latest 기본 설정)

---

🔹 3. stage('Ensure ECR Exists') (ECR 저장소 확인 및 생성)

stage('Ensure ECR Exists') {
    steps {
        script {
            sh """
            aws ecr describe-repositories --repository-names my-jenkins-image --region ${AWS_REGION} || \
            aws ecr create-repository --repository-name my-jenkins-image --region ${AWS_REGION}
            """
        }
    }
}

• ECR 저장소가 존재하는지 확인하고 없다면 자동 생성합니다.
• aws ecr describe-repositories 명령어로 존재 여부 확인
• 만약 저장소가 없으면 aws ecr create-repository를 실행하여 생성

✅ 이 단계를 추가하면 최초 배포에서도 오류 없이 진행 가능합니다.

---

🔹 4. stage('Checkout') (GitHub에서 코드 가져오기)

stage('Checkout') {
    steps {
        git branch: 'main', credentialsId: 'your-credentials-id', url: 'git@github.com:your-repo/your-project.git'
    }
}

• GitHub에서 main 브랜치의 코드를 Jenkins 작업 공간으로 가져옵니다.
• credentialsId: 'your-credentials-id' → Jenkins에 저장된 GitHub SSH Key or Token을 사용하여 인증
• url: 'git@github.com:your-repo/your-project.git'
  • SSH 인증 방식 사용 (HTTPS 방식 사용 시 https://github.com/your-repo/your-project.git)

---

🔹 5. stage('Build Docker Image') (Docker 이미지 빌드)

stage('Build Docker Image') {
    steps {
        script {
            sh "docker build -t ${ECR_REPO}:${IMAGE_TAG} ."
        }
    }
}

• docker build 명령어를 실행하여 Docker 이미지를 생성
• ${ECR_REPO}:${IMAGE_TAG} → ECR 저장소를 참조하여 태깅

✅ ECR 저장소에 맞게 이미지가 자동 태깅되므로 추가 설정 필요 없음

---

🔹 6. stage('AWS ECR Login') (AWS ECR 로그인)

stage('AWS ECR Login') {
    steps {
        script {
            sh "aws ecr get-login-password --region ${AWS_REGION} | docker login --username AWS --password-stdin ${ECR_REPO}"
        }
    }
}

• AWS CLI를 통해 ECR 로그인 수행
• aws ecr get-login-password --region ${AWS_REGION} → AWS에서 ECR 로그인 비밀번호 가져오기
• docker login --username AWS --password-stdin ${ECR_REPO} → 해당 패스워드를 사용하여 로그인

✅ 이 단계를 수행해야 ECR에 Docker 이미지를 푸시할 수 있음

---

🔹 7. stage('Push Docker Image to ECR') (Docker 이미지 푸시)

stage('Push Docker Image to ECR') {
    steps {
        script {
            sh "docker push ${ECR_REPO}:${IMAGE_TAG}"
        }
    }
}

• docker push 명령어로 빌드된 이미지를 AWS ECR 저장소에 업로드

✅ 완료 후 AWS ECR에서 이미지를 확인할 수 있음

aws ecr list-images --repository-name my-jenkins-image --region ap-northeast-2

---

정리

이 Jenkinsfile은:

1. GitHub에서 최신 코드 가져오기 (Checkout)
2. Docker 이미지 빌드 (Build Docker Image)
3. AWS ECR에 로그인 (AWS ECR Login)
4. Docker 이미지를 AWS ECR에 푸시 (Push Docker Image to ECR)

을 수행하는 완전한 CI/CD 파이프라인을 구축합니다.

---

8️⃣ AWS ECR 연동 (IAM 및 권한 설정)

🔹 1. AWS CLI 설치

brew install awscli

🔹 2. AWS IAM 사용자 생성 (ECR 접근 가능하도록 설정)

• AWS IAM → 사용자 추가 → 프로그램 방식 접근
• 권한 추가: AmazonEC2ContainerRegistryFullAccess
• Access Key & Secret Key 저장

🔹 3. Jenkins에서 AWS Credentials 추가

1. Manage Jenkins → Manage Credentials → Global Credentials
2. "Add Credentials" 클릭
   • Kind: AWS Credentials
   • Access Key ID & Secret Key 입력
   • ID: aws-credentials

---

9️⃣ GitHub Webhook 설정 (자동 빌드 트리거)

Jenkins에서 GitHub의 변경 사항을 자동으로 감지하고 빌드를 트리거하려면 Webhook을 설정해야 합니다.

🔹 1. GitHub Webhook 설정

1. GitHub Repository → Settings → Webhooks 이동

2. Webhook 추가 (Add webhook) 클릭

3. Webhook 정보 입력

   • Payload URL:

     http://your-jenkins-url/github-webhook/

     • your-jenkins-url은 Jenkins 서버의 실제 URL로 변경해야 합니다.
     • Jenkins가 외부에서 접근 가능해야 합니다 (예: http://jenkins.yourdomain.com/github-webhook/).
   • Content type: application/json
   • Secret: Jenkins에서 Webhook 인증을 강화하려면, 임의의 Secret을 입력하고 Jenkins에서도 같은 값을 설정해야 합니다.
   • Which events would you like to trigger this webhook?
     • Just the push event 체크 (기본적으로 코드 변경 시 자동 트리거)
     • Pull requests를 포함하려면 별도로 체크 가능

4. Webhook 저장 (Add webhook) 클릭

---

🔹 2. Jenkins에서 Webhook 수신 설정

Jenkins가 Webhook 요청을 정상적으로 처리하려면 GitHub Plugin을 활성화해야 합니다.

1. Jenkins → Manage Jenkins → Configure System 이동
2. GitHub 섹션에서 GitHub Webhook 설정 확인
3. "Manage Hooks" 권한을 부여한 GitHub Credentials 추가
   • Manage Jenkins → Manage Credentials → Add Credentials
   • Kind: Username with password
   • Username: GitHub 사용자명
   • Password: Personal Access Token (PAT)
   • Scope: Global
4. 해당 Credentials를 GitHub 설정에서 연결

---

🔹 3. GitHub Hook Trigger 활성화 (Jenkins Job 설정)

Jenkins에서 Webhook을 사용하려면 Job에서 해당 옵션을 활성화해야 합니다.

1. Jenkins → 해당 Pipeline Job → Configure 이동
2. "Build Triggers" 섹션에서 아래 옵션 활성화
   • ✅ GitHub hook trigger for GITScm polling 체크

✅ 이제 GitHub에서 코드가 푸시될 때마다 Jenkins가 자동으로 빌드를 수행합니다. 🚀

---

🔟 Jenkins 실행 및 배포 테스트

1. Jenkins Job 실행

1. Jenkins → New Item → Pipeline 생성
2. SCM을 Git으로 설정 (GitHub 레포지토리 설정)
3. "Build Now" 실행
4. Pipeline 실행 로그 확인

✅ 성공 시 AWS ECR 확인

aws ecr list-images --repository-name my-jenkins-image --region ap-northeast-2

---

🎯 마무리

이제 Jenkins를 통해 GitHub에서 코드를 가져와 Docker 이미지를 빌드하고, AWS ECR에 업로드하는 자동화 CI/CD 파이프라인이 구축되었습니다! 🚀

다음으로 배포 환경 (ECS, Kubernetes)까지 확장하는 과정을 진행하면 완전한 DevOps 워크플로우를 구축할 수 있습니다.

---

🛠 추가 질문

❓ Jenkins에서 GitHub 인증이 안 될 때?

• SSH 키 등록 여부 확인 (ssh -T git@github.com)

❓ ECR 푸시가 안 될 때?

• aws ecr get-login-password 실행 후 docker login 재시도

❓ GitHub Webhook이 작동하지 않을 때?

• GitHub → Webhook 로그에서 응답 코드 확인 (200 OK가 정상)

---

이제 Jenkins를 활용해 완전한 CI/CD 파이프라인을 구축할 수 있습니다! 🚀

궁금한 점이 있으면 언제든지 질문해주세요. 😊