This page contains information related to upcoming products, features, and functionality. It is important to note that the information presented is for informational purposes only. Please do not rely on this information for purchasing or planning purposes. The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the sole discretion of GitLab Inc.

Status	Authors	Coach	DRIs	Owning Stage	Created
proposed	`@jdrpereira` `@10io`	`@grzesiek`	`@trizzi` `@crystalpoole`	devops package	2023-08-31

Google Artifact Registry 통합

요약

GitLab과 Google Cloud는 최근 플랫폼의 독특한 기능을 결합하기 위한 파트너십을 발표했습니다.

발표에서 강조된 바에 따르면, 한 가지 중요한 목표는 “GitLab 파이프라인 및 패키징에서 Google의 Artifact Registry를 사용하여 보안 데이터 플레인을 만드는 것” 입니다. 이 목표를 향한 초기 단계는 사용자가 새로운 Google Artifact Registry (이제 GAR로 약칭) 프로젝트 통합을 구성하고 GitLab UI에서 컨테이너 이미지 artifact를 표시할 수 있도록 하는 것입니다.

동기

GitLab과 Google Cloud의 파트너십의 동기와 장기적인 목표에 대한 자세한 내용은 발표 블로그 게시물을 참조하십시오.

이 설계 문서의 범위와 관련하여, 우리의 주요 관심은 사용자들에게 GAR에서 컨테이너 이미지에 대한 가시성을 제공하는 제품 요구를 충족시키는 것입니다. 구체적인 목표에 대한 동기는 GitLab 컨테이너 레지스트리를 보완하는 외부 레지스트리 사용에 대한 기본적인 연구에 근간을 두고 있습니다 (내부).

본격적인 GAR 통합의 첫 걸음으로서, 우리의 목표는 이러한 목표를 달성함으로써 미래에 재사용 가능성을 도모할 수 있는 기초를 마련하는 것입니다. 이 기반은 잠재적인 미래 확장 (예: 추가 Artifact 형식 지원 (npm, Maven 등), 패키지 단계 이상의 기능 (예: 취약성 스캔, 배포 등))에 도움이 될 수 있습니다.

목표

