• 용어
• 해결해야 할 문제
• 클라우드 커넥터 구성 요소
• 접근 통제
  • GitLab.com
  • GitLab Dedicated/Self-Managed
  • AI Gateway
• 참고자료

클라우드 커넥터: 아키텍처

GitLab Cloud Connector는 여러 GitLab 배포, 인스턴스 및 셀에서 공통적으로 사용하는 서비스에 접근하는 방법입니다. 현재로서는 Cloud Connector 자체가 전담 서비스가 아니라, Cloud 기반 서비스와 GitLab 인스턴스를 통합할 때 인증 및 기타 항목에 대한 접근 방식을 표준화하는 API와 코드의 집합입니다.

이 페이지는 Cloud Connector의 일반적인 아키텍처를 다루며, 주요 개발자 문서의 보조 자료로 읽히도록 설계되었습니다.

용어

Cloud Connector의 구성 요소와 메커니즘에 대해 이야기할 때, 우리는 다음 용어를 사용합니다:

• GitLab Rails: 주요 GitLab 애플리케이션입니다.
• GitLab.com: GitLab Inc.에서 운영하는 다중 임대형 GitLab SaaS 배포입니다.
• Dedicated: GitLab Inc.에서 운영하는 단일 임대형 GitLab SaaS 배포입니다.
• Self-managed: 고객이 운영하는 모든 GitLab 인스턴스, 잠재적으로 개인 클라우드에 배포됩니다.
• GitLab instance: 위의 모든 것.
• Backend service: GitLab 인스턴스가 Cloud Connector 기능 세트의 일환으로 기능을 제공하기 위해 호출하는 GitLab 운영 웹 서비스입니다. AI 게이트웨이는 하나의 예입니다.
• CustomersDot: GitLab 고객 포털, 고객이 자신의 GitLab 구독을 관리하는 데 사용하는 포털입니다.
• OIDC: OpenID Connect, 신원 공급자와 인증/권한 부여를 구현하기 위한 개방형 표준입니다. JWT 발급자는 JWT 검증기를 위한 키를 게시하기 위해 OIDC 호환 직면 엔드포인트를 제공합니다.
• JWT: JSON Web Token, 신원 데이터를 암호화된 서명 토큰 형식으로 인코딩하고 전송하기 위한 개방형 표준입니다. 이 토큰은 GitLab 인스턴스 또는 사용자와 백엔드 서비스 간의 요청을 승인하는 데 사용됩니다. GitLab 인스턴스 또는 사용자 둘 다에 대해 스코프될 수 있습니다.
• JWT issuer: JWT를 발급하기 위한 엔드포인트를 제공하는 GitLab 운영 웹 서비스입니다. OAuth 사양에서는 이를 Authorization Server라고 합니다. 이 토큰을 검증하는 데 필요한 공개 키를 제공하는 엔드포인트도 포함됩니다. GitLab.com, CustomersDot 및 AI Gateway는 모두 JWT 발급자입니다.
• JWT validator: JWT를 포함하고 있는 GitLab 인스턴스 요청을 검증하는 백엔드 서비스입니다. OAuth 사양에서는 이를 Resource Server라고 하며, JWT 발급자에서 얻은 공개 키를 사용합니다. AI Gateway는 JWT 검증기의 한 예입니다.
• IJWT: GitLab 인스턴스를 위해 생성된 Instance JSON Web Token입니다.
• UJWT: GitLab 사용자에 대해 생성된 User JSON Web Token으로, IJWT보다 짧은 수명과 더 적은 권한을 가진 JWT입니다.
• JWKS: JSON Web Key Set, JWTs를 검증하기 위해 암호화 키를 인코딩하기 위한 개방형 표준입니다.
• Unit primitives: 권한/접근 범위가 관리할 수 있는 논리적 기능입니다.
• Add-On 유닛 프리미티브의 그룹으로, 묶여서 함께 판매됩니다. 예: code_suggestions 및 duo_chat은 DUO_PRO 애드온 아래에 함께 판매되는 2개의 UP입니다.

