통합 컨테이너 레지스트리를 사용해 각 GitLab 프로젝트의 컨테이너 이미지를 저장할 수 있습니다.

관리자가 GitLab 인스턴스에서 컨테이너 레지스트리를 활성화해야 합니다. 자세한 내용은 GitLab 컨테이너 레지스트리 관리를 참고합니다.

컨테이너 레지스트리 보기#

프로젝트 또는 그룹의 컨테이너 레지스트리를 볼 수 있습니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트 또는 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Container Registry를 선택합니다.

컨테이너 이미지를 검색, 정렬, 필터링하고 삭제할 수 있습니다. 브라우저에서 URL을 복사해 필터링된 보기를 공유할 수 있습니다.

컨테이너 레지스트리에서 특정 컨테이너 이미지의 태그 보기#

컨테이너 레지스트리의 Tag Details 페이지에서 특정 컨테이너 이미지에 연결된 태그 목록을 볼 수 있습니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트 또는 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Container Registry를 선택합니다.
3. 컨테이너 이미지를 선택합니다.

게시 시점, 사용 중인 스토리지 용량, 매니페스트 및 구성 다이제스트 등 각 태그의 세부 정보를 확인할 수 있습니다.

이 페이지에서 태그를 검색, 정렬, 삭제할 수 있습니다. 태그는 Name 기준으로 정렬됩니다. 컨테이너 레지스트리 메타데이터 데이터베이스가 활성화되어 있으면 Published 기준으로도 정렬할 수 있으며, 이 값이 기본값으로 가장 최근에 게시된 태그가 먼저 표시됩니다. 브라우저에서 URL을 복사해 필터링된 보기를 공유할 수 있습니다.

멀티 아키텍처 이미지의 지원 플랫폼 보기#

Docker 매니페스트 목록 또는 OCI 이미지 인덱스(멀티 아키텍처 이미지)를 가리키는 태그를 보면 해당 이미지가 지원하는 플랫폼을 확인할 수 있습니다.

사전 요구 사항:

• GitLab Self-Managed의 경우 메타데이터 데이터베이스가 구성된 컨테이너 레지스트리. 자세한 내용은 컨테이너 레지스트리 메타데이터 데이터베이스를 참고합니다.

지원 플랫폼을 보려면 다음 절차를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트 또는 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Container Registry를 선택합니다.
3. 컨테이너 이미지를 선택합니다.
4. 멀티 아키텍처 태그의 세부 정보를 펼칩니다.

Supported platforms 행에는 linux/amd64, linux/arm64/v8 같은 플랫폼별 배지가 표시됩니다. Windows 이미지의 경우 알려진 빌드 번호가 windows/amd64 (ltsc2022) 같이 알아보기 쉬운 레이블로 매핑됩니다.

스토리지 사용량#

컨테이너 레지스트리 스토리지 사용량을 확인해 프로젝트와 그룹 전반의 컨테이너 리포지터리 크기를 추적하고 관리합니다.

자세한 내용은 컨테이너 레지스트리 사용량 보기를 참고합니다.

컨테이너 레지스트리의 컨테이너 이미지 사용#

컨테이너 레지스트리에 호스팅된 컨테이너 이미지를 내려받아 실행하려면 다음 절차를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트 또는 그룹을 찾습니다.

2. 왼쪽 사이드바에서 Deploy > Container Registry를 선택합니다.

3. 사용할 컨테이너 이미지를 찾아 Copy image path ([copy-to-clipboard])를 선택합니다.

4. 복사한 링크로 docker run을 실행합니다.

   docker run [options] registry.example.com/group/project/image [arguments]
   

컨테이너 이미지의 명명 규칙#

컨테이너 이미지는 다음 명명 규칙을 따라야 합니다.

<registry server>/<namespace>/<project>[/<optional path>]

예를 들어 프로젝트가 gitlab.example.com/mynamespace/myproject이면 컨테이너 이미지 이름도 gitlab.example.com/mynamespace/myproject여야 합니다.

컨테이너 이미지 이름 뒤에 최대 2단계까지 이름을 덧붙일 수 있습니다.

예를 들어 myproject 프로젝트의 컨테이너 이미지에서 다음 이름은 모두 유효합니다.

registry.example.com/mynamespace/myproject:some-tag

registry.example.com/mynamespace/myproject/image:latest

registry.example.com/mynamespace/myproject/my/image:rc1

컨테이너 레지스트리 리포지터리 이동 또는 이름 변경#

컨테이너 리포지터리의 경로는 항상 관련 프로젝트의 리포지터리 경로와 일치하므로, 컨테이너 레지스트리만 이름을 바꾸거나 이동할 수는 없습니다. 대신 다음 중 하나를 수행합니다.

• 프로젝트의 리포지터리 이름 변경.
• 프로젝트 이전.

성능상의 이유로, 컨테이너 리포지터리가 있는 프로젝트의 이름 변경은 컨테이너 리포지터리가 1,000개 이하인 프로젝트로 제한됩니다.

