Jenkins가 Flutter 경로를 찾지 못해 발생한 이슈 트러블 슈팅

🧐 문제상황

 
매일 새벽 5시마다 플러터 프로젝트 develop 브랜치에서 단위테스트를 실행시키고자 했다.
 
1. 이를 위해 EC2에 도커로 젠킨스를 배포했다.
2. Flutter 는 Docker Hub 에 마땅한 이미지가 없어서 (개인이 올려놓은 플러터 이미지가 있긴했는데 스타수가 워낙 낮아 신뢰하기 어려웠다.) EC2 로컬에 직접 설치한상태였다.
 
이 상태에서 파이프라인 스크립트를 작성하고 build 를 해보았더니 젠킨스가 flutter 파일을 찾지못하고 failure해버리는 이슈가 발생했다.

---

☺️ 문제 원인 분석 및 해결

Jenkins가 Docker 컨테이너로 실행되면, 컨테이너는 자체 격리된 파일 시스템을 사용한다. 따라서, EC2 로컬에 설치된 Flutter와 Android SDK 경로를 인식하지 못하고, flutter 명령을 실행할 수 없는 상황이 발생한다. 이를 정리하면

 

1. Flutter 및 Android SDK 경로 마운트 미설정
   Docker 컨테이너에서 EC2 호스트의 /home/ec2-user/flutter 및 /home/ec2-user/android-sdk 경로를 접근하지 못함.
   
   
2. 환경 변수 누락
   Jenkins Pipeline에서 Flutter와 Android SDK 경로를 PATH에 포함하지 않음.
   
   
3. 권한 문제
   EC2 로컬 디렉토리를 Jenkins Docker 컨테이너가 읽고 쓸 수 있도록 설정하지 않음.

 

위 문제 해결을 위해  Docker를 통해 실행되는 Jenkins 컨테이너에서 호스트의 Flutter 및 Android SDK를 사용할 수 있도록 볼륨 마운트를 설정했다.

---

볼륨이란? 

 

도커 컨테이너는 그 자체로 격리된 저장 공간 환경으로 호스트 시스템과 분리된 파일 시스템을 사용한다.

 

도커는 이식성(portability)이 생명이기 때문에 컨테이너는 어디서든 동일하게 작동해하고 (예: 로컬, 클라우드, 다른 개발 환경) 만약 컨테이너가 특정 호스트의 로컬 데이터를 의존한다면, 다른 시스템으로 옮겼을 때 동일하게 작동하지 않을 가능성이 생겨버린다.

 

따라서 도커 이미지에는 데이터를 따로 두지 않는대신 외부에 데이터를 저장하고 이를 참조해서 쓰게 되는데 이러한 공간을 "도커볼륨"이라고 한다. 즉 도커 볼륨은 컨테이너 외부에 데이터를 저장하기 위한 도커의 내장 데이터 관리 기능이다. 컨테이너가 삭제되더라도 볼륨에 저장된 데이터는 유지된다. 주요 특징은 아래와 같다.

• 컨테이너의 수명과 독립적으로 데이터를 보관한다.
• 도커가 관리하는 특정 위치에 저장된다 (/var/lib/docker/volumes/).
• 컨테이너 간 데이터 공유가 가능하다.

 

마운트란?

https://takethenotes.com/mount-points/

 

리눅스는 단일 루트 파일 시스템(/)을 기반으로 동작한다다. 외부 장치(디스크, USB 등)나 추가 디스크 파티션을 사용하려면, 이를 리눅스의 파일 시스템 트리에 연결해야 한다.이때  마운트는 외부 저장 장치나 파일 시스템을 리눅스의 특정 디렉토리(마운트 지점, Mount Point)에 연결한다. 마운트된 장치의 데이터는 마운트 지점 디렉토리를 통해 접근할 수 있다. 

 

https://therahulsarkar.medium.com/understanding-docker-volumes-a-comprehensive-guide-46339aa9ac53

 

껍데기라 볼 수 있는 도커이미지가 데이터를 이용하는 방법은 크게 세가지 경로이다. BindMount 를 통해 호스트 파일 시스템과 직접 연결하여 호스트의 데이터를 실시간으로 참조하는 방법, tmpfs mount를 통해 램메모리 임시 데이터를 이용하는 방법, 그리고 도커 볼륨 에 접근하는 방법이다. 

 

---

 

일단 플러터 SDK를 이용하기 위해서는 램메모리 참조가 아닌 도커볼륨 or Bindmount 두가지 방법중 하나를 선택해야했다. 이중 내가 선택한 방법은 도커 볼륨 마운트를 통한 로컬 데이터를 이용하는 것이었다. 

 

 

도커 볼륨과 BindMount 차이

 

도커 볼륨은 Docker가 데이터를 자체적으로 관리한다(var/lib/docker/volumes/). 따라서, 로컬 경로에 의존하지 않고, 컨테이너가 실행되는 환경이 어디든 동일하게 작동한다. 만약 바인드 마운트는 호스트의 특정 경로를 요구하기 때문에 환경 간 차이가 발생할 수 있다.

 

물론 바인드 호스트로 하게 되면 로컬 파일을 실시간으로 컨테이너에서 참조할 수 있으므로 SDK에 변화가 생긴다거나 업데이트되면 컨테이너를 재시작하지 않아도 바로 반영된다는 것과 로컬 데이터를 그대로 사용하므로 추가적인 데이터 복사 과정이 없다는게 장점이기는 하지만 도커의 가장 큰 장점인 이식성이 훼손되어서 프로덕션 환경에서는 도커 볼륨을 마운트하는게 더 나은 판단이라고 생각했다.

 

실제 문제 해결한 과정은 아래와 같다.

 

 

1. Docker 컨테이너 실행 시 볼륨 마운트

Jenkins 컨테이너 실행 시 아래와 같이 호스트의 Flutter 및 Android SDK 경로를 컨테이너에 마운트했다

sudo docker run \
  -d \
  -p 8080:8080 \
  -v /var/jenkins_home:/var/jenkins_home \
  -v /home/ec2-user/flutter:/home/ec2-user/flutter \
  -v /home/ec2-user/android-sdk:/home/ec2-user/android-sdk \
  jenkins/jenkins:lts

 

2. Jenkins Pipeline에서 환경 변수 설정

Jenkins Pipeline에서 Flutter와 Android SDK 경로를 인식할 수 있도록, 아래와 같이 environment 블록에서 경로를 추가한다:

pipeline {
    agent any
    environment {
        PATH = "/home/ec2-user/flutter/bin:/home/ec2-user/android-sdk/tools:/home/ec2-user/android-sdk/platform-tools:$PATH"
    }
    stages {
        stage('Environment Check') {
            steps {
                sh 'flutter --version'
                sh 'adb --version'
            }
        }
        // 기타 스테이지 생략
    }
}

 

 

3. Jenkins 컨테이너의 권한 문제 해결

Flutter와 Android SDK가 Jenkins 컨테이너 내에서 제대로 읽히고 쓰일 수 있도록 디렉토리 권한을 설정한다.

sudo chown -R 1000:1000 /home/ec2-user/flutter
sudo chown -R 1000:1000 /home/ec2-user/android-sdk

여기서 1000:1000은 Jenkins Docker 컨테이너의 기본 사용자 및 그룹 ID이다. 이는 컨테이너 내에서 Jenkins가 파일 접근에 문제가 없도록 보장한다.

 

위와같은 방법으로 Jenkins Docker 컨테이너가 EC2 로컬의 Flutter 및 Android SDK를 제대로 인식할 수 있도록 볼륨 마운트와 환경 변수 설정을 완료할 수 있었다 :)