• 요약
• 제안
  • 현재와 새로운 러너 등록 흐름 비교
  • 등록 토큰 대신 인증 토큰 사용
  • 전환 기간
  • 여러 대의 머신에서 러너 인증 토큰 재사용
    • system_id 값 생성
  • CI 작업에서의 러너 식별
• 이점
• 세부 정보
  • 레거시 러너 처리
  • ci_runner_machines 레코드 유지 기간
  • 필요한 조정
    • ci_runner_machines 테이블로의 마이그레이션
    • REST API
    • GraphQL CiRunner 타입
    • 미사용 러너 정리
  • API를 통한 러너 생성
• 구현 계획
  • 단계 1 - 폐기
  • 단계 2 - system_id를 위한 gitlab-runner 준비
  • 단계 2a - GitLab Runner Helm Chart 및 GitLab Runner Operator 준비
  • 단계 3 - 데이터베이스 변경
  • 스테이지 4 - UI에서 러너 생성
  • 스테이지 5 - 등록 토큰의 선택적 비활성화
  • 스테이지 6 - 집행
  • 스테이지 7 - 제거 사항
• FAQ
• 상태
• 담당자

다음 GitLab Runner 토큰 아키텍처

요약

GitLab Runner는 신뢰할 수 있고 병행적인 환경에서 CI/CD 작업을 실행하는 GitLab CI/CD의 핵심 컴포넌트입니다. 서비스의 시작부터 루비 프로그램으로 시작되었으며, 러너는 GitLab 인스턴스에 등록될 때 등록 토큰 - 무작위로 생성된 텍스트 문자열을 사용합니다. 등록 토큰은 해당 범위(instance, 그룹 또는 프로젝트)에 대해 고유합니다. 등록 토큰은 러너를 등록한 당사자가 관리 액세스를 가지고 있는지를 증명합니다.

이 접근 방식은 초기 몇 년간 잘 작동했지만, 대상 시청자가 늘어남에 따라 몇 가지 주요 문제가 드러나기 시작했습니다:

이러한 문제에 비추어, 러너를 GitLab의 인스턴스에 연결하는 방법을 다시 설계하여 추적 가능성, 보안 및 성능을 보장할 수 있도록 하는 것이 중요합니다.

이 새로운 메커니즘을 “다음 GitLab Runner 토큰 아키텍처”라고 부릅니다.

제안

제안은 범위 당 단일 토큰 및 토큰 저장 문제를 제거함으로써 등록 토큰의 필요성을 없애는 것에 주안점을 두고 있습니다. 러너 생성은 인증된 사용자의 컨텍스트 내에서 해당 범위의 GitLab 러너 설정 페이지에서 이루어지며, 추적 가능성을 제공합니다. 페이지에서는 지원되는 환경에서 새로 생성된 러너를 구성하는 지침을 제공합니다. 기존의 gitlab-runner register 명령을 사용하여 새로 생성된 러너를 설정합니다.

나머지 관심사항은 등록 토큰이 없어짐으로써 더 이상 문제가 되지 않습니다.

현재와 새로운 러너 등록 흐름 비교

등록 토큰 대신 인증 토큰 사용

이 제안에서는 GitLab UI에서 생성된 러너에는 glrt- (GitLab Runner Token의 약자)로 접두어가 붙은 인증 토큰이 할당됩니다. 접두어를 통해 기존 register 명령이 현재의 등록 토큰(--registration-token) 대신 인증 토큰을 사용할 수 있도록하여 기존의 워크플로우에서 최소한의 조정을 요구합니다. 인증 토큰은 사용자에게 한 번만 표시되며 - 생성 흐름을 완료한 후에 표시되며 - 의도하지 않은 재사용을 방지하기 위한 것입니다.

GitLab UI를 통해 러너가 미리 생성되기 때문에, register 명령은 러너 생성 양식에서 노출된 인수를 제공하면 명령이 실패합니다. 일부 예는 --tag-list, --run-untagged, --locked, 또는 --access-level과 같은 민감한 매개변수입니다. 이러한 매개변수는 관리자/소유자가 만들어진 시간에 결정해야 하는 민감한 매개변수이므로 러너 구성은 기존의 register 명령을 통해 생성되며, 이는 --registration-token 인수에 등록 토큰 대신 인증 토큰이 제공되는지에 따라 두 가지 다른 방식으로 행동할 수 있습니다:

전환 기간

