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

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

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

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

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

컨테이너 이미지를 이관하려면 skopeo와 같은 타사 도구를 사용할 수 있습니다. skopeo를 사용하여 컨테이너 이미지를 여러 저장 메커니즘 간에 복사할 수 있습니다. skopeo를 사용하면 컨테이너 레지스트리, 컨테이너 저장 백엔드, 로컬 디렉터리, 로컬 OCI 레이아웃 디렉터리에서 GitLab 컨테이너 레지스트리로 복사할 수 있습니다.

도커 연결 오류

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

  • 선행 밑줄
  • 후행 하이픈 또는 대시

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

도커 엔진 17.11 이하를 사용하는 경우 404 Not Found 또는 Unknown Manifest 오류 메시지가 표시될 수 있습니다. 현재 버전의 도커 엔진은 v2 API를 사용합니다.

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

매니페스트 목록을 푸시할 때 Registry의 알 수 없는 Blob 오류

GitLab 컨테이너 레지스트리에 도커 매니페스트 목록을 푸시하는 경우, manifest blob unknown: blob unknown to registry 오류 메시지가 표시될 수 있습니다. 이 오류는 동일한 레지스트리가 아닌 여러 레포지토리에 흩어진 서로 다른 아키텍처를 가진 여러 이미지를 보유하고 있는 경우 발생할 수 있습니다.

예를 들어 다음과 같이 두 이미지가 있는 경우:

  • amd64 플랫폼
  • arm64v8 플랫폼

이러한 이미지로 멀티 아키텍처 이미지를 빌드하려면 해당 이미지를 멀티 아키텍처 이미지와 동일한 레포지토리에 푸시해야 합니다.

Registry의 알 수 없는 Blob 오류를 해결하려면 개별 이미지의 태그 이름에 아키텍처를 포함시키십시오. 예를 들어 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

자세한 내용은 이슈를 참조하십시오.

큰 이미지를 푸시할 때 허가되지 않음: 인증이 필요함 메시지

큰 이미지를 푸시하는 경우 다음과 유사한 인증 오류를 받을 수 있습니다: 

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을 사용하는 경우 관리자는 토큰 지속 기간을 늘릴 수 있습니다.

이미지를 가져오는 데 실패한 메시지

CI/CD 작업에서 프로젝트에서 컨테이너 이미지를 가져오지 못하는 경우 이미지 가져오기 실패 오류 메시지를 받을 수 있습니다. 이는 CI/CD 작업 토큰 범위 제한이 있는 프로젝트에서 발생할 수 있습니다.

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 엔드포인트로 리디렉션하는지 확인하세요.

OCI manifest found, but accept header does not support OCI manifests 오류

이미지를 끌어오지 못하는 경우, 레지스트리 로그에 다음과 유사한 오류가 있을 수 있습니다: 

manifest unknown: OCI manifest found, but accept header does not support OCI manifests

이 오류는 클라이언트가 올바른 Accept: application/vnd.oci.image.manifest.v1+json 헤더를 제출하지 않았을 때 발생합니다. Docker 클라이언트 버전이 최신인지 확인하세요. 서드 파티 도구를 사용하는 경우 OCI 매니페스트를 처리할 수 있는지 확인하세요.