클라우드 커넥터
GitLab 클라우드 커넥터는 여러 GitLab 배포, 인스턴스 및 셀에서 공통 서비스에 액세스하는 방법입니다. 현재 클라우드 커넥터는 전용 서비스가 아니라, 오히려 클라우드 기반 서비스를 GitLab 인스턴스와 통합할 때 인증 및 기타 항목의 접근 방식을 표준화하는 API 및 코드 모음입니다. 이 페이지는 어떻게 클라우드 커넥터를 사용하여 GitLab Rails를 서비스에 연결하는지 설명합니다.
클라우드 커넥터에 대한 자세한 정보는 아키텍처 페이지를 참조하십시오. 문서 전반에 사용된 용어 목록은 용어를 참조하십시오. 또한 유료 기능이 GitLab 티어와 애드온에 번들로 구성되는 방법에 대한 정보는 구성을 참조하십시오.
자습서: 클라우드 커넥터를 사용하여 새 기능 연결
다음 섹션에서는 다음과 같은 사용 사례를 다룹니다:
- 클라우드 커넥터에 이미 연결된 기존 백엔드 서비스를 통해 새로운 기능을 소개하는 경우(#the-new-feature-is-introduced-through-the-existing-backend-service) (즉, AiGateway).
- 클라우드 커넥터에 연결해야 하는 새로운 백엔드 서비스를 통해 새 기능을 소개하는 경우(#the-new-feature-is-introduced-via-new-backend-service).
클라우드 커넥터를 통해 기존 백엔드 서비스를 통해 새 기능을 소개
Ai Gateway는 현재 클라우드 커넥터와 연결된 유일한 백엔드 서비스입니다. 기존 백엔드 서비스 (Ai Gateway)에 새로운 기능을 추가하려면:
선택 사항: 토큰을 사용하는 백엔드 서비스가 추가 클레임을 서비스 액세스 토큰에 임베딩해야하는 경우, 현재 자체 서비스 인터페이스가 없기 때문에 내부 사용자만 접근 가능한 #g_cloud_connector(Slack)에 연락하세요.
JWT 발급자에서 새 기능 등록
- GitLab Dedicated 및 자체 관리 GitLab 인스턴스의 경우, CustomersDot이 JWT 발급자입니다.
- GitLab.com 배포의 경우, GitLab.com이 JWT 발급자입니다. 왜냐하면 클라우드 커넥터 기능에 대한 모든 요청에 대해 자체 서명 및 JWT 생성을 수행하기 때문입니다.
자체 관리, 전담 및 GitLab.com 고객을 위한 새로운 기능 등록
GitLab Dedicated 및 자체 관리 GitLab 인스턴스의 경우 CustomersDot이 JWT 발급자이므로, 새로운 기능을 등록하려면 CustomersDot 구성을 업데이트해야 합니다.
GitLab.com이 JWT 발급자이므로 자체 서명 및 JWT 생성 가능하기 때문에 새로운 기능을 등록하려면 GitLab.com 구성을 업데이트해야 합니다.
따라서 총 2개의 별도의 머지 리퀘스트를 열어야 하며, 병합되는 시기의 동기화가 필요하지 않습니다.
새로운 기능은 다음과 같이 제공됩니다:
-
documentation_search와 같은 일부 기능은 기존 (Duo Chat) 서비스의 일부로 제공됩니다. - 기타 기능은 독립적인 서비스 (
code_suggestions)로 제공됩니다. - 기존 기능 (
explain_vulnerability)을 기존 (Duo Chat) 서비스의 일부로 이동하는 것도 가능합니다. - 또한 Duo Chat 서비스의 일부가 되고 동시에 독립적인 서비스로 작동할 수도 있습니다.
용어:
-
기능 - 새 유닛 원시(unit primitive)인
documentation_search로 등록되어 JWT에 포함됩니다. -
기존 서비스 -
Duo Chat- 기능이Duo Chat서비스의 일부로 제공됩니다. -
독립적인 서비스 -
code_suggestions- 기능이 별도의 서비스로 제공되며, 아마도 고유한 인터페이스를 통해 액세스할 수 있습니다. -
백엔드 서비스 -
Ai Gateway- 기능이 호스팅되는 백엔드입니다.
기존 서비스 (DuoChat)에 새 기능 등록
이 새로운 기능은 기존 서비스인 Duo Chat의 일부로 제공됩니다.
예를 들어, 새 기능은 다음과 같습니다:
- 이름:
new_feature - 기존
duo chat서비스의 일부로 제공되며, Duo Chat 창을 통해서만 사용 가능합니다. - 오직
duo_enterprise애드온을 통해서만 판매됩니다.
cloud_connector.yml(자체 관리 및 전담용) 및 access_data.yml(GitLab.com용)을 업데이트하여 duo chat 서비스에 new_feature_up 유닛 원시를 등록합니다.
defaults: &defaults
services:
duo_chat:
cut_off_date: 2024-7-15 00:00:00 UTC
min_gitlab_version: 16.8
min_gitlab_version_for_free_access: 16.8
bundled_with:
duo_pro:
unit_primitives:
- duo_chat
- documentation_search
duo_enterprise:
unit_primitives:
- duo_chat
- documentation_search
+ - new_feature_up
- 이 기능은 기존 서비스 (
Duo Chat)의 일부로 제공되므로duo_chat서비스에new_feature_up유닛 원시를 등록합니다. - 이 기능은 오직
duo_enterprise를 통해서만 판매되므로duo_enterprise애드온에만 bundled with에new_feature_up를 추가해야 합니다.
구성 구조에 대한 자세한 내용은 구성을 참조하십시오.
참고:
현재 기존 서비스 (Duo Chat)의 일부로 제공되는 유닛 원시의 경우 cut_off_date 또는 min_gitlab_version을 설정하는 것은 지원되지 않습니다.
이슈 465221는 현재 구성 구조 재구성 및 기존 서비스 (Duo Chat)의 일부로 제공되는 유닛 원시별로 cut_off_date 지원을 추가하는 것을 제안하고 있습니다.
새로운 독립 서비스 등록
새로운 기능을 독립 서비스로 제공합니다.
예를 들어, 새로운 기능은 다음과 같습니다.
-
new_feature라고 명명됨 -
Duo Chat서비스의 일부가 아닌 독립 서비스로 제공됨 -
duo_pro및duo_enterprise애드온을 통해 판매됨 - 무료로 이용할 수 없어야 함
- 최소 필수 GitLab 버전은 17.1임
cloud_connector.yml (자체 관리 및 전담용) 및 access_data.yml(GitLab.com용)을 업데이트하여 new_feature를 service로 등록하십시오. 구성을 참조하십시오.
defaults: &defaults
services:
+ new_feature:
+ cut_off_date: 2024-1-1 00:00:00 UTC
+ min_gitlab_version: 17.1
+ bundled_with:
+ duo_pro:
+ unit_primitives:
+ - new_feature_up
+ duo_enterprise:
+ unit_primitives:
+ - new_feature_up
- 이 기능은 새로운 독립 서비스로 액세스 가능해야 하므로
new_feature서비스를 등록해야 합니다. - 이 기능은 무료로 이용할 수 없어야 하므로
cut_off_date를 과거 날짜로 설정해야 합니다. - 이 기능은
duo_pro및duo_enterprise양측을 통해 판매되므로 양측 모두에 대해 bundled with에new_feature_up를 추가해야 합니다.
추가 구성 구조에 대한 자세한 내용은 구성을 참조하십시오.
기존 서비스와 독립 기능의 조합으로 기능 등록
새로운 기능을 기존 서비스(Duo Chat) 및 자체 사용자 인터페이스를 통해 액세스할 수 있습니다.
예를 들어, 새로운 기능은 다음과 같습니다.
-
new_feature라고 명명됨 - 기존
duo chat서비스의 일부로 제공되며, Duo Chat 창을 통해서만 액세스 가능함 - 독립 서비스로도 제공됨. 즉, 자체 인터페이스를 통해서도 Duo Chat 외부에서 사용됨
-
duo_enterprise애드온만을 통해 판매됨
cloud_connector.yml (자체 관리 및 전담용) 및 access_data.yml(GitLab.com용)을 업데이트하십시오:
defaults: &defaults
services:
+ new_feature:
+ bundled_with:
+ duo_enterprise:
+ unit_primitives:
+ - new_feature
duo_chat:
bundled_with:
duo_pro:
unit_primitives:
- duo_chat
- documentation_search
duo_enterprise:
unit_primitives:
- duo_chat
- documentation_search
+ - new_feature_up
- 이 기능은 기존 서비스 (Duo Chat)의 일부로 제공되므로
duo_chat서비스에서 새로운new_feature_up유닛 원시를 등록하고 있습니다. - 이 기능은 독립 서비스로도 제공되므로
new_feature를 새service로 등록해야 합니다. - 이 기능은
duo_enterprise애드온만을 통해 판매되므로 두 서비스에 대해 bundled with 아래에new_feature_up을 추가해야 합니다.
추가 구성 구조에 대한 자세한 내용은 구성을 참조하십시오.
GitLab Rails에서 권한 검사 구현
새로운 기능은 독립 서비스로 제공됨
액세스 토큰
예를 들어, 기능은 new_feature라는 독립 서비스로 제공됩니다.
-
CloudConnector::AvailableServices.find_by_name(:new_feature).access_token(user_or_namespace)를 호출하고 이 토큰을AuthorizationHTTP 헤더 필드에 포함하십시오.- GitLab.com에서는 제공된 리소스에 따라 범위가 설정된 토큰이 자동으로 생성됩니다.
- 사용자의 경우: 범위는 사용자의 좌석 할당에 기반함
- 네임스페이스의 경우: 이 네임스페이스의 구매한 애드온에 기반함
- 무료로 액세스할 수 있는 서비스의 경우, 토큰에는 해당 서비스의 모든 가능한 범위가 포함됨
- Duo Chat의 경우 JWT에
documentation_search및duo_chat범위가 포함됨
- 자체 관리에서는 항상
::CloudConnector::ServiceAccessTokenJWT 토큰이 반환됨.- 사용자, 네임스페이스 또는 추가 클레임과 같은 제공된 매개변수는 자체 관리 인스턴스에 대해 무시됨
- 자체 관리 인스턴스에서 사용자 정의 클레임이 어떻게 처리되는지 자세한 내용은 이 섹션을 참조하십시오.
백엔드 서비스 (즉, Ai Gateway)는 요청을 받을 때 이 토큰과 토큰이 가지고 있는 모든 범위를 유효성 검사해야 합니다.
- GitLab.com에서는 제공된 리소스에 따라 범위가 설정된 토큰이 자동으로 생성됩니다.
-
특정 사용 사례에 맞게 토큰에 추가적인 클레임을 임베드해야 하는 경우
extra_claims인자에 이를 전달할 수 있습니다. -
요청이 백엔드 서비스로 전송하는 필수 헤더를 보내십시오.
어떤 백엔드 서비스에 대해 항상 전송해야 하는 주요 헤더 필드들:
-
X-Gitlab-Instance-Id: 전역적으로 고유한 인스턴스 ID 문자열 -
X-Gitlab-Global-User-Id: 전역적으로 고유한 익명 사용자 ID 문자열 -
X-Gitlab-Realm:saas,self-managed중 하나 -
X-Gitlab-Version: GitLab 인스턴스 버전 -
X-Gitlab-Host-Name: 현재 GitLab 인스턴스의 호스트 이름 -
Authorization:access_token메서드로 얻은Bearer토큰으로 인코딩된 JWT가 포함됨.
AI에 특화된 헤더 필드:
-
X-Gitlab-Duo-Seat-Count: 고객이 구매한 duo pro 또는 duo enterprise 좌석 수. 두 애드온이 모두 있는 경우, 더 높은 좌석 수를 취함
이러한 헤더 중 일부는 페이로드에
Gitlab::CloudConnector#headers메서드의 결과를 병합함으로써 주입할 수 있습니다. AI 사용 사례 및 AI 게이트웨이를 대상으로 하는 요청의 경우,Gitlab::CloudConnector#ai_headers를 사용하십시오. -
권한 확인
서비스가 최종 사용자에게 표시되거나 사용 가능한지 여부를 결정하려면 다음이 필요합니다.
-
선택 사항. Self-Managed GitLab의 경우, 새로운 기능이 기업용 기능으로 소개되면 EE 기능 지침을 따라 기능에 액세스할 수 있는지 확인합니다.
next true if ::Gitlab::Saas.feature_available?(:new_feature_on_saas) ::License.feature_available?(:new_feature) - Self-Managed GitLab에서는 고객이 온라인 클라우드 라이선스를 사용하는지 확인합니다
- 클라우드 커넥터는 현재 Self-Managed 고객을 위해 온라인 클라우드 라이선스만 지원합니다.
- 평가 또는 레거시 라이선스는 지원되지 않습니다.
- GitLab.com은 레거시 라이선스를 사용 중입니다.
::License.current&.online_cloud_license? - GitLab.com 및 Self-Managed GitLab에서 서비스에 무료 액세스가 있는지 확인합니다.
- 커트오프 날짜가 설정되지 않았거나 미래에 설정되었을 경우, 기능은 무료로 간주됩니다.
# 서비스에 무료 액세스가 가능한지 반환합니다 (추가 구매가 필요하지 않음) CloudConnector::AvailableServices.find_by_name(:new_feature).free_access? - 선택 사항. 서비스에 무료 액세스가 있는 경우, 실험적 기능은 일반적으로 테스트 계약에 따라 제공됩니다.
- GitLab Duo 기능의 경우, 고객은 실험적 기능을 사용하려면 실험적 토글을 활성화해야 합니다.
-
GitLab.com과 Self-Managed GitLab에서 서비스가 무료로 액세스할 수 없는 경우, 해당 서비스와 번들로 제공된 애드온이 고객에의해 구매되었는지 확인합니다 (그룹/네임스페이스 기준)
# 서비스와 번들로 제공된 애드온 중 하나 이상이 구매되었다면 true를 반환합니다. # # - 제공된 네임스페이스의 경우, 제공된 그룹/프로젝트 또는 해당 부모를 기준으로 애드온이 구매되었는지 확인합니다. # - Self-Managed의 경우 네임스페이스는 고려되지 않습니다. Self-Managed 고객을 대상으로 애드온은 네임스페이스별로 구매되지 않습니다. CloudConnector::AvailableServices.find_by_name(:new_feature).purchased?(namespace) -
GitLab.com과 Self-Managed GitLab에서 고객의 최종 사용자가 적절한 시트에 할당되었는지 확인합니다.
# 서비스 사용이 허용되었는지 여부를 반환합니다. # # 제공된 사용자의 경우, 해당 사용자가 적절한 시트에 할당되었는지 확인합니다. current_user.allowed_to_use?(:new_feature)
예
다음 예제는 :new_feature라는 서비스에 대한 요청입니다.
여기서 우리는 백엔드 서비스를 foo라고 가정하고 이미 https://cloud.gitlab.com/foo에서 사용 가능한 상태라고 가정합니다.
또한, 백엔드 서비스가 /new_feature_endpoint 엔드포인트를 통해 서비스를 노출하는 것으로 가정합니다.
이를 통해 클라이언트는 https://cloud.gitlab.com/foo/new_feature_endpoint에서 서비스에 액세스할 수 있습니다.
ee/global_policy.rb에 새로운 정책 규칙을 추가하세요.
condition(:new_feature_licensed) do
next true if ::Gitlab::Saas.feature_available?(:new_feature_on_saas)
next false unless ::License.current.online_cloud_license?
::License.feature_available?(:new_feature)
end
condition(:user_allowed_to_use_new_feature) do
@user.allowed_to_use?(:new_feature)
end
rule { new_feature_licensed & user_allowed_to_use_new_feature }.enable :access_new_feature
요청
include API::Helpers::CloudConnector
# 사용자의 시트 할당, 애드온 구매 여부를 기반으로 사용자가 서비스에 액세스할 수 있는지 확인합니다
return unauthorized! unless current_user.can?(:access_new_feature)
# Gitlab.com의 경우, 제공된 리소스를 기반으로 스코프가 있는 토큰을 자체 발급합니다.
# - 제공된 사용자의 경우, 사용자 할당 권한에 기반한 스코프가 있는 토큰을 자체 발급합니다.
# - 제공된 네임스페이스의 경우, 애드온 구매 권한에 기반한 스코프가 있는 토큰을 자체 발급합니다.
# - 서비스에 free_access? 설정이 되어 있는 경우, 모든 사용 가능한 스코프가 있는 토큰을 자체 발급합니다
#
# Self-Managed의 경우, 추가 클레임과 제공된 사용자, 네임스페이스를 무시하고 :CloudConnector::ServiceAccessToken 인스턴스 토큰을 반환합니다
token = ::CloudConnector::AvailableServices.find_by_name(:new_feature).access_token(current_user)
Gitlab::HTTP.post(
"https://cloud.gitlab.com/foo/new_feature_endpoint",
headers: {
'Authorization' => "Bearer #{token}",
}.merge(cloud_connector_headers(current_user))
)
소개된 정책은 프론트엔드가 표시되는지를 제어하는 데 사용할 수 있습니다. new_feature_helper.rb에 새로운 기능 추가:
def show_new_feature?
current_user.can?(:access_new_feature)
end
기존 서비스(듀오 채팅) 일부로서의 새로운 기능 제공
액세스 토큰
기존 서비스(듀오 채팅)의 일부로서 새로운 기능을 제공하는 경우, CloudConnector::AvailableServices.find_by_name(:duo_chat).access_token(user_or_namespace)를 호출하면
모든 인가된 기능(유닛 primitive)을 포함한 IJWT가 반환됩니다.
백엔드 서비스(AI 게이트웨이)는 토큰 범위가 JWT에 포함되지 않은 경우 특정 기능(유닛 primitive)에 대한 액세스를 방지합니다.
권한 확인
기존 서비스의 일부로서 새로운 기능을 제공하는 경우 추가적인 권한 확인이 필요하지 않습니다.
기존의 전역 정책 규칙인 user.can?(:access_duo_chat)을 의존할 수 있습니다.
사용자가 최소한 하나의 기능(유닛 primitive)에 액세스 권한이 있는 경우, 최종 사용자가 서비스에 액세스할 수 있습니다.
개별 기능(유닛 primitive)에 대한 액세스는 IJWT 스코프에 의해 제어되며 이는 백엔드 서비스(AI 게이트웨이)에 의해 유효성이 검증될 것입니다.
액세스 토큰을 확인하세요.
백엔드 서비스에서 권한 확인 구현
GitLab Rails는 Self-Managed 및 전용 인스턴스에서 사용할 수 없는 기능을 제공하기 위해 백엔드 서비스를 호출합니다. GitLab Rails가 호출할 수 있도록 백엔드 서비스에 노출된 엔드포인트가 있어야 합니다. 백엔드 서비스는 GitLab Rails에 의해 Authorization 헤더에서 보낸 각 JWT를 확인해야 합니다.
AI Gateway 인증 프로세스에 대한 자세한 정보 및 예제는 AI Gateway 문서를 확인하세요.
새로운 기능은 새로운 백엔드 서비스를 통해 소개됩니다.
새로운 클라우드 커넥터 기능으로 접근할 수 없는 새로운 백엔드 서비스를 통합하려면 다음을 수행하세요:
- JWT 유효성 검사 설정.
-
cloud.gitlab.com에서 사용 가능하게 만듭니다.
JWT 유효성 검사 설정
이미 클라우드 커넥터를 사용하는 서비스에 대한 권한 확인을 구현한 내용(백엔드 서비스의 권한 확인 구현)에 언급된 것처럼 각 서비스는 GitLab 인스턴스에서 전송된 JWT가 정당한지 확인해야 합니다.
이를 수행하기 위해 백엔드 서비스는 다음을 수행해야 합니다:
이에 대한 자세한 설명은 아키텍처: 액세스 제어를 참조하세요.
우리는 JWKS 및 JWT 인증을 처리하기 위해 기존 소프트웨어 라이브러리를 사용할 것을 강력히 권장합니다. 예시로는 다음이 있습니다:
토큰 유효성 검사를 위한 JWKS 유지
JWT는 토큰 부여자에 의해 암호적으로 서명됩니다. 그런 다음 GitLab 인스턴스는 백엔드 서비스에 대해 요청된 JWT를 첨부합니다.
JWT 서비스 액세스 토큰을 유효성 검사하려면 백엔드 서비스는 먼저 토큰을 서명한 개인 키에 해당하는 공개 유효성 확인 키를 포함하는 JWKS를 얻어야 합니다. GitLab.com 및 CustomersDot에서 모두 토큰을 발급하므로 백엔드 서비스는 두 곳에서 JWKS를 가져와야 합니다.
JWKS를 가져오려면 GitLab.com 및 CustomersDot에서 노출된 OIDC 디스커버리 엔드포인트를 사용하세요. 이러한 토큰 권한 각각에 대해 다음을 수행하세요:
-
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" ] } -
<jwks_uri>를GET합니다.예시 응답:
{ "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" } ] } -
응답을 캐시합니다. 캐시 만료는 하루에 한 번 이루어지도록 권장합니다.
이 방법으로 얻은 키는 각 토큰 권한에서 발급된 JWT의 유효성을 검사하는 데 사용될 수 있습니다. 이 동작 방식은 사용하는 프로그래밍 언어 및 라이브러리에 따라 다르며, 일반적인 지침은 JSON Web Key Sets 찾기에서 찾을 수 있습니다. 백엔드 서비스는 두 토큰 권한의 응답을 단일 캐시된 결과 집합으로 병합할 수 있습니다.
JWKS로 JWT 유효성 검사
JWT를 유효성 검사하려면:
- HTTP
Authorization헤더에서 토큰 스트링을 읽습니다. - JWT 라이브러리 오브젝트 및 이전에 얻은 JWKS를 사용하여 유효성을 검사합니다.
토큰을 검증할 때 다음을 확인하세요:
- 토큰 서명이 올바른지 확인합니다.
-
aud클레임이 백엔드 서비스와 일치하거나 해당 합니다(이 필드는 문자열 또는 배열일 수 있습니다). -
iss클레임이 유효성을 검사하는 데 사용된 키의 발행자 URL과 일치합니다. -
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 issue 트래커에서 이슈를 열고 클라우드 커넥터 그룹에 할당하세요.
테스트
AI 게이트웨이를 백엔드 서비스로 하는 엔드 투 엔드 통합 설정 예시는 여기에서 찾을 수 있습니다.
도움말