전환 기간 동안 기존 토큰인 (“등록 토큰”)의 유산 토큰은 여전히 GitLab 러너 설정 페이지에 표시되고 gitlab-runner register 명령에서도 유효합니다. 그러나 UI에서는 유산 워크플로우를 지양하고 있습니다. 사용자들은 러너를 UI에서 만들고 결과로 나오는 인증 토큰을 오늘처럼 gitlab-runner register 명령과 함께 사용하도록 유도됩니다. 이 접근 방식은 러너를 배포하는 사용자들에게 혼란을 줄이도록 돕습니다.

여러 대의 머신에서 러너 인증 토큰 재사용

기존 자동 확장 모델에서는 새 작업이 실행되어야 할 때마다 새로운 러너가 생성됩니다. 이로 인해 러너가 남겨지고 구식화되는 경우가 많이 발생했습니다.

제안된 모델에서는 ci_runners 테이블 항목 한 개가 여러 대의 머신에서 재사용할 수 있는 구성을 설명하며 각 머신에서의 러너 상태(예: IP 주소, 플랫폼, 아키텍처)은 별도의 테이블인 (ci_runner_machines)로 이동합니다. 러너 애플리케이션이 시작되거나 구성이 저장될 때마다 고유한 시스템 식별자가 자동으로 생성됩니다. 이를 통해 러너가 사용되는 머신을 구분할 수 있습니다.

system_id 값은 명령줄 출력, CI 작업 로그 및 GitLab UI에서 러너를 식별하는 데 사용되는 짧은 러너 토큰을 보완합니다.

러너 생성에 사용자 상호작용이 포함되므로 스코프당 등록할 수 있는 CI 러너의 제한을 최종적으로 낮출 수 있어야 합니다.

system_id 값 생성

우리는 항상 gitlab-runner 설치에 고유한 시스템 식별자를 할당합니다. 이 ID는 기존의 머신 식별자(예: 리눅스의 /etc/machine-id)에서 파생되어 개인정보 보호를 위해 해싱된 것이며, 그렇지 않은 경우 r_로 접두사가 붙은 임의의 문자열이 대신 사용됩니다.

이 고유한 ID는 gitlab-runner 프로세스를 식별하고 config.toml 파일 내려 POST /api/v4/jobs 요청에 보내집니다.

이 ID는 gitlab-runner 시작 시와 구성이 디스크에 저장될 때 모두 생성되고 저장됩니다. 단, 우리는 config.toml의 루트가 아닌 새로운 파일인 .runner_system_id 파일에 저장하여 config.toml 파일을 매뉴얼으로 복사하는 것으로 ID가 재사용될 가능성이 줄어들도록 합니다.

s_cpwhDr7zFz4xBJujFeEM

CI 작업에서의 러너 식별

사용자들이 작업이 실행된 머신을 식별할 수 있도록 고유 식별자는 CI 작업 컨텍스트에서 볼 수 있어야 합니다. 최초 반복에서 GitLab 러너는 빌드 로그에 고유 시스템 식별자를 포함시키며, 러너가 재사용될 수 있기 때문에 이 식별자를 데이터베이스에 저장해야 합니다. 이는 고유 시스템 ID가 러너 토큰과 매핑되도록 함으로써 러너를 데이터베이스에서 식별할 수 있도록 하여 마지막으로 연결된 러너를 파악하고 어떤 유형인지에 대한 정보를 보관합니다.

장기적으로, 관련 필드는 ci_runners에서 ci_runner_machines로 이동해야 합니다. 그러나 제거 마일스톤이 올 때까지 ci_runners에 유지하여 일치하는 ci_runner_machines 레코드가 없는 경우 대비하는 용도로 사용합니다. 예상 시나리오로는 러너가 GitLab 인스턴스에 핑을 보내지 않은 경우(러너가 오프라인인 경우)가 있습니다.

또한, 다음과 같은 열을 ci_runners에 추가해야 합니다:

• 러너를 생성한 사용자를 추적하기 위한 creator_id 열;
• 러너가 기존 register 방법을 사용하여 생성되었는지, 아니면 새로운 UI 기반 방법을 사용하여 생성되었는지를 나타내는 registration_type 열입니다. 가능한 값은 :registration_token 및 :authenticated_user입니다. 이는 구식화된 러너 청소 서비스가 어떤 러너를 청소할지 결정하고 앞으로 알 수 없는 미래의 사용 사례를 허용합니다.