해결해야 할 문제

대부분의 GitLab 기능은 배포 위치와 상관없이 GitLab 인스턴스에서 직접 제공될 수 있습니다. 그러나 일부 기능은 제3자 공급자 통합이 필요하거나 GitLab.com 외부에서 운영하기 어려운 경우가 있습니다. 이는 Self-managed 및 Dedicated 고객에게 문제를 제기하며, 이러한 기능에 쉽게 접근할 수 없습니다.

Cloud Connector는 다음과 같이 이 문제를 해결합니다:

• GitLab Rails에서 기능을 분리하여 GitLab 운영 서비스로 이동하여 고객이 이를 수동으로 구성하고 운영하는 번거로움을 덜어줍니다.

• Cloud Connector 기능에 대한 전 세계 단일 진입점을 cloud.gitlab.com에 제공하여 백엔드 서비스에 접근할 수 있도록 합니다.

• 인스턴스 라이선스 및 청구 데이터를 연결하여 접근 권한을 부여하고, GitLab 인스턴스가 GitLab Inc.에서 운영하는 백엔드 서비스에서 호스팅되는 기능을 사용할 수 있도록 지원합니다.

클라우드 커넥터 구성 요소

기술적으로 클라우드 커넥터는 다음 요소로 구성됩니다:

1. 전역 로드 밸런서. cloud.gitlab.com에서 Cloudflare를 통해 호스팅되며, AI와 같은 클라우드 커넥터 기능으로의 모든 트래픽은 이 호스트를 거쳐야 합니다. 로드 밸런서는 경로 접두사에 따라 라우팅 결정을 내립니다. 예를 들어:
   1. 로드 밸런서는 /prefix를 백엔드 서비스에 매핑합니다.
   2. 클라이언트는 cloud.gitlab.com/prefix/path를 요청합니다.
   3. 로드 밸런서는 /prefix를 제거하고 /path를 백엔드 서비스에 라우팅합니다.

2. GitLab.com 및 CustomersDot을 IJWT 발급자로 선출. 우리는 이러한 배포를 GitLab Inc.만 접근할 수 있는 개인 키로 구성합니다. 우리는 이 키를 사용하여 GitLab Rails 인스턴스가 연결된 서비스 백엔드에 요청을 하기 위해 사용할 수 있는 암호화된 IJWT를 발급합니다. 공개 검증 키는 OIDC 발견 API 엔드포인트를 사용하여 게시됩니다.

3. AI Gateway를 UJWT 발급자 및 검증기로 선출. 위에서 언급한 IJWT 발급자와 유사하지만 오직 사용자만을 위한 토큰을 발급하는 목적입니다. AI 게이트웨이는 자체 검증기이므로 검증 키는 OIDC 발견 API 엔드포인트에 게시되지 않습니다.

4. 백엔드 서비스를 IJWT 검증기로 선출. 백엔드 서비스는 정기적으로 GitLab.com 또는 CustomersDot과 동기화하여 요청에 첨부된 서비스 토큰의 서명을 검증하는 데 사용되는 공개 키를 얻습니다. 그런 다음 백엔드 서비스는 서명 유효성과 토큰 본문에 포함된 클레임에 따라 요청을 수락하거나 거부할 수 있습니다.

5. 위와 통합하기 위한 API 프로그래밍. 우리는 GitLab Rails 애플리케이션과 백엔드 서비스 간의 통신 구현을 쉽게 하기 위해 Ruby에서 필요한 인터페이스를 제공하는 것을 목표로 하고 있습니다. 이는 변동성이 큰 목표이며, 우리는 이를 개선하기 위해 클라우드 커넥터 추상화 서사에 문제를 기록합니다.

다음 다이어그램은 이러한 구성 요소가 어떻게 상호작용하는지를 보여줍니다:

접근 통제

백엔드 서비스에 요청할 때 두 가지 수준의 접근 통제가 있습니다:

