클라우드 커넥터

GitLab 클라우드 커넥터는 여러 GitLab 배포, 인스턴스 및 셀에서 공통으로 액세스하는 방법입니다. 지금은 클라우드 커넥터가 별도의 서비스가 아니라 표준화된 인증 및 기타 항목에 접근하는 접근 방식을 표준화하는 API 및 코드의 모음입니다. GitLab 인스턴스와 클라우드 기반 서비스를 통합할 때 사용하는 방법을 설명하는 것이 이 페이지의 목표입니다.

클라우드 커넥터에 대한 자세한 내용은 아키텍처 페이지를 참조하세요. 또한 문서 전반에 사용된 용어 목록은 이곳에서 확인하세요.

튜토리얼: 클라우드 커넥터를 사용하여 기능 연결

GitLab Rails 인스턴스는 클라우드 커넥터 서비스 액세스 토큰을 사용하여 백엔드 서비스에 액세스합니다. 이는 GitLab Rails 애플리케이션에서 제공되는 토큰으로, 해당 토큰에는 액세스할 수 있는 백엔드 서비스 및 해당 서비스의 기능에 관한 정보가 포함되어 있습니다.

다음 섹션에서는 기존에 있는 백엔드 서비스 및 새로 만든 백엔드 서비스의 기능을 클라우드 커넥터를 통해 노출하는 데 필요한 단계를 다룹니다.

기존 서비스에 기능 연결

기존 백엔드 서비스의 기능을 클라우드 커넥터에 연결하려면 다음을 수행하세요:

  1. GitLab Rails의 단계를 완료합니다.
  2. CustomersDot의 단계를 완료합니다.
  3. 백엔드 서비스의 단계를 완료합니다.

GitLab Rails

  1. CloudConnector::AccessService.new.access_token(scopes: [...])를 호출하여 기능이 필요로 하는 스코프 목록을 포함하고 Authorization HTTP 헤더 필드에 이 토큰을 포함하여 호출합니다. 이 작업은 유효한 토큰이 없으면 nil을 반환할 수 있음에 유의하세요. 토큰이 없으면 Cloud 커넥터에 대한 호출에 인증이 통과되지 않으므로 일찍 반환하는 것이 좋습니다. 백엔드 서비스는 요청을 받을 때 이 토큰과 해당하는 스코프를 유효성 검사해야 합니다. 귀하의 사용 사례에 특정한 토큰에 추가 클레임을 포함해야 하는 경우, 이를 extra_claims 인수에 전달할 수 있습니다. 여기에 전달되는 스코프 및 다른 클레임은 GitLab.com에서 스스로 발급한 토큰에만 포함됩니다. 셀프 매니지드 인스턴스에서 사용자 지정 클레임이 어떻게 처리되는지 보려면 CustomersDot을 참조하세요.

  2. 귀하의 요청이 백엔드 서비스로 필요한 헤더를 보내는지 확인하세요.

    이 헤더는 다음과 같습니다:

    • X-Gitlab-Instance-Id: 전역적으로 고유한 인스턴스 ID 문자열.
    • X-Gitlab-Global-User-Id: 전역적으로 고유한 익명 사용자 ID 문자열.
    • X-Gitlab-Realm: saas, self-managed 중 하나.
    • Authorization: access_token 메서드에서 얻은 Bearer 토큰으로의 Base64로 인코딩된 JWT를 포함합니다.

    이러한 헤더 중 일부는 API::Helpers::CloudConnector#cloud_connector_headers 메서드의 결과를 페이로드에 병합함으로써 주입할 수 있습니다.

다음 예제는 new_feature_scope 스코프를 포함하는 요청에 대한 것입니다. 여기서 가정하는 바는 귀하의 백엔드 서비스가 foo라는 이름이며 이미 https://cloud.gitlab.com/foo에서 접근 가능하다는 것입니다. 또한 백엔드 서비스가 /new_feature_endpoint 엔드포인트를 통해 기능을 노출하도록 허용하고 있습니다. 이를 통해 클라이언트는 https://cloud.gitlab.com/foo/new_feature_endpoint에서 해당 기능에 액세스할 수 있습니다. 

include API::Helpers::CloudConnector

token = ::CloudConnector::AccessService.new.access_token(scopes: [:new_feature_scope])
return unauthorized! if token.nil?

Gitlab::HTTP.post(
  "https://cloud.gitlab.com/foo/new_feature_endpoint",
  headers: {
      'Authorization' => "Bearer #{token}",
    }.merge(cloud_connector_headers(current_user))
)