CREATE TABLE ci_runners (
  ...
  creator_id bigint
  registration_type int8
)

새로운 p_ci_runner_machine_builds 테이블은 ci_runner_machines와 ci_builds 테이블을 연결하여 이들 테이블에 더 많은 압력을 가하지 않도록 합니다. 기존 레코드를 업데이트하는 대신 contacted_at를 저장하는 더 효율적인 방법을 고려해볼 수 있습니다.

CREATE TABLE p_ci_runner_machine_builds (
    partition_id bigint DEFAULT 100 NOT NULL,
    build_id bigint NOT NULL,
    runner_machine_id bigint NOT NULL
)
PARTITION BY LIST (partition_id);

CREATE TABLE ci_runner_machines (
    id bigint NOT NULL,
    system_xid character varying UNIQUE NOT NULL,
    contacted_at timestamp without time zone,
    version character varying,
    revision character varying,
    platform character varying,
    architecture character varying,
    ip_address character varying,
    executor_type smallint,
    config jsonb DEFAULT '{}'::jsonb NOT NULL
);

이점

• 두 가지 유형의 토큰이 아닌 러너당 인증 토큰이 하나뿐이므로 사용자들에게 개념을 이해하기 쉬워집니다. 이러한 경우 아이템을 토론할 때 자주 오해를 일으키기도 합니다.
• 러너는 항상 생성한 사용자로 거슬러 올라갈 수 있으며, 감사 로그를 통해 그 정보를 확인할 수 있습니다.
• CI 러너의 클레임은 생성 시에 알려져 있고 러너로부터 변경될 수 없습니다(예: access_level/protected 플래그를 변경하는 경우). 그러나 인증된 사용자는 여전히 GitLab UI를 통해 이러한 설정을 편집할 수 있습니다.
• ci_runner 테이블을 건드리지 않고 구식화된 러너를 쉽게 정리할 수 있습니다.

세부 정보

제안된 접근 방식에서는 전환 기간 동안 기존의 등록 토큰 방법과 함께 사용 가능한 러너를 설정하는 구별된 방법을 만듭니다. 아이디어는 러너가 새로운 러너를 등록할 수 있는 “공감스러운 가능성(god-like)” 토큰을 활용하는 API 호출을 피하는 것입니다.

새로운 작업 흐름은 다음과 같습니다:

1. 사용자가 러너 설정 페이지(인스턴스, 그룹 또는 프로젝트 레벨)를 엽니다.
2. 사용자가 새로운 원하는 러너에 대한 설명, 태그, 보호, 잠금 등과 같은 세부 정보를 기입합니다.

3. 사용자가 생성을 클릭합니다. 결과는 다음과 같습니다:

   1. ci_runners 테이블(및 해당 glrt- 접두어 인증 토큰)에 새 러너가 생성됩니다;
   2. 머신에 이 새로운 러너를 구성하는 방법에 대한 지침이 제공됩니다. 이는 사용자에게만 일회용으로 제공되며, UI에서 중복 등록하는 것은 피하지만 불가능한 것은 아닙니다.

4. 사용자는 의도한 배포 시나리오(register 명령어)를 위한 지침을 복사하여 붙입니다. 이로 인해 다음 작업이 진행됩니다:

   1. 지침에 따라 새 gitlab-runner register 명령을 실행하면 gitlab-runner이 주어진 러너 토큰으로 POST /api/v4/runners/verify를 호출합니다.
   2. POST /api/v4/runners/verify GitLab 엔드포인트가 토큰을 검증하면 config.toml 파일이 구성되어 정보가 저장됩니다.
   3. 러너가 작업을 위해 핑을 보낼 때마다 해당 ci_runner_machines 레코드가 최신 정보로 “업서트”됩니다.

전환 기간 동안 설정을 위한 인스턴스/상위 레벨 그룹 소유자에게 allow_runner_registration_token 설정이 제공되어 기존의 회원 등록 토큰 기능을 비활성화하고 새 작업 흐름만을 사용하도록 강제할 수 있습니다. gitlab-runner register 명령을 사용하여 새 등록 토큰이 있는 러너를 등록하려고 하면 HTTP 410 Gone 상태 코드가 반환됩니다.

인스턴스 설정은 하위 그룹에 상속됩니다. 즉, 인스턴스 방법에서 기존 회원 등록 방법이 비활성화되면 하위 그룹/프로젝트에서 기존 회원 등록 방법을 의무적으로 방지합니다.

