[Docker] GitLab CI/CD: Docker 볼륨 권한 문제를 해결하기

GitLab CI/CD 파이프라인에서 docker-compose를 사용해 볼륨을 마운트할 때 Permission denied 오류를 만난 적이 있나요? 로컬에서는 잘되던 코드가 GitLab Runner에서만 오류를 뱉어낸다면, 대부분 권한 문제가 원인입니다.

핵심은 GitLab Runner의 shell executor가 gitlab-runner라는 특정 사용자로 실행된다는 점입니다. 이 사용자는 당신의 계정과는 별개이므로, 당신의 계정이 소유한 프로젝트 폴더에 대한 쓰기 권한이 없을 수 있습니다.

문제의 원인: 소유자 불일치

1. 당신의 로컬 환경: 당신의 PC에서 docker-compose up을 실행하면, 당신 계정의 권한으로 모든 작업이 진행됩니다. 따라서 프로젝트 폴더에 자유롭게 접근하고 파일을 생성할 수 있습니다.
2. GitLab Runner 환경: GitLab CI/CD 파이프라인이 시작되면, gitlab-runner 계정이 스크립트를 실행합니다. 이 계정은 보안상의 이유로 제한된 권한을 가지고 있습니다. 만약 프로젝트 폴더가 gitlab-runner 계정의 소유가 아니라면, Permission denied 오류가 발생합니다.

이 문제를 해결하기 위한 가장 간단하고 확실한 방법은 바로 프로젝트 폴더의 소유권을 gitlab-runner 계정으로 변경하는 것입니다.

---

chown 명령어: 소유자 변경하기

chown은 "Change Owner"의 약자로, 파일이나 디렉터리의 소유권을 변경하는 명령어입니다. 여기서 -R 옵션이 중요합니다.

Bash

 

sudo chown -R gitlab-runner:gitlab-runner /path/to/your/project

명령어 자세히 살펴보기

• sudo: "superuser do"의 약자입니다. 일반 사용자는 소유권을 변경할 권한이 없기 때문에, 최고 관리자(root)의 권한으로 명령어를 실행해야 합니다.
• chown: 소유권을 변경하는 명령어입니다.
• -R (Recursive): 매우 중요한 옵션입니다. 이는 명령어의 효과를 대상 디렉터리뿐만 아니라 그 아래에 있는 모든 하위 디렉터리와 파일에 대해 재귀적으로 적용하라는 의미입니다. 이 옵션이 없다면, 상위 디렉터리의 소유권만 변경되고 내부 파일들은 여전히 원래 소유자의 소유로 남아있게 됩니다.
• gitlab-runner:gitlab-runner: 새로운 소유자와 그룹을 지정합니다. 이 명령어를 통해 /path/to/your/project 디렉터리와 그 안의 모든 파일/폴더의 소유권이 gitlab-runner 사용자 및 그룹으로 바뀝니다.
• /path/to/your/project: 소유권을 변경할 프로젝트 디렉터리의 실제 경로를 입력하세요.

이 명령어를 파이프라인 스크립트의 첫 부분에 추가하거나, 직접 GitLab Runner가 설치된 서버에서 실행하면 권한 문제를 손쉽게 해결할 수 있습니다.

요약: GitLab CI/CD에서 볼륨 마운트 오류가 발생하면, sudo chown -R gitlab-runner:gitlab-runner /path/to/project 명령어를 실행해 소유권을 일치시켜주세요.

 

Questions

소유자를 바꾸면 또다른 문제를 야기하는 것 아닌가?

네, 맞습니다. 프로젝트 디렉터리의 소유권을 gitlab-runner 계정으로 변경하면 다른 계정의 접근 권한에 문제가 생길 수 있습니다. 이는 특히 여러 사용자가 동일한 서버에서 작업하는 환경에서 중요한 고려 사항입니다.

발생할 수 있는 문제점들

1. 다른 개발자의 접근 권한 상실 

• 문제: 만약 여러 명의 개발자가 SSH로 서버에 접속해 코드를 직접 수정해야 하는 상황이라면, 소유권이 gitlab-runner로 변경되어 다른 개발자들이 파일을 수정하거나 삭제할 수 없게 됩니다.
• 해결책:
  • 그룹 권한 사용: 프로젝트 디렉터리의 소유자 그룹을 개발자들이 모두 속한 그룹으로 변경하고, 해당 그룹에 쓰기 권한을 부여합니다.
  • Bash

     

    # 소유자는 gitlab-runner로 유지, 그룹은 developers로 변경
    sudo chown -R gitlab-runner:developers /path/to/your/project
    # 그룹에 쓰기 권한 부여 (rwxrwx---)
    sudo chmod -R 770 /path/to/your/project
    

  • ACL(Access Control List) 사용: 더 세밀한 권한 관리가 필요하다면, ACL을 사용해 특정 사용자에게만 추가적인 권한을 부여할 수 있습니다.

2. 로컬에서 작업 시 불편함 

• 문제: GitLab Runner를 사용하는 동일한 서버에서 직접 코드를 수정해야 할 때, 소유권이 gitlab-runner로 되어 있으면 sudo 없이 파일 수정이 불가능해집니다.
• 해결책:
  • user 옵션 사용 (권장): docker-compose.yml에서 user 옵션을 사용해 컨테이너를 실행하는 사용자를 동적으로 설정하는 것이 가장 좋은 방법입니다.
     

    # docker-compose.yml
    services:
      your_service:
        user: "${HOST_USER_ID}:${HOST_GROUP_ID}"
        volumes:
          - ./:/app
    

    이 방법은 gitlab-runner가 실행할 때는 gitlab-runner의 UID/GID를 사용하고, 당신이 로컬에서 실행할 때는 당신의 UID/GID를 사용하므로 권한 충돌이 발생하지 않습니다.
  •  

    # .gitlab-ci.yml
    variables:
      HOST_USER_ID: $(id -u)
      HOST_GROUP_ID: $(id -g)
    
    build:
      script:
        - docker-compose up --build
    

결론: 상황에 맞는 해결책 선택하기

소유권을 변경하는 chown 명령어는 단일 사용자 환경에서 빠르고 쉽게 문제를 해결할 수 있는 방법입니다. 하지만 여러 사용자가 협업하는 환경에서는 그룹 권한 조정이나 user 옵션을 사용하는 것이 장기적으로 훨씬 안전하고 효율적입니다.