1. 인스턴스 접근. 특정 SM/전용 인스턴스에 접근 권한을 부여하는 것은 고객의 클라우드 라이센스 청구 상태에 바인딩된 IJWT를 발급함으로써 이루어집니다. 이 토큰은 CustomersDot에서 하루에 한 번 GitLab 인스턴스로 동기화되어 인스턴스의 로컬 데이터베이스에 저장됩니다. GitLab.com의 경우, 이 단계를 요구하지 않으며 대신 각 요청에 대해 짧은 수명의 토큰을 발급합니다. 이 토큰은 JWT로 구현되어 발급자에 의해 암호화된 서명이 있습니다.

2. 사용자 접근. 현재 모든 최종 사용자 요청이 최소한 한 번은 각각의 GitLab 인스턴스를 통해 이루어지기를 기대합니다. 특정 요청(예: 코드 완성)에 대해 사용자가 백엔드 서비스에 직접 요청을 할 수 있도록 백엔드 범위의 UJWT를 사용할 수 있도록 허용합니다. 이 토큰은 인스턴스 토큰보다 제한된 수명과 접근 권한을 가지고 있습니다. 사용자 토큰을 얻으려면 사용자는 먼저 해당 GitLab 인스턴스를 통해 토큰을 요청해야 합니다. 따라서 사용자 수준의 인증 및 권한 부여는 일반적인 REST 또는 GraphQL API 요청과 같이 처리됩니다. 즉, OAuth 또는 개인 접근 토큰을 사용해야 합니다.

인스턴스 접근을 위해 발급된 JWT는 다음과 같은 클레임을 포함합니다(완전하지 않으며 변경될 수 있음):

• aud: 청중. 이 백엔드 서비스의 이름입니다 (예: gitlab-ai-gateway).
• sub: 주체. 이 토큰이 발급된 GitLab 인스턴스의 UUID입니다 (예: 8f6e4253-58ce-42b9-869c-97f5c2287ad2).
• iss: 발급자 URL. https://gitlab.com 또는 https://customers.gitlab.com.
• exp: 토큰의 만료 시간 (UNIX 타임스탬프). 현재 GitLab.com은 1시간, SM/전용의 경우 3일입니다.
• nbf: 이 토큰을 사용할 수 없는 시간 (UNIX 타임스탬프), 이 시점은 토큰이 발급되기 전 5초로 설정됩니다.
• iat: 이 토큰이 발급된 시간 (UNIX 타임스탬프), 이 시점은 토큰이 발급된 시간으로 설정됩니다.
• jti: JWT ID, 임의로 생성된 UUID로 설정됩니다 (예: 0099dd6c-b66e-4787-8ae2-c451d86025ae).
• gitlab_realm: 자체 관리와 GitLab.com에서의 요청을 구분하는 문자열입니다. Customers Portal에서 발급된 경우 self-managed이며 GitLab.com에서 발급된 경우 saas입니다.
• scopes: 이 토큰이 유효한 기능을 정의하는 접근 범위 리스트입니다. 우리는 이러한 범위를 어떻게 유료 기능이 GitLab 티어와 추가 기능에 번들링되는지에 대한 결정에 따라 얻습니다.

사용자 접근을 위해 발급된 JWT는 다음과 같은 클레임을 포함합니다 (완전하지 않으며 변경될 수 있음):

• aud: 청중. 이 백엔드 서비스의 이름입니다 (gitlab-ai-gateway).
• sub: 주체. 이 토큰이 발급된 GitLab 사용자의 전 세계적으로 고유한 익명 사용자 ID 해시입니다 (예: W2HPShrOch8RMah8ZWsjrXtAXo+stqKsNX0exQ1rsQQ=).
• iss: 발급자 (gitlab-ai-gateway).
• exp: 토큰의 만료 시간 (UNIX 타임스탬프). 현재 발급 시점에서 1시간입니다.
• nbf: 이 토큰을 사용할 수 없는 시간 (UNIX 타임스탬프), 이 시점은 토큰이 발급된 시간으로 설정됩니다.
• iat: 이 토큰이 발급된 시간 (UNIX 타임스탬프), 이 시점은 토큰이 발급된 시간으로 설정됩니다.
• jti: JWT ID, 임의로 생성된 UUID로 설정됩니다 (예: 0099dd6c-b66e-4787-8ae2-c451d86025ae).
• gitlab_realm: 자체 관리와 GitLab.com에서의 요청을 구분하는 문자열입니다. self-managed 또는 saas입니다.
• scopes: 이 토큰이 유효한 기능을 정의하는 접근 범위 리스트입니다. 우리는 이러한 범위를 어떻게 유료 기능이 GitLab 티어와 추가 기능에 번들링되는지 및 사용자 토큰으로 접근이 허용되는 기능에 대한 결정에 따라 얻습니다.

