Cloud Connector: 아키텍처

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

이 페이지는 Cloud Connector의 일반적인 아키텍처를 다루며, 기존 개발자 문서에 보충 자료로 사용됩니다.

용어

Cloud Connector의 컴포넌트 및 메커니즘에 대해 이야기할 때 다음 용어가 사용됩니다:

  • GitLab Rails: 주요 GitLab 응용 프로그램.
  • GitLab.com: GitLab Inc.가 운영하는 멀티 테넌트 GitLab SaaS 배포.
  • 전용 (Dedicated): GitLab Inc.가 운영하는 단일 테넌트 GitLab SaaS 배포.
  • Self-Managed형: 고객이 운영하는 모든 GitLab 인스턴스로, 사설 클라우드에 배포될 수 있습니다.
  • GitLab 인스턴스: 상기 모든 인스턴스.
  • 백엔드 서비스: GitLab 인스턴스에 의해 호출되는 GitLab이 제공하는 웹 서비스로, Cloud Connector 기능 세트의 일부인 기능을 제공합니다. AI 게이트웨이가 한 예입니다.
  • CustomersDot: 고객이 GitLab 구독을 관리하는 데 사용하는 GitLab Customers Portal.
  • 서비스 토큰: GitLab 인스턴스와 백엔드 서비스 간의 요청을 승인하는 데 사용되는 암호화된 토큰.
  • 서비스 토큰 발급자: 서비스 토큰 또는 해당 토큰의 유효성을 검증하기 위한 공개 키를 제공하기 위한 엔드포인트를 제공하는 GitLab이 운영하는 웹 서비스. GitLab.com 및 CustomersDot 모두 서비스 토큰 발급자입니다.
  • 서비스 토큰 검증기: 서비스 토큰 발급자에서 얻은 공개 키를 사용하여 서비스 토큰이 첨부된 GitLab 인스턴스 요청을 유효성 검사하는 백엔드 서비스. AI 게이트웨이가 한 예입니다.
  • OIDC: OpenID Connect, IDP(Identity Provider) 및 인증 및 권한 부여를 구현하는 오픈 표준입니다. 서비스 토큰 발급자는 서비스 토큰 검증기를 위해 OIDC 호환 디스커버리 엔드포인트를 제공합니다.
  • JWT: JSON Web Token, ID 데이터를 인코딩하고 전송하는 오픈 표준입니다.
  • JWKS: JSON Web Key Set, JWT의 서명을 유효성 검사하는 암호화 키를 인코딩하는 오픈 표준입니다.

문제 해결

대부분의 GitLab 기능은 어디에 배포되었든지 GitLab 인스턴스에서 직접 제공될 수 있습니다. 그러나 일부 기능은 3rd party 공급업체 통합이 필요하거나 GitLab.com 외부에서 운영하기 어려울 수 있습니다. 이로 인해 Self-Managed형 및 전용 고객은 해당 기능에 쉽게 액세스할 수 없는 문제가 발생합니다.

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

  • GitLab Rails에서 기능을 이동하여, 고객이 매뉴얼으로 구성하고 운영하는 번거로움을 덜어줍니다.
  • Cloud Connector 기능에 대한 단일 전역 진입점을 제공하여 cloud.gitlab.com에서 백엔드 서비스에 액세스합니다.
  • GitLab 인스턴스가 GitLab Inc.가 운영하는 백엔드 서비스에서 제공하는 기능을 사용할 수 있도록 인스턴스 라이선스 및 청구 데이터를 연결하여 액세스 권한을 부여합니다.

Cloud Connector 컴포넌트

기술적으로, Cloud Connector는 다음 컴포넌트로 구성됩니다:

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

다음 다이어그램은 이러한 컴포넌트들이 상호 작용하는 방식을 설명합니다:

액세스 제어

