GitLab 컨테이너 레지스트리 문제 해결

대부분의 GitLab 컨테이너 레지스트리 문제를 해결하려면 GitLab에 관리자 권한으로 로그인해야 합니다.

GitLab 컨테이너 레지스트리 관리 문서에서 추가 문제 해결 정보를 찾을 수 있습니다.

OCI 컨테이너 이미지를 GitLab 컨테이너 레지스트리로 마이그레이션

GitLab 레지스트리로의 컨테이너 이미지 마이그레이션은 지원되지 않지만, epic에서 이 동작을 변경하기로 제안되었습니다.

컨테이너 이미지를 마이그레이션하기 위해 다른 회사의 도구를 사용할 수 있습니다. 예를 들어 skopeo는 여러 저장 메커니즘 간에 컨테이너 이미지를 복사할 수 있습니다. skopeo를 사용하여 컨테이너 레지스트리, 컨테이너 스토리지 백엔드, 로컬 디렉터리 및 로컬 OCI 레이아웃 디렉터리에서 GitLab 컨테이너 레지스트리로 복사할 수 있습니다.

Docker 연결 오류

Docker 연결 오류는 그룹, 프로젝트 또는 브랜치 이름에 특수 문자가 포함되어 있을 때 발생할 수 있습니다. 특수 문자로는 다음이 포함됩니다:

  • 선행 밑줄.
  • 뒷부분 하이픈 또는 대시.

이 오류를 해결하려면 그룹 경로, 프로젝트 경로 또는 브랜치 이름을 변경해야 합니다.

Docker Engine 17.11 이전을 사용하는 경우 404 Not Found 또는 Unknown Manifest 오류 메시지가 표시될 수 있습니다. 현재 버전의 Docker Engine에서는 v2 API를 사용합니다.

GitLab 컨테이너 레지스트리의 이미지는 Docker v2 API를 사용해야 합니다. 버전 1 이미지를 버전 2로 업데이트하는 방법에 대한 자세한 내용은 Docker 문서를 참조하십시오.

매니페스트 리스트를 푸시할 때 Blob unknown to registry 오류

GitLab 컨테이너 레지스트리에 Docker 매니페스트 리스트를 푸시할 때 manifest blob unknown: blob unknown to registry 오류 메시지가 표시될 수 있습니다. 이 오류는 동일한 리포지터리가 아닌 여러 리포지터리에 분산된 다른 아키텍처의 이미지가 있는 경우 발생합니다.

예를 들어 두 개의 이미지가 있는 경우 각각 다음과 같이 아키텍처를 표현합니다:

  • amd64 플랫폼.
  • arm64v8 플랫폼.

이러한 이미지로 다중 아키텍처 이미지를 빌드하려면 이들을 동일한 리포지터리에 푸시해야 합니다.

Blob unknown to registry 오류를 해결하려면 개별 이미지의 태그 이름에 아키텍처를 포함하십시오. 예를 들어 mygroup/myapp:1.0.0-amd64 및 mygroup/myapp:1.0.0-arm64v8와 같이 사용할 수 있습니다. 그런 다음 매니페스트 리스트에 mygroup/myapp:1.0.0으로 태그를 지정할 수 있습니다.

프로젝트 경로를 변경하거나 프로젝트를 이전할 수 없음

프로젝트 경로를 변경하거나 프로젝트를 새 네임스페이스로 이전하려고 시도하는 경우 다음과 같은 오류 메시지 중 하나가 발생할 수 있습니다:

  • 프로젝트는 컨테이너 레지스트리에 태그가 있기 때문에 이전할 수 없습니다.
  • 네임스페이스는 한 프로젝트에 태그가 있기 때문에 이동할 수 없습니다.

이 오류는 프로젝트에 컨테이너 레지스트리에 이미지가 있는 경우 발생합니다. 경로를 변경하거나 프로젝트를 이전하기 전에 이미지를 삭제하거나 이동해야 합니다.

다음 절차는 다음과 같은 샘플 프로젝트 이름을 사용합니다:

  • 현재 프로젝트: gitlab.example.com/org/build/sample_project/cr:v2.9.1.
  • 새 프로젝트: gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1.

  1. 컴퓨터에서 Docker 이미지를 다운로드합니다: 

    docker login gitlab.example.com
docker pull gitlab.example.com/org/build/sample_project/cr:v2.9.1
    note
    개인 액세스 토큰 또는 배포 토큰 중 하나를 사용하여 사용자 계정을 인증하십시오.

  2. 새 프로젝트 이름과 일치하도록 이미지의 이름 바꾸기: 

    docker tag gitlab.example.com/org/build/sample_project/cr:v2.9.1 gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1
  3. UI 또는 API를 사용하여 이전 프로젝트의 이미지 삭제. 이미지가 대기열에 들어가 삭제될 때까지 시간이 걸릴 수 있습니다.

  4. 경로 변경 또는 프로젝트 이전:

    1. 왼쪽 사이드바에서 검색 또는 이동하여를 선택하고 프로젝트를 찾습니다.
    2. 설정 > 일반을 선택합니다.
    3. 고급 섹션을 확장합니다.
    4. 경로 변경 텍스트 상자에서 경로를 편집합니다.
    5. 경로 변경을 선택합니다.

  5. 이미지 복원: 

    docker push gitlab.example.com/new_org/build/new_sample_project/cr:v2.9.1

세부 정보는 이 이슈를 참조하십시오.

큰 이미지를 푸시할 때 unauthorized: authentication required 메시지

큰 이미지를 푸시하는 경우, 컨테이너 레지스트리의 토큰이 이미지 푸시가 완료되기 전에 만료되어 인증 오류가 발생할 수 있습니다. 기본적으로 Self-managed GitLab 인스턴스의 컨테이너 레지스트리 토큰은 5분마다 만료됩니다. GitLab.com에서는 토큰 만료 시간이 15분으로 설정됩니다.

Self-managed GitLab을 사용하는 경우 관리자는 토큰 지속 시간을 증가시킬 수 있습니다.

Failed to pull image 메시지

제한된 CI/CD 작업 토큰 범위가 있는 프로젝트에서 컨테이너 이미지를 끌어오지 못하는 경우 Failed to pull image 오류 메시지를 받을 수 있습니다.

큰 이미지를 kaniko를 사용하여 푸시할 때 업로드가 느린 문제

kaniko를 사용하여 큰 이미지를 푸시할 때 치명적으로 긴 지연이 발생할 수 있습니다.

이는 일반적으로 HTTP/2 및 kaniko의 성능 문제로 인한 것입니다. 현재의 임시 방편은 kaniko로 푸시할 때 HTTP/1.1을 사용하는 것입니다.

HTTP/1.1을 사용하려면 GODEBUG 환경 변수를 "http2client=0"으로 설정하십시오.

docker login 명령이 access forbidden 오류로 실패함

컨테이너 레지스트리는 GitLab API URL을 Docker 클라이언트에 반환하여 자격 증명을 검증합니다. Docker 클라이언트는 기본 인증을 사용하므로 요청에는 Authorization 헤더가 포함됩니다. 레지스트리 구성에 대해 /jwt/auth 엔드포인트로 구성된 요청에서 Authorization 헤더가 누락되면 access forbidden 오류 메시지가 표시됩니다.

예를 들어: 

> docker login gitlab.example.com:4567

Username: user
Password:
Error response from daemon: Get "https://gitlab.company.com:4567/v2/": denied: access forbidden

이 오류를 피하려면 요청에서 Authorization 헤더가 제거되지 않도록 해야 합니다. 예를 들어, GitLab 앞에 있는 프록시가 /jwt/auth 엔드포인트로 리디렉션을 수행할 수 있습니다.