Cloud Connector: 아키텍처

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

이 페이지는 Cloud Connector의 일반 아키텍처를 다루며, 주 개발자 문서의 보조 자료로서 참고용으로 작성되었습니다.

용어

Cloud Connector의 구성 및 기술에 관한 대화 시 다음 용어를 사용합니다.

GitLab Rails: 주요 GitLab 애플리케이션입니다.
GitLab.com: GitLab Inc.가 운영하는 멀티 테넌트 GitLab SaaS 배포.
전용: GitLab Inc.가 운영하는 단일 테넌트 GitLab SaaS 배포.
Self-managed: 고객이 운영하는 GitLab 인스턴스로, 개인 클라우드에 배포될 수 있습니다.
GitLab 인스턴스: 위에서 언급된 GitLab과 같은 것입니다.
백엔드 서비스: GitLab 인스턴스에서 호출되어 Cloud Connector 기능 집합의 일부인 기능을 제공하는 GitLab 운영 웹 서비스입니다. AI 게이트웨이가 한 예시입니다.
CustomersDot: 고객이 GitLab 구독을 관리하는 데 사용하는 GitLab Customers Portal입니다.
서비스 토큰: GitLab 인스턴스와 백엔드 서비스 사이의 요청을 승인하는 데 사용되는 암호화된 토큰입니다.
서비스 토큰 발급자: 서비스 토큰을 발급하거나 해당 토큰을 유효성 검사하는 데 필요한 공개 키를 제공하는 GitLab 운영 웹 서비스입니다. GitLab.com 및 CustomersDot은 서비스 토큰 발급자입니다.
서비스 토큰 유효성 검사기: 서비스 토큰 발급자로부터 얻은 공개 키를 사용하여 서비스 토큰이 첨부된 GitLab 인스턴스 요청을 유효성 검사하는 백엔드 서비스입니다. AI 게이트웨이가 서비스 토큰 유효성 검사기의 한 예시입니다.
OIDC: OpenID Connect로, ID 공급자 및 인증/인가를 구현하는 데 사용되는 오픈 표준입니다. 서비스 토큰 발급자는 OIDC 호환 검색 엔드포인트를 제공하여 서비스 토큰 유효성 검사기의 공개 키를 게시합니다.
JWT: JSON Web Token으로, ID 데이터를 인코딩하고 전송하는 오픈 표준입니다.
JWKS: JSON Web Key Set으로, JWT 유효성 검사를 위한 암호화 키를 인코딩하는 오픈 표준입니다.

해결해야 할 문제

대부분의 GitLab 기능은 배포 위치에 관계 없이 GitLab 인스턴스에서 직접 제공될 수 있습니다. 그러나 일부 기능은 제 3자 공급업체 통합이 필요하거나 GitLab.com 외부에서 운영하기 어려운 기능이 있습니다. 이는 Self-managed 및 Dedicated 고객에게 문제를 제기합니다. 왜냐하면 그러한 기능에 쉽게 액세스할 수 없기 때문입니다.

Cloud Connector는 다음과 같은 방법으로 이 문제를 해결합니다:

GitLab Rails에서 기능을 이동하여 GitLab 운영 서비스에서 수동으로 구성하고 운영하는 수고를 덜어줍니다.
cloud.gitlab.com에서 Cloud Connector 기능에 대한 단일 글로벌 진입점을 제공하여 백엔드 서비스에 액세스합니다.
GitLab 인스턴스가 GitLab Inc.가 운영하는 백엔드 서비스에 호스팅된 기능을 사용할 수 있도록 인스턴스 라이선스 및 요금 청구 데이터를 연결하여 액세스 권한을 부여합니다.

Cloud Connector 구성 요소

기술적으로, Cloud Connector에는 다음과 같은 구성 요소가 포함됩니다:

