컨테이너 레지스트리로 인증하려면 다음을 사용할 수 있습니다:

• GitLab 사용자 이름 및 비밀번호(2FA가 활성화된 경우 사용 불가)

• 개인 액세스 토큰

• 배포 토큰

• 프로젝트 액세스 토큰

• 그룹 액세스 토큰

• GitLab CLI

토큰 기반 인증 방법의 경우 필요한 최소 범위:

• 읽기(pull) 액세스의 경우 read_registry여야 합니다.

• 쓰기(push) 액세스의 경우 write_registry 및 read_registry여야 합니다.

Admin Mode는 컨테이너 레지스트리 인증 중에는 적용되지 않습니다. Admin Mode가 활성화된 관리자가 admin_mode 범위 없이 개인 액세스 토큰을 생성하면 Admin Mode가 활성화되어 있더라도 해당 토큰이 작동합니다. 자세한 내용은 Admin Mode를 참조하세요.

사용자 이름 및 비밀번호로 인증#

계정에서 이메일 OTP를 포함하여 이중 인증(2FA)을 활성화한 경우 토큰으로 인증해야 합니다.

사용자 이름과 비밀번호로 인증하려면 docker login 명령을 실행합니다:

docker login registry.example.com -u <username> -p <password>

보안 상의 이유로 -p 대신 --password-stdin 플래그를 사용하는 것을 권장합니다:

echo "<password>" | docker login registry.example.com -u <username> --password-stdin

토큰으로 인증#

토큰으로 인증하려면 docker login 명령을 실행합니다:

TOKEN=<token>
echo "$TOKEN" | docker login registry.example.com -u <username> --password-stdin

인증 후 클라이언트는 자격 증명을 캐시합니다. 이후 작업은 지정된 작업만 수행하도록 승인된 JWT 토큰을 반환하는 인증 요청을 합니다. 토큰은 다음 기간 동안 유효합니다:

• GitLab Self-Managed에서 기본적으로 5분

• GitLab.com에서 15분

GitLab CI/CD를 사용하여 인증#

CI/CD를 사용하여 컨테이너 레지스트리로 인증하려면 다음을 사용할 수 있습니다:

• CI_REGISTRY_USER 및 CI_REGISTRY_PASSWORD CI/CD 변수.

CI_REGISTRY_USER는 컨테이너 레지스트리에 대한 읽기-쓰기 액세스 권한이 있는 job별 사용자를 보유하며, CI_REGISTRY_PASSWORD는 자동으로 생성된 해당 비밀번호를 보유합니다.

echo "$CI_REGISTRY_PASSWORD" | docker login $CI_REGISTRY -u $CI_REGISTRY_USER --password-stdin

• CI job 토큰.

이 토큰은 job을 실행하는 프로젝트의 컨테이너 레지스트리에 대한 읽기(pull) 및 쓰기(push) 액세스 권한을 가집니다. CI/CD job 토큰 허용 목록은 다른 프로젝트의 레지스트리에 대한 액세스를 제어합니다.

echo "$CI_JOB_TOKEN" | docker login $CI_REGISTRY -u $CI_REGISTRY_USER --password-stdin

gitlab-ci-token 체계를 사용할 수도 있습니다:

echo "$CI_JOB_TOKEN" | docker login $CI_REGISTRY -u gitlab-ci-token --password-stdin

• 다음 최소 범위를 가진 GitLab 배포 토큰:

읽기(pull) 액세스의 경우 read_registry.

• 쓰기(push) 액세스의 경우 read_registry 및 write_registry.

  echo "$CI_DEPLOY_PASSWORD" | docker login $CI_REGISTRY -u $CI_DEPLOY_USER --password-stdin
  

• 다음 최소 범위를 가진 개인 액세스 토큰:

읽기(pull) 액세스의 경우 read_registry.

• 쓰기(push) 액세스의 경우 read_registry 및 write_registry.

  echo "<access_token>" | docker login $CI_REGISTRY -u <username> --password-stdin
  

트러블슈팅#

오류: 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 엔드포인트로 리다이렉트하고 있을 수 있습니다.

Docker 클라이언트를 사용한 자격 증명 검증에 대한 자세한 내용은 컨테이너 레지스트리 아키텍처를 참조하세요.

오류: docker login이 인증 오류로 실패#

GitLab이 docker login 요청을 거부하면 Docker 클라이언트는 오류 코드와 메시지가 포함된 JSON 오류 엔벨로프를 표시합니다.

오류를 해결하려면 오류 코드를 확인하고 다음 안내를 따르세요:

• UNAUTHORIZED (401): GitLab이 자격 증명을 확인할 수 없습니다. 해결하려면:

비밀번호 또는 토큰이 올바르고 만료되지 않았는지 확인합니다.

• 개인 액세스 토큰 또는 배포 토큰이 pull 액세스의 경우 read_registry 범위를, push 액세스의 경우 read_registry 및 write_registry 범위를 가지고 있는지 확인합니다.

• 계정에서 이중 인증을 사용하는 경우 비밀번호 대신 토큰으로 인증합니다. 자세한 내용은 토큰으로 인증을 참조하세요.

• DENIED (403): GitLab이 액세스를 거부했습니다. 메시지를 확인하세요:

access forbidden: 자격 증명은 유효하지만 레지스트리 액세스 권한을 부여하지 않습니다. 토큰이 read_registry 범위(push 액세스의 경우 write_registry)를 가지고 있는지, 그리고 역할이 프로젝트의 레지스트리에 대한 액세스를 허용하는지 확인합니다.

• Pushing to protected repository path forbidden: 대상 경로가 컨테이너 레지스트리 보호 규칙으로 보호되어 있습니다.

• Access denied: too many failed authentication attempts from this network: 남용 방지 기능이 네트워크를 차단했습니다. 차단이 만료될 때까지 기다리거나 다른 네트워크에서 다시 시도하세요.

• Access denied: too many distinct sources for this account: 계정이 너무 많은 IP 주소에서 사용되었습니다. 계정이 사용되는 위치를 검토한 다음 요청을 통합하거나 분산하세요.

• UNSUPPORTED (404): GitLab이 요청된 인증 서비스를 인식하지 못합니다. 해결하려면:

레지스트리 토큰 서비스가 올바르게 구성되어 있는지 확인합니다.

Docker 클라이언트가 대신 unexpected end of JSON input을 보고하는 경우 응답 본문이 비어 있거나 잘못된 JSON을 포함하고 있습니다:

오류: unexpected end of JSON input#

GitLab 앞의 프록시 또는 로드 밸런서가 응답 본문을 제거하면 다음과 같은 오류가 발생할 수 있습니다:

Error response from daemon: error parsing HTTP <status> response body: unexpected end of JSON input: ""

이 문제를 해결하려면 Docker 클라이언트와 GitLab 사이의 요청 경로를 확인하세요.

오류: 대용량 이미지 푸시 시 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 Self-Managed 인스턴스의 컨테이너 레지스트리 토큰은 5분 후에 만료됩니다. GitLab.com에서 토큰 만료 시간은 15분입니다.