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

• GitLab 사용자 이름 및 비밀번호(2FA가 활성화된 경우 사용 불가)
• 개인 액세스 토큰
• 배포 토큰
• 프로젝트 액세스 토큰
• 그룹 액세스 토큰
• GitLab CLI

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

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

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

사용자 이름과 비밀번호로 인증하려면 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

토큰으로 인증 {#authenticate-with-a-token}#

토큰으로 인증하려면 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/CD 변수.

  이 변수는 컨테이너 레지스트리에 대한 읽기-쓰기 액세스 권한이 있는 job별 사용자를 보유합니다. 비밀번호도 자동으로 생성되어 CI_REGISTRY_PASSWORD에서 사용할 수 있습니다.

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

• CI job 토큰.

  이 토큰은 읽기(pull) 액세스에만 사용할 수 있습니다. read_registry 범위가 있지만 push 작업에 필요한 write_registry 범위는 없습니다.

  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 클라이언트를 사용한 자격 증명 검증에 대한 자세한 내용은 컨테이너 레지스트리 아키텍처를 참조하세요.

대용량 이미지 푸시 시 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분입니다.