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

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

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

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

컨테이너 이미지를 GitLab 레지스트리로 마이그레이션하는 것은 지원되지 않지만, 에픽이 이 동작을 변경할 것을 제안합니다.

타사 도구를 사용하여 컨테이너 이미지를 마이그레이션할 수 있습니다. 예를 들어, 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 오류

Docker 매니페스트 리스트를 푸시할 때 GitLab 컨테이너 레지스트리에 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 대형 이미지 푸시 시

대형 이미지를 푸시할 때 다음과 같은 인증 오류가 발생할 수 있습니다:

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 작업 토큰 범위를 가진 프로젝트에서 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

Username: user
Password:
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 매니페스트를 처리할 수 있는지 확인하십시오.