JWKS는 토큰 검증기가 토큰의 서명을 검증하는 데 사용하는 공개 키를 포함합니다. 모든 백엔드 서비스는 현재 다음을 요구합니다:

• GitLab.com 및 CustomersDot에서 JWKS를 정기적으로 새로 고쳐 키 회전이 서비스 중단 없이 쉽게 그리고 정기적으로 이루어질 수 있도록 합니다.
• 각 요청에 대해 JWT의 서명 검증 및 접근 범위 확인을 수행합니다.

다음 흐름 차트는 사용자가 AI 채팅 봇과 같은 클라우드 커넥터 기능을 사용할 때 발생하는 일을 이해하는 데 도움이 될 것입니다, GitLab.com과 전용/자체 관리 배포 모두에 대해.

GitLab.com

GitLab.com 배포는 특별한 신뢰를 가지고 있기 때문에, Cloud Connector 기능에 대한 모든 요청에 대해 IJWT를 자가 서명하고 생성할 수 있는 장점이 있습니다. 이는 흐름을 크게 단순화합니다:

GitLab Dedicated/Self-Managed

전용 및 자체 관리 인스턴스의 주요 문제는 신뢰 위임입니다:
어떤 개별 자체 관리 인스턴스를 신뢰하고 토큰을 발급하도록 할 수는 없습니다.
하지만 고객 인스턴스가 GitLab Inc.에서 운영하는 CustomersDot으로 정기적으로 권한을 부여하도록 하여 신뢰를 위임할 수 있습니다.
우리는 GitLab 전용 인스턴스를 제어하지만, 간단함을 위해 현재는 Cloud Connector 관점에서 “자체 관리”로 간주합니다.

GitLab.com과의 주요 차이점은 고객 인스턴스가 정기적으로 동기화하여 GitLab 백엔드 서비스에 접근하는 데 필요한 데이터를 가져오는 CustomersDot 액터의 추가입니다.

Cloud Connector 접근 데이터는 인스턴스의 로컬 데이터베이스에 저장되는 구조화된 JSON 데이터입니다.
IJWT 위에 추가된 정보에는 서비스가 완전히 출시된 것으로 간주되는지 또는 베타 단계인지에 대한 정보가 포함됩니다.
이 정보는 업그레이드 주기를 제어하지 않는 자체 관리 인스턴스에 특히 유용합니다.
왜냐하면 변경될 수 있는 데이터를 동기화하고 일부 GitLab 기능에 대한 접근을 원격으로 제어할 수 있기 때문입니다.

AI Gateway

AI Gateway는 사용자가 AI Gateway와 직접 통신할 수 있도록 설계된 UJWT를 발급할 수 있습니다.
즉, 먼저 GitLab 인스턴스에 호출할 필요가 없습니다.
이는 IJWT를 사용하는 것 외에도 가능합니다.
오직 GitLab 인스턴스만 UJWT를 요청할 수 있으며, 이는 IJWT로 요청을 하는 방식으로 이루어집니다.
그 후 AI Gateway는 인스턴스가 사용자에게 전달할 수 있는 단기 유효 UJWT를 반환합니다.
클라이언트는 이 UJWT를 사용하여 AI Gateway와 직접 통신할 수 있습니다.

참고자료

• 클라우드 커넥터 디자인 문서 및 ADR