Gitea Container Registry 이용하기

배포자동화를 구현하면서 이미지를 빌드한 뒤 원격저장소에 빌드한 이미지를 올리고 서버에서 이미지를 받아 컨테이너를 띄우는 과정이 필요했다.

 

이미지를 저장할 원격 저장소가 필요한데 DockerHub, ECR, GitHub Container Registry 등 이용 가능한 여러 서비스들이 있다.

DockerHub의 경우는 Private의 경우는 딱 하나의 이미지만 무료로 업로드가 가능하고 나머지 서비스들 역시 모두 서비스 이용료가 들어가게 된다.

 

비용 없이 이용할 수 있는 것이 있을까 찾아보다가 회사에서 사용중이었던 Gitea에도 Gitea Container Registry가 있다는 것을 알게 되었다. 추가 비용을 들이지 않고도 이미지를 업로드하고 받을 수 있기 때문에 이용해보기로 했다.

 

사용법은 공식문서에 잘 나와있다. 간단하게 사용법을 정리해보았다.

 

https://docs.gitea.com/usage/packages/container

Container Registry | Gitea Documentation

 

Gitea Container Registry 이용하기

1. 로그인하기

Private 저장소에 이미지를 업로드 하려면 먼저 Gitea 계정을 이용해 로그인을 해야한다. 아래 명령어를 이용해 로그인 할 수 있다.

$ docker login gitea.example.com

명령어 입력후 아이디와 비밀번호(토큰)를 입력하면 로그인 할 수 있다.

 

이미지를 Pull 받는 것은 일반 유저도 가능하지만 Push 하려면 관리자 권한이 있어야한다는 점도 참고해야한다.

 

2. 이미지 네이밍 규칙을 지켜 이미지 빌드하기

이미지를 업로드(Push)하려면 네이밍 규칙(convention)을 지켜서 이미지를 빌드해야한다. 유저 기반 또는 조직 기반으로 이미지를 관리할 수 있고, 하나를 선택해서 작업하면 된다.

# 태그를 달아 이미지를 빌드 (유저 이름을 경로로하여 빌드 후 푸쉬하면 유저 기반으로 관리됨)
$ docker build -t {레지스트리}/{유저이름(owner)}/{이미지이름}:{태그} .

# 태그를 달아 이미지를 빌드 (조직 기반으로 관리하려면 아래와 같이 빌드)
$ docker build -t {레지스트리}/{조직(organization)}/{이미지이름}:{태그} .

# 예시
$ docker build -t gitea.example.com/organization/front-server:latest .

3. 빌드한 이미지 업로드(Push)하기

네이밍 컨벤션을 잘 지켜 이미지를 빌드했다면 그대로 업로드만 하면 된다. docker push 명령어를 이용하면 된다.

# 예시
$ docker push gitea.example.com/organization/front-server:latest

업로드가 완료되면 아래 사진과 같이 Packages 탭에서 확인할 수 있다.

 

4. 이미지 다운받기(Pull)

업로드된 이미지를 다운받을 때에는 docker pull 명령어를 이용하면 된다.

# 예시
$ docker pull gitea.example.com/organization/front-server:latest

 

 

이렇게 이용방법은 간단하다. 다만 이용하면서 이미지가 정상적으로 Push 되지 않는 문제가 발생했었다. 그 문제를 해결했던 내용도 아래 같이 정리해본다.

 

Gitea Container Registry Push 오류 해결하기

Gitea Container Registry의 사용방법은 위와 같이 간단하다. 하지만 실제 이용 과정 중 Push 과정에서 계속해서 문제가 발생했었다.

 

Push를 진행하면 오류 메시지가 발생하면서 업로드가 중단되었고, Gitea에서는 업로드된 이미지 확인은 가능하지만 업로드가 완전히 이루어지지 않은 상태로 남아있었다. 에러가 발생하면서 업로드가 중단된 것이다.

 

오류 메시지는 아래와 같다.

failed commit on ref "index-sha256:[...]": unexpected status from PUT request to https://{registry}/v2/manifests/latest: 404 Not Found

해당 오류에 대해 검색을 해봐도 해결 방법과 원인에 대해서 나오지 않아 한참을 해결하지 못하고 있었다.

 

그러다가 아래 게시글을 발견하게 되었다.

 

https://github.com/go-gitea/gitea/issues/31861

Builtin Container Registry: Manifests 404 Not Found · Issue #31861 · go-gitea/gitea

 

해결법은 간단한데 이미지를 빌드할 때 --provenance=false 옵션을 추가해주는 것이다. workflow 파일에서 빌드할 때 빌드 옵션에 해당 부분을 추가해주는 것으로 문제를 해결할 수 있었다.

 

provenance 정보는 빌드 아티팩트가 어떻게 생성되었는지, 어떤 코드나 종속성, 환경을 사용했는지 등의 정보를 기록하는 메타데이터이고, 이것이 설정되어 있으면 빌드가 서명되고 그 서명 및 출처 정보가 검증된다.

 

이것을 이용할 때 오류가 발생하는 경우는 서명에 실패하거나 인증 문제가 발생했을 때 검증에 실패했을 때 등이라고 한다. 하지만 이 중 어떤 이유로 인해 Push가 실패하는지는 알아내지 못했다. (게시글을 읽어봐도 정확한 원인이 무엇인지 파악할 수 없다.)

 

해당 기능을 사용하지 않음으로써 문제는 해결되었다. 문제는 해결했지만 정확한 원인을 알아내지 못한 부분은 아쉽기도하고 개운하지 못한 느낌이 드는 것도 사실이었다.

 

 

그래도 정리한 내용과 같이 회사 내에 있는 서버에서 호스팅한 Gitea만 가지고도 추가 서비스를 이용하지 않고 이미지를 잘 업로드하고 다운받을 수 있게 되었다는 점에서 만족스러웠다. 다음에 비슷한 일을 맡게 된다면 그때에도 다양한 옵션들을 살펴보고 가장 좋은 선택을 하기 위해 고민해보아야할 것 같다.