글로벌 로드 밸런서. Cloudflare를 통해 cloud.gitlab.com에 호스팅되며, AI와 같은 Cloud Connector 기능으로의 모든 트래픽은 이 호스트를 통과해야 합니다. 로드 밸런서는 경로 접두사에 따라 라우팅 결정을 내립니다. 예를 들어:
1. 로드 밸런서는 /prefix를 백엔드 서비스로 매핑합니다.
2. 클라이언트가 cloud.gitlab.com/prefix/path를 요청합니다.
3. 로드 밸런서는 /prefix를 제거하고 /path를 백엔드 서비스로 라우팅합니다.
GitLab.com 및 CustomersDot을 서비스 토큰 발급자로 선출. 이러한 배포에는 GitLab Inc.만 액세스할 수 있는 개인 키가 구성되어 있습니다. 우리는 이러한 키를 사용하여 GitLab Rails 인스턴스가 연결된 서비스 백엔드로의 요청에 사용할 암호화된 서비스 토큰을 발급합니다. 공개 유효성 검사 키는 OIDC 검색 API 엔드포인트를 사용하여 게시됩니다.
백엔드 서비스를 서비스 토큰 유효성 검사기로 선출. 백엔드 서비스는 정기적으로 GitLab.com 또는 CustomersDot과 동기화하여 요청에 첨부된 서비스 토큰의 서명을 유효성 검사하는 데 사용되는 공개 키를 얻습니다. 그런 다음 백엔드 서비스는 서명의 유효성과 토큰 본문에 포함된 클레임을 기반으로 요청을 수락하거나 거부하게 됩니다.
상기 항목과 통합하기 위한 API 프로그래밍. 우리는 GitLab Rails 애플리케이션과 백엔드 서비스 간 통신을 구현하기 쉽도록 러비에서 필요한 인터페이스를 제공하기 위해 노력합니다. 이는 계속 변하는 과정이며, 이를 개선하기 위해 Cloud Connector 추상화 이픽에 이슈를 등록합니다.

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

접근 제어

백엔드 서비스로의 요청 시 두 가지 수준의 접근 제어가 있습니다.

인스턴스 접근. 특정 SM/Dedicated 인스턴스 액세스를 부여하는 것은 고객의 클라우드 라이선스 요금 청구 상태에 바인딩된 서비스 토큰을 발급함으로써 이루어집니다. 이 토큰은 CustomersDot으로부터 매일 GitLab 인스턴스로 동기화되어 인스턴스의 로컬 데이터베이스에 저장됩니다. GitLab.com의 경우 이 단계가 필요하지 않으며 각 요청에 대해 단명한 토큰을 발급합니다. 이러한 토큰은 JWT로 구현되며 발급자에 의해 암호화 서명됩니다.
사용자 액세스. 현재 우리는 최종 사용자 요청이 모두 해당 GitLab 인스턴스를 통과하도록 예상하고 있습니다. 따라서 사용자 수준의 인증 및 권한 부여는 REST 또는 GraphQL API 요청처럼 처리됩니다. 즉, OAuth 또는 개인 액세스 토큰을 사용합니다.

인스턴스 접근용으로 발급된 JWT는 다음 클레임을 가집니다(완전하지 않고 변경될 수 있음):

aud: 청중(Audience). 이것은 백엔드 서비스의 이름입니다(예: gitlab-ai-gateway).
iss: 발급자 URL. https://gitlab.com 또는 https://customers.gitlab.com 중 하나입니다.
exp: 토큰의 만료 시간(UNIX 타임스탬프). 현재 GitLab.com은 1시간, SM/Dedicated는 3일입니다.
scopes: 이 토큰이 유효한 기능을 정의하는 액세스 스코프 목록입니다. GitLab 티어와 애드온에 유료 기능이 어떻게 번들로 구성되는지 등의 결정을 기반으로 얻습니다.

JSON 웹 키 세트(JWKS)에는 토큰 검증기가 토큰의 서명을 확인하는 데 사용하는 공개 키가 포함되어 있습니다. 모든 백엔드 서비스는 현재 다음을 수행해야 합니다:

JWKS를 GitLab.com 및 CustomersDot에서 정기적으로 새로 고쳐 키 회전을 쉽게 정기적으로 발생시켜 서비스 중단 없이 할 수 있도록 합니다.
각 요청에 대해 JWT 서명 검증 및 액세스 스코프 확인을 수행합니다.

다음 플로우 차트는 사용자가 클라우드 커넥터 기능을 사용할 때, 즉 AI 챗봇과 대화하는 경우 GitLab.com 및 전용/셀프 관리 배포용으로 어떤 일이 발생하는지 이해하는 데 도움이 될 것입니다.

GitLab.com

GitLab.com 배포는 특별한 신뢰를 즐기므로 모든 요청에 대해 자체 서비스 토큰을 자체 서명하고 생성할 수 있는 장점이 있으므로 흐름을 크게 간소화할 수 있습니다:

sequenceDiagram autonumber participant U as 사용자 participant GL as GitLab.com participant SB as 백엔드 서비스 Note over U,SB: 최종 사용자 흐름 U->>GL: GitLab 인스턴스로 권한 부여 GL-->>U: PAT 또는 Cookie U->>GL: 클라우드 커넥터 기능 사용 GL->>GL: Cookie 또는 PAT로 인증/권한 부여 수행 GL->>GL: 사용자가 기능 사용이 허용되었는지 확인 GL->>GL: 서명된 서비스 토큰 생성 GL->>SB: 서비스 토큰으로 기능 요청 SB->>GL: 공개 서명 키 검색(필요한 경우) GL-->>SB: JSON 웹 키 세트(JWKS) SB->>SB: 키로 서비스 토큰 유효성 검사 SB-->>GL: 기능 페이로드

GitLab Dedicated/셀프 관리

전용 및 셀프 관리형 인스턴스의 주요 문제는 신뢰 위임입니다: 개별 자체 관리형 인스턴스를 신뢰할 수 없으며 토큰을 발급할 수 없지만, 인스턴스가 정기적으로 자체를 CustomersDot으로 승인하게하여 신뢰를 위임할 수 있습니다. 현재 우리는 GitLab 전용 인스턴스를 제어하지만 편의상 클라우드 커넥터 측면에서는 “셀프 관리형”으로 간주합니다.

GitLab.com과의 주요 차이점은 고객 인스턴스가 정기적으로 동기화하여 GitLab 백엔드 서비스에 액세스하기 위해 필요한 데이터를 검색 및 저장하는 CustomersDot 액터가 추가된 것입니다.

sequenceDiagram autonumber participant U as 사용자 participant GL as SM/Dedicated GitLab participant CD as CustomersDot participant SB as 백엔드 서비스 Note over GL,CD: 백그라운드: 액세스 데이터 동기화 loop cron job GL->>CD: 라이선스 키 전송 CD->>CD: 라이선스 키로 고객 구독 확인 CD->>CD: JWT 서비스 토큰 작성 및 서명 CD-->>GL: 클라우드 커넥터 액세스 데이터 + 서비스 토큰 GL->>GL: DB에 액세스 데이터 + 서비스 토큰 저장 end Note over U,SB: 최종 사용자 흐름 U->>GL: GitLab 인스턴스로 권한 부여 GL-->>U: PAT 또는 Cookie U->>GL: 클라우드 커넥터 기능 사용 GL->>GL: Cookie 또는 PAT로 인증/권한 부여 수행 GL->>GL: 사용자가 기능 사용이 허용되었는지 확인 GL->>GL: DB에서 서비스 토큰 로드 GL->>SB: 서비스 토큰으로 기능 요청 SB->>CD: 공개 서명 키 검색(필요한 경우) CD-->>SB: JSON 웹 키 세트(JWKS) SB->>SB: 키로 서비스 토큰 유효성 검사 SB-->>GL: 기능 페이로드

클라우드 커넥터 액세스 데이터는 인스턴스의 로컬 데이터베이스에 저장된 형식화된 JSON 데이터입니다. 서비스 토큰 위에 추가 정보를 포함하며, 서비스가 완전히 출시되었는지 또는 베타 단계인지 등의 서비스를 이용할 수 있는 추가 정보를 포함합니다. 이 정보는 특히 업그레이드 주기를 제어하지 않는 셀프 관리형 인스턴스에 유용합니다. 왜냐하면 변경될 수 있는 데이터를 동기화하고 원격으로 일부 GitLab 기능에 대한 액세스를 제어할 수 있기 때문입니다.

참조

Cloud Connector 블루프린트 및 ADR