CustomersDot

Self-Managed 및 GitLab 전용 배포에 대한 귀하의 기능이 작동하려면 이 단계가 필요합니다.

CustomersDot은 어떤 인스턴스가 어떤 액세스 권한을 가지고 있는지의 권한을 부여합니다. 이 정보는 해당 인스턴스의 서비스 토큰에 저장됩니다.

범위에 바인딩된 새로운 기능을 추가하려면:

  1. cloud_connector.yml을 업데이트하여 services 아래에 새로운 서비스를 추가합니다. 우리는 서비스 토큰에 스코프로 포함될 기능 이름부터 시작합니다.

    service_start_time은 이 기능에 대해 지불이 필요한 기한 날짜입니다.

    min_gitlab_version은 이 기능을 받기 위해 필요한 최소한의 GitLab 버전이고, 이 기한 이전에 인스턴스가 액세스를 받아야 합니다.

    min_gitlab_version_for_beta는 이 기능을 받기 위해 필요한 최소한의 GitLab 버전이고, 이 기한 이전에 인스턴스가 액세스를 받아야 합니다.

    bundled_with는 해당 서비스에 액세스하기 위해 필요한 추가 번들입니다.

    예: 

     defaults: &defaults
   services:
     new_feature_scope:
       service_start_time: 2024-02-15 00:00:00 UTC
       min_gitlab_version: '16.8'
       bundled_with: 'duo_pro'

  2. 선택 사항: 토큰을 사용하는 백엔드 서비스가 추가 클레임을 포함해야 하는 경우, 현재 우리는 자체 서비스를 위한 인터페이스가 없기 때문에 내부에서만 사용 가능한 #g_cloud_connector(Slack, 내부 전용)에 문의하세요.

백엔드 서비스

GitLab Rails는 Self-managed 및 Dedicated 인스턴스에서 사용할 수없는 기능을 제공하기 위해 백엔드 서비스를 호출합니다. GitLab Rails가 이를 호출하려면 노출된 엔드포인트가 있어야 합니다. 백엔드 서비스는 GitLab Rails에서 Authorization 헤더의 JWT를 각각 확인해야 합니다.

이 섹션의 예제는 AI Gateway 및 FastAPI 프레임워크를 기반으로 합니다.

  1. 서비스에 엔드포인트를 생성하세요: 

    @router.post("/new_feature_endpoint")
async def feature_name(
    request: Request,
    payload: CompletionRequest
):
    return Response(
     id="id",
     created=int(time()),
     extra="Feature"
 )

  2. 엔드포인트가 호출자가 올바른 스코프 액세스를 가졌는지 확인하세요: 

    @router.post("/new_feature_endpoint")