백엔드 서비스로의 요청을 처리할 때 두 가지 수준의 액세스 제어가 있습니다:

  1. 인스턴스 액세스. 특정 SM/Dedicated 인스턴스에 액세스 권한을 부여하려면 고객의 클라우드 라이선스 청구 상태에 바인딩된 서비스 토큰을 발급합니다. 이 토큰은 CustomersDot에서 GitLab 인스턴스로 매일 동기화되어 인스턴스의 로컬 데이터베이스에 저장됩니다. GitLab.com에서는 이 단계가 필요하지 않으며 대신 각 요청에 대해 유효 기간이 짧은 토큰을 발급합니다. 이러한 토큰은 JWT로 구현되어 발행자에 의해 암호화 서명됩니다.
  2. 사용자 액세스. 현재 모든 최종 사용자 요청은 각각의 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/Dedicated에서는 3일입니다.
  • scopes: 이 토큰이 유효한 기능을 정의하는 액세스 스코프 디렉터리. 이는 GitLab 티어 및 애드온에 지불 기반 기능이 결합되는 결정에 기반하여 얻습니다.

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

  • JWKS를 정기적으로 GitLab.com 및 CustomersDot에서 새로 고침하여 키 회전이 쉽게 정기적으로 발생하도록 하고 서비스 중단이 없이 작동되도록 합니다.
  • 각 요청에 대해 JWT의 서명 검증과 액세스 스코프 확인을 수행합니다.

다음의 흐름 차트는 GitLab.com 및 Dedicated/Self-Managed형 배포와 관련하여 AI 챗봇과 같은 Cloud Connector 기능을 소비할 때 사용자가 어떤 일이 발생하는지에 대해 이해하는 데 도움이 될 것입니다.

GitLab.com

GitLab.com 배포는 특별한 신뢰를 누리기 때문에 Cloud Connector 기능에 대한 모든 요청에 대해 자체 서명 및 서비스 토큰을 생성할 수 있는 장점이 있어서 흐름을 크게 간소화합니다.

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: Cloud Connector 기능 사용 GL->>GL: Cookie 또는 PAT로 authN/authZ 수행 GL->>GL: 기능 사용이 허용된지 사용자 확인 GL->>GL: 서명된 서비스 토큰 생성 GL->>SB: 서비스 토큰으로 기능 요청 SB->>GL: 필요한 경우 공개 서명 키 가져오기 GL-->>SB: JSON 웹 키 세트(JWKS) SB->>SB: 키로 서비스 토큰 유효성 검사 SB-->>GL: 기능 페이로드

GitLab Dedicated/Self-Managed

Dedicated 및 Self-Managed 인스턴스의 주요 문제는 신뢰 위임입니다: 우리는 개별 Self-Managed형 인스턴스를 신뢰할 수 없으며 그들에게 토큰을 발급할 수 없지만 CustomersDot을 통해 정기적으로 인스턴스가 자신을 승인하도록 위임할 수 있습니다. CustomersDot은 GitLab Inc.에서 제어하며 GitLab Dedicated 인스턴스를 제어하지만 단순함을 위해 Cloud Connector 측면에서 “Self-Managed”로 현재 간주합니다.

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: Cloud Connector 액세스 데이터 + 서비스 토큰 GL->>GL: DB에 액세스 데이터 + 서비스 토큰 저장 end Note over U,SB: 최종 사용자 흐름 U->>GL: GitLab 인스턴스로 인증 GL-->>U: PAT 또는 Cookie U->>GL: Cloud Connector 기능 사용 GL->>GL: Cookie 또는 PAT로 authN/authZ 수행 GL->>GL: 기능 사용이 허용된지 사용자 확인 GL->>GL: DB에서 서비스 토큰로드 GL->>SB: 서비스 토큰으로 기능 요청 SB->>CD: 필요한 경우 공개 서명 키 가져오기 CD-->>SB: JSON 웹 키 세트(JWKS) SB->>SB: 키로 서비스 토큰 유효성 검사 SB-->>GL: 기능 페이로드

Cloud Connector 액세스 데이터는 인스턴스의 로컬 데이터베이스에 저장된 구조화된 JSON 데이터입니다. 서비스 토큰 위에, 서비스가 완전히 출시되었는지 또는 베타 단계인지와 같은 서비스가 제공되는 추가 정보를 포함하여 우리가 제어하지 않는 Self-Managed형 인스턴스에 대한 업데이트 주기, 일부 GitLab 기능에 대한 원격 액세스를 제어할 수 있도록 해줍니다.

참조