등록 토큰 작업 흐름은 구식화될 예정이며(gitlab-runner register 명령인 경우 구식화 공지가 출력됨) 고객들이 새 작업 흐름으로 이동하고 안정화된 것이 증명된 후에 향후 주요 릴리스에서 제거될 것입니다.

레거시 러너 처리

GitLab Runner의 레거시 버전은 요청에서 고유한 시스템 식별자를 보내지 않기 때문에 Workhorse의 로직을 변경하지 않겠으며, 이는 레거시 등록 시스템이 제거되고 러너가 새 버전으로 업그레이드된 후에 개선될 수 있습니다.

이러한 레거시 러너로부터의 작업 핑은 <legacy> system_xid 필드 값을 포함하는 ci_runner_machines 레코드를 만듭니다.

고유한 시스템 식별자를 사용하지 않는 것은 동일한 토큰을 가진 모든 연결된 러너에게 통지됨을 의미하므로 정확한 시스템 식별자와 일치하는 러너 대신 모든 러너에게 통지됩니다. 이는 이상적이지는 않지만 본질적으로 문제는 아닙니다.

ci_runner_machines 레코드 유지 기간

새 레코드는 2 가지 상황에서 생성됩니다.

• 러너가 gitlab-runner register 명령의 일부로 POST /api/v4/runners/verify 엔드포인트를 호출하는 경우, 지정된 러너 토큰이 glrt-로 접두어가 있는 경우. 이를 통해 프론트엔드에서 사용자가 등록을 성공적으로 완료했는지를 결정하고 적절한 조치를 취할 수 있습니다.
• GitLab이 새 작업을 위해 핑(ping)을 받고 token+system_id와 일치하는 레코드가 이미 존재하지 않는 경우.

시간이 흐름에 따라 감소하는 성격 때문에 ci_runner_machines 레코드는 해당 러너로부터의 마지막 연락 후 7일 후에 자동으로 정리됩니다.

필요한 조정

ci_runner_machines 테이블로의 마이그레이션

ci_runner_machines에서의 세부 정보가 필요할 때, ci_runner_machines에서 일치하는 항목이 없는 경우 ci_runner의 기존 필드로 회귀해야 합니다.

REST API

러너 토큰을 받는 API 엔드포인트는 새로운 glrt- 토큰과 함께 서버로 보내는 system_id 매개변수를 선택적으로 받도록 변경되어야 합니다(대부분의 경우 요청 본문의 JSON 매개변수로 가장 많이 보내집니다).

GraphQL CiRunner 타입

CiRunner 타입은 ci_runners 모델을 밀접하게 반영합니다. 이는 ipAddress, architectureName, executorName 등의 기계 정보가 제안된 방법에서 더 이상 단일 값이 아니라는 것을 의미합니다. 우리는 당분간 그 사실을 받아 들일 수 있으며 쉼표로 구분된 고유한 값 디렉터리을 반환하여 시작할 수 있습니다. 해당 CiRunner 필드는 ci_runner_machines 항목에 대한 값을 반환해야 합니다(ci_runner_machines 레코드가 없는 경우 ci_runner 레코드로 회귀).

미사용 러너 정리

미사용 러너를 정리하는 기능은 ci_runners 레코드 대신에 ci_runner_machines 레코드를 정리하도록 수정되어야 합니다.

등록 토큰 지원이 제거된 후 어느 시점에서, 우리는 ci_runners 테이블에 생성된 지연된 러너들을 정리하기 위한 백그라운드 마이그레이션을 만들고 싶어할 것입니다(테이블에 생성된 열거형 열을 활용).

API를 통한 러너 생성

새로운 GraphQL 뮤테이션과 기존의 POST /user/runners REST API 엔드포인트를 통해 자동 러너 생성이 가능합니다. 이러한 엔드포인트는 지정된 범위에서 러너를 생성할 수 있는 권한을 가진 사용자에게만 사용 가능합니다.

구현 계획

단계 1 - 폐기

단계 2 - system_id를 위한 gitlab-runner 준비

단계 2a - GitLab Runner Helm Chart 및 GitLab Runner Operator 준비

단계 3 - 데이터베이스 변경

스테이지 4 - UI에서 러너 생성

스테이지 5 - 등록 토큰의 선택적 비활성화

스테이지 6 - 집행

스테이지 7 - 제거 사항

FAQ

사용자 문서를 참고하세요.

상태

Status: RFC.

담당자

제안:

담당자:

도메인 전문가: