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

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

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

OCI 컨테이너 이미지를 GitLab 컨테이너 레지스트리로 이관

GitLab 레지스트리로 컨테이너 이미지를 이관하는 것은 지원되지 않지만, epic에서 이 동작을 변경하도록 제안하고 있습니다.

컨테이너 이미지를 이관하려면 skopeo와 같은 타사 도구를 사용할 수 있습니다. 예를 들어 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

    참고: 개인 액세스 토큰 또는 배포 토큰을 사용하여 사용자 계정을 인증할 수 있습니다.

  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 오류가 발생하는 경우

대용량 이미지를 푸시하는 중에 다음과 같은 인증 오류가 발생할 수 있습니다: 

docker push gitlab.example.com/myproject/docs:latest
The push refers to a repository [gitlab.example.com/myproject/docs]
630816f32edb: Preparing
530d5553aec8: Preparing
...
4b0bab9ff599: Waiting
d1c800db26c7: Waiting
42755cf4ee95: Waiting
unauthorized: authentication required

이 오류는 이미지 푸시가 완료되기 전에 인증 토큰이 만료될 때 발생합니다. 기본적으로, 자체 관리형 GitLab 인스턴스의 컨테이너 레지스트리용 토큰은 5분마다 만료됩니다. GitLab.com에서는 토큰 만료 시간이 15분으로 설정됩니다.

자체 관리형 GitLab을 사용하는 경우, 관리자는 토큰 기간을 증가시킬 수 있습니다.

Failed to pull image 메시지

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

kaniko를 사용하여 대용량 이미지를 푸시하는 경우 업로드 속도가 느린 문제

kaniko를 사용하여 대용량 이미지를 푸시하는 경우 일반적으로 뚜렷하게 긴 지연이 발생할 수 있습니다.

이는 일반적으로 kaniko 및 HTTP/2와 관련된 성능 문제의 결과입니다. 현재의 해결책은 kaniko로 푸시할 때 HTTP/1.1을 사용하는 것입니다.

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

docker login 명령이 access forbidden 오류로 실패하는 경우

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

예를 들어: 

> docker login gitlab.example.com:4567

사용자 이름: user
암호:
Error response from daemon: Get "https://gitlab.company.com:4567/v2/": denied: access forbidden

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