GitLab Self-Managed 인스턴스에서는 그룹이나 프로젝트를 이동하거나 이름을 바꾸기 전에 모든 컨테이너 이미지를 삭제할 수 있습니다. 또는 이슈 18383에 이 제약을 우회하는 커뮤니티 제안이 정리되어 있습니다. 에픽 9459에서는 컨테이너 리포지터리가 있는 프로젝트와 그룹을 GitLab Self-Managed에서 이동할 수 있도록 지원을 추가하는 방안을 제안하고 있습니다.

프로젝트의 컨테이너 레지스트리 비활성화#

컨테이너 레지스트리는 기본적으로 활성화되어 있습니다.

다만 프로젝트에서 컨테이너 레지스트리를 제거할 수 있습니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Visibility, project features, permissions 섹션을 펼치고 Container registry를 비활성화합니다.
4. Save changes를 선택합니다.

프로젝트 사이드바에서 Deploy > Container Registry 항목이 제거됩니다.

컨테이너 레지스트리 가시성 변경#

기본적으로 컨테이너 레지스트리는 프로젝트에 접근할 수 있는 모든 사용자에게 표시됩니다. 다만 프로젝트의 컨테이너 레지스트리 가시성은 변경할 수 있습니다.

이 설정이 사용자에게 부여하는 권한에 관한 자세한 내용은 컨테이너 레지스트리 가시성 권한을 참고합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.

2. 왼쪽 사이드바에서 Settings > General을 선택합니다.

3. Visibility, project features, permissions 섹션을 펼칩니다.

4. Container registry 아래에서 드롭다운 목록의 옵션을 선택합니다.

   • Everyone With Access (기본값): 컨테이너 레지스트리는 프로젝트에 접근할 수 있는 모든 사용자에게 표시됩니다. 프로젝트가 공개이면 컨테이너 레지스트리도 공개입니다. 프로젝트가 내부 또는 비공개이면 컨테이너 레지스트리도 내부 또는 비공개입니다.

   • Only Project Members: 컨테이너 레지스트리는 Reporter, Developer, Maintainer 또는 Owner 권한을 가진 프로젝트 멤버에게만 표시됩니다. 이 가시성은 Container Registry 가시성이 Everyone With Access로 설정된 비공개 프로젝트의 동작과 비슷합니다.

5. Save changes를 선택합니다.

컨테이너 레지스트리 가시성 권한#

컨테이너 레지스트리를 보고 컨테이너 이미지를 가져올 수 있는지는 컨테이너 레지스트리의 가시성 권한으로 결정됩니다. 가시성은 UI의 가시성 설정이나 API로 변경할 수 있습니다.

컨테이너 레지스트리 업데이트, 컨테이너 이미지 푸시 또는 삭제 등 다른 권한은 이 설정의 영향을 받지 않습니다. 다만 컨테이너 레지스트리를 비활성화하면 모든 컨테이너 레지스트리 작업이 비활성화됩니다. 자세한 내용은 역할 및 권한을 참고합니다.

지원되는 이미지 유형#

컨테이너 레지스트리는 Docker V2와 Open Container Initiative(OCI) 이미지 형식을 지원합니다. 또한 컨테이너 레지스트리는 OCI 배포 사양을 준수합니다.

OCI를 지원하므로 Helm 3 이상 차트 패키지처럼 OCI 기반 이미지 형식을 레지스트리에 호스팅할 수 있습니다. GitLab API와 UI에서는 이미지 형식을 구분하지 않습니다. 이슈 38047에서 Helm부터 이 구분을 다루고 있습니다.

컨테이너 이미지 서명#

GitLab 컨테이너 레지스트리에서는 OCI 1.1 매니페스트 subject 필드를 사용해 컨테이너 이미지를 Cosign 서명과 연결할 수 있습니다. 그러면 해당 서명의 태그를 따로 찾지 않고도 연결된 컨테이너 이미지와 함께 서명 정보를 확인할 수 있습니다.

컨테이너 이미지의 태그를 볼 때, 연결된 서명이 있는 태그 옆에는 아이콘이 표시됩니다. 서명의 세부 정보를 보려면 해당 아이콘을 선택합니다.

사전 요구 사항:

• 컨테이너 이미지에 서명하려면 Cosign v2.0 이상이 필요합니다.
• GitLab Self-Managed에서 서명을 표시하려면 메타데이터 데이터베이스가 구성된 GitLab 컨테이너 레지스트리가 필요합니다. 자세한 내용은 컨테이너 레지스트리 메타데이터 데이터베이스를 참고합니다.

OCI 참조자 데이터로 컨테이너 이미지 서명#

Cosign으로 서명에 참조자 데이터를 추가하려면 다음을 수행해야 합니다.

• COSIGN_EXPERIMENTAL 환경 변수를 1로 설정합니다.
• 서명 명령에 --registry-referrers-mode oci-1-1을 추가합니다.

예:

COSIGN_EXPERIMENTAL=1 cosign sign --registry-referrers-mode oci-1-1 <container image>