@requires("new_feature_scope")
async def feature_name(
...

새 백엔드 서비스를 클라우드 커넥터에 연결

클라우드 커넥터 기능에서 이미 액세스 가능한 새 백엔드 서비스를 통합하려면:

  1. JWT 검증 설정.
  2. cloud.gitlab.com에서 이용 가능하게 만듭니다.

JWT 검증 설정

이미 Cloud Connector를 사용하는 서비스에 대한 백엔드 서비스 섹션에서 언급된 대로, 각 서비스는 GitLab 인스턴스에서 전송된 JWT가 정당한지 확인해야 합니다.

이를 위해 백엔드 서비스는 다음을 수행해야 합니다:

  1. JSON Web Key Set (JWKS) 유지.
  2. 이 세트의 키로 JWT 유효성 검사.

이러한 메커니즘에 대한 자세한 설명은 아키텍처: 액세스 제어를 참조하십시오.

JWKS 및 JWT 인증을 처리하기 위해 기존 소프트웨어 라이브러리를 사용하는 것이 좋습니다. 예시:

JWT 유효성 검사를 위한 JWKS 유지

JWT는 토큰 관리자에 의해 처음 발급될 때 암호화하여 서명됩니다. 그런 다음 GitLab 인스턴스는 해당 JWT를 백엔드 서비스에 보내는 요청에 첨부합니다.

JWT 서비스 액세스 토큰을 유효성 검사하려면 백엔드 서비스는 먼저 해당 토큰을 서명하는 개인 키에 상응하는 공개 유효성 검사 키를 포함하는 JWKS를 얻어야 합니다. GitLab.com 및 CustomersDot은 모두 토큰을 발행하므로, 백엔드 서비스는 두 곳에서 JWKS를 가져와야 합니다.

JWKS를 가져오려면 GitLab.com 및 CustomersDot에서 노출된 OIDC 디스커버리 엔드포인트를 사용하세요. 각각의 토큰 권한에 대해:

  1. GET /.well-known/openid-configuration

    예시 응답: 

    {
  "issuer": "https://customers.gitlab.com/",
  "jwks_uri": "https://customers.gitlab.com/oauth/discovery/keys",
  "id_token_signing_alg_values_supported": [
    "RS256"
  ]
}

  2. GET <jwks_uri>

    예시 응답: 

    {
  "keys": [
    {
      "kty": "RSA",
      "n": "sGy_cbsSmZ_Y4XV80eK_ICmz46XkyWVf6O667-mhDcN5FcSfPW7gqhyn7s052fWrZYmJJZ4PPyh6ZzZ_gZAaQM7Oe2VrpbFdCeJW0duR51MZj52FwShLfi-NOBz2GH9XuUsRBKnXt7wwKQTabH4WW7XL23Hi0eDjc9dyQmsr2-AbH05yVsrgvEYSsWiCGEgobPgNc51DwBoIcsJ-kFN591aO_qAkbpf1j7yAuAVG7TUxaditQhyZKkourPXXyx1R-u0Lx9UJyAV8ySqFxq3XDE_pg6ZuJ7M0zS0XnGI82g3Js5zAughrQyJMhKd8j5c8UfSGxhRBQh58QNl3UwoMjQ",
      "e": "AQAB",
      "kid": "ZoObkdsnUfqW_C_EfXp9DM6LUdzl0R-eXj6Hrb2lrNU",
      "use": "sig",
      "alg": "RS256"
    }
  ]
}

  3. 응답을 캐시하세요. 캐시는 일일로 만료되도록 권장합니다.

이 방법으로 얻은 키는 각 토큰 권한에 의해 발급된 JWT의 유효성을 검사하는 데 사용될 수 있습니다. 이 작업 방법은 사용하는 프로그래밍 언어 및 라이브러리에 따라 다르며 일반적인 지침은 JSON Web Key Sets 찾기에서 찾을 수 있습니다. 백엔드 서비스는 두 토큰 권한의 응답을 단일로 캐시된 결과 집합으로 병합할 수 있습니다.

JWKS를 사용하여 JWT 유효성 검사

JWT를 유효성 검사하려면:

  1. HTTP Authorization 헤더에서 토큰 문자열을 읽습니다.
  2. 이전에 얻은 JWKS 및 JWT 라이브러리 객체를 사용하여 유효성을 검사합니다.

토큰을 유효성 검사할 때 다음을 확인하세요:

  1. 토큰 서명이 올바른지 확인합니다.
  2. aud 클레임이 백엔드 서비스와 동일하거나 포함되어 있는지 확인합니다(이 필드는 문자열 또는 배열일 수 있습니다).
  3. iss 클레임이 유효성을 검사하는 데 사용된 키의 발급자 URL과 일치하는지 확인합니다.
  4. scopes 클레임이 요청된 엔드포인트에 의해 노출된 기능을 포함하는지 확인합니다(백엔드 서비스 참조).

새로운 클라우드 커넥터 경로 추가

모든 클라우드 커넥터 기능은 글로벌 로드 밸런서인 cloud.gitlab.com을 통해 액세스해야 합니다. 이 로드 밸런서는 경로 접두어에 기반하여 백엔드 서비스로의 요청을 라우팅합니다. 예를 들어, AI 기능은 cloud.gitlab.com/ai/<AI-specific-path>에서 요청해야 합니다. 그러면 로드 밸런서가 <AI-specific-path>를 AI 게이트웨이로 라우팅합니다.

새로운 백엔드 서비스를 클라우드 커넥터에 연결하려면, 새 경로 접두어를 요청하는 경로를 청구해야 합니다. 예를 들어, foo-service를 연결하려면, cloud.gitlab.com/foo를 foo-service로 라우팅하는 새 경로를 추가해야 합니다.

새로운 경로를 추가하려면 프로덕션 인프라 구성에 액세스해야 합니다. 새 경로가 필요한 경우, gitlab-org/gitlab 이슈 트래커에서 이슈를 열고 Cloud Connector 그룹에 할당하세요.

테스트

AI 게이트웨이를 백엔드 서비스로 하는 엔드 투 엔드 통합을 설정하는 예제는 여기에서 찾을 수 있습니다.