GitLab 사용자가 GAR에 연결하기 위한 새로운 프로젝트 통합을 구성할 수 있도록 함.
GitLab 프로젝트 당 단일 최상위 GAR 리포지터리로 한정.
Standard](https://cloud.google.com/artifact-registry/docs/repositories#mode) 모드의 GAR 리포지터리로 한정. 미리보기에서 Remote 및 Virtual 리포지터리 모드 지원 (둘 다)은 신축목표입니다.
컨테이너 이미지 형식의 GAR 리포지터리로 한정.
GitLab 프로젝트 소유자/유지 관리자가 제공하는 Google Cloud 서비스 계정을 사용하여 GAR와 상호 작용할 수 있도록 함.
GitLab 사용자가 연결된 GAR 리포지터리의 컨테이너 이미지를 디렉터리으로 표시할 수 있도록 함. 디렉터리은 페이지별로 볼 수 있으며 정렬할 수 있음.
각 디렉터리된 이미지에 대해 해당 URI, 태그 디렉터리, 크기, 다이제스트, 업로드 시간, 미디어 유형, 빌드 시간 및 업데이트 시간을 표시함. 여기서 여기에서 문서화됨.
연결된 GAR 리포지터리의 컨테이너 이미지 디렉터리은 Reporter+ 역할을 가진 사용자로 한정됨.

비목표

일부는 미래의 반복에서 목표가 될 수 있지만 현재는 범위에서 제외됨:

생성, 업데이트 및 삭제 작업.
동일 프로젝트 내에서 여러 (최상위) GAR 리포지터리에 연결하는 것.
컨테이너 이미지를 넘어 리포지터리 형식 지원.
Identity and Access Management (IAM) 권한/자격 증명에서 서비스 계정(service accounts) 이외의 지원.
GAR 정리 정책.
이미지 디렉터리 필터링(이름 또는 값으로). 현재의 GAR API는 필터링을 지원하지 않음.
Artifact 분석 및 취약성 스캔.

제안

디자인 및 구현 세부사항

프로젝트 통합

GAR에 대한 새로운 프로젝트 통합이 생성될 것입니다. 활성화된 후에는 이것이 사이드바의 “운영” 섹션에 “Google Artifact Registry” 항목을 표시합니다. 이것은 활성화된 경우 Harbor 통합도 여기에 표시됩니다.

GAR 통합은 프로젝트 소유자/유지 관리자가 활성화할 수 있으며, 설정 중에 네 가지 구성 매개변수를 제공해야 합니다:

GCP 프로젝트 ID: 대상 GAR 리포지터리가 있는 GCP 프로젝트의 전역적으로 고유한 식별자.
리포지터리 위치: 대상 GAR 리포지터리가 있는 GCP 위치.
리포지터리 이름: 대상 GAR 리포지터리의 이름.
GCP 서비스 계정 키: JSON 형식의 서비스 계정 키의 내용 (파일이 아님) (샘플).

인증

통합은 통합을 위해 단일 GCP 서비스 계정을 사용함으로써 단순화됩니다. 사용자들은 이 서비스 계정의 사용을 GCP 측에서 감사하고 필요할 때 권한을 취소할 수 있는 능력을 유지합니다.

통합 설정 중에 제공된 서비스 계정 키는 대상 GCP 프로젝트에서 적어도 Artifact Registry Reader 역할로 부여되어야 합니다.

(암호화된) 서비스 계정 키 JSON 내용을 백엔드에 저장함으로써 우리는 이를 쉽게 가져와 사용하여 GAR 클라이언트를 초기화할 수 있습니다 (추가로 알아볼 내용은 하단의 Client SDK 참조). 이 파일의 내용을 제공하고 그것을 업로드하는 것은 사용자의 공개 SSH 키와 유사합니다.

앞서 언급했듯이, GAR 통합 기능의 액세스는 Reporter+ 역할을 가진 사용자로 제한됩니다.

리소스 매핑

특정 프로젝트 내의 GitLab 컨테이너 레지스트리의 리포지터리는 프로젝트 전체 경로와 일치해야 합니다. 이것은 본질적으로 GitLab Rails와 레지스트리 간의 리소스 매핑을 설정하는 방법이며, 권한 부여를 더 상세히 하고, 리포지터리 사용량을 특정 프로젝트/그룹/네임스페이스에 제한하는 방법 등 다양한 목적에 사용됩니다.

GAR 통합에 관해서는 GitLab 프로젝트/그룹/네임스페이스 리소스에 대한 동등한 개체가 없기 때문에, 우리는 사용자들에게 각각의 경로와 상관없이 어떤 GAR 리포지터리라도 임의의 GitLab 프로젝트에 첨부할 수 있도록 하는 것으로 문제를 단순화하고자 합니다. 마찬가지로, 특정 GAR 리포지터리를 특정 GitLab 프로젝트에 첨부하는 것을 제한할 계획이 없습니다. 궁극적으로, 양쪽 데이터 세트를 자신들의 필요에 가장 잘 맞는 방식으로 구성하는 것은 사용자의 몫입니다.

GAR API

GAR은 Docker API, REST API 및 RPC API 세 가지 API를 제공합니다.

Docker API는 Docker Registry HTTP API V2를 기반으로 하며, 이제 OCI Distribution Specification API (OCI API로 지칭함)에 의해 대체되었습니다. 이 API는 GAR와 이미지를 밀어넣거나 끌어오는 작업뿐만 아니라 몇 가지 검색 작업을 제공합니다. 이것을 사용하지 않을 이유에 대해서는 대체 솔루션을 참조하십시오.

특허된 GAR API 중, REST API는 리포지터리를 관리하기 위한 기본적인 기능을 제공합니다. 이것은 컨테이너 이미지 리포지터리를 위한 list 및 get 작업을 포함하며, 이러한 작업은 이 통합에서 사용될 수 있습니다. 이 두 작업은 동일한 데이터 구조를 반환하며, DockerImage 객체로 표시됩니다. 따라서 둘 다 동일한 수준의 세부 정보를 제공합니다.

마지막으로, gRPC와 Protocol Buffers를 기반으로 하는 RPC API가 있습니다. 이 API는 모든 GAR 기능을 포함하며 가장 많은 기능을 제공합니다. 사용 가능한 작업 중 가장 필요한 ListDockerImagesRequest 및 GetDockerImageRequest 작업을 활용할 수 있습니다. REST API와 마찬가지로 두 응답은 DockerImage 객체로 구성됩니다.

두 가지 프로세스 API 옵션 중에서 우리는 미래 반복에 유익할 것이며, 오늘날 필요한 작업만 지원하는 것이 아니라 모든 GAR 기능을 더 잘 다루는 RPC API를 선택했습니다. 마지막으로, 우리는 이 API를 직접 사용하는 것이 아니라 공식 Ruby 클라이언트 SDK를 통해 사용할 것이며, 더 자세한 내용은 아래의 Client SDK를 참조하십시오.

백엔드 통합

이 통합은 Rails 프로젝트의 백엔드 쪽에서 여러 변경 사항이 필요합니다. 추가 세부 정보는 백엔드 페이지를 참조하세요.

UI/UX

이 통합에는 “Google Artifact Registry”라는 전용 페이지가 포함됩니다. 이 페이지는 측면 표시줄의 “운영” 섹션에 나열되며, 사용자가 구성된 GAR 리포지터리에 있는 모든 컨테이너 이미지 디렉터리을 볼 수 있게 합니다. 추가 세부 정보는 UI/UX 페이지를 참조하세요.

GraphQL API

TODO: 이 통합에 필요한 GraphQL API 또는 기존 API의 변경 사항을 설명하세요.

대체 솔루션

Docker/OCI API 사용

고려된 다른 대안 솔루션 중 하나는 GAR에서 제공하는 Docker/OCI API를 사용하는 것이었습니다. 컨테이너 레지스트리에 대한 공통 표준이기 때문에 이 접근 방식은 GitLab이 컨테이너 레지스트리에 연결하는 데 사용했던 기존 논리를 재사용할 수 있었으며, 개발 속도를 높일 수도 있었습니다. 그러나 이 접근 방식에는 몇 가지 단점이 있었습니다:

인증 복잡성: API는 인증 토큰이 필요했는데, 이는 로그인 엔드포인트에서 요청해야 했습니다. 이러한 토큰은 제한된 유효성을 가지며, 인증 프로세스에 복잡성을 추가했습니다. 만료된 토큰을 처리해야 했어야 했습니다.
한정된 포커스: API는 컨테이너 레지스트리 객체에만 집중되어 있었으며, 이는 추가적인 GAR 아티팩트(예: 패키지 레지스트리 포맷)를 유연한 통합 프레임워크를 만드는 목표와 일치하지 않았습니다.
검색 가능성 제한: API는 필터링이나 정렬과 같은 기능이 없어서 검색 가능성에 매우 제한이 있었습니다.
다중 요청: 각 이미지에 대한 모든 필요한 정보를 검색하려면 여러 엔드포인트(태그 디렉터리, 이미지 매니페스트 및 이미지 구성 블롭 획득)에 대한 여러 요청이 필요했는데, 이는 1+N 성능 문제로 이어질 수 있었습니다.

GitLab은 이전에 마지막 두 가지 제한으로 인해 중대한 도전을 겪었으며, 이를 해결하기 위해 사용자 정의 GitLab 컨테이너 레지스트리 API를 개발하기로 결정했습니다. 또한, 이러한 같은 제한 사항 및 두 가지 솔루션을 병행 유지하는 비용 증가로 인해 Docker/OCI API 엔드포인트를 사용하여 서드 파티 컨테이너 레지스트리에 연결하는 지원을 사용 중단하기로 결정했습니다. 결과적으로, GitLab은 모든 컨테이너 레지스트리 기능을위한 사용자 정의 API 엔드포인트로 Docker/OCI API 엔드포인트의 사용을 대체하는 노력이 진행 중입니다.

이러한 요인을 고려하여, GAR 통합을 GAR API를 사용하여 처음부터 빌드하기로 결정했습니다. 이 방식은 통합에 대한 더 많은 유연성과 제어를 제공하며, 지원이 가능할 수 있도록 다른 GAR 아티팩트 형식을 지원하는 것과 같이 미래의 확장을 위한 기반이 될 수 있습니다.