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

다음 GitLab Runner 토큰 아키텍처

요약

GitLab Runner는 신뢰할 수 있고 동시에 안정적인 환경에서 CI/CD 작업을 실행하는 GitLab CI/CD의 핵심 컴포넌트입니다. 서비스가 루비 프로그램으로 시작됐던 이래로, 러너는 GitLab 인스턴스에 등록되어 관리자가 소유한 랜덤으로 생성된 텍스트 문자열인 등록 토큰으로 등록됩니다. 등록 토큰은 해당 scope(인스턴스, 그룹 또는 프로젝트)에 대해 고유합니다. 등록 토큰은 러너를 등록한 당사자가 해당 인스턴스, 그룹 또는 프로젝트에 대한 관리 액세스를 가지고 있음을 증명합니다.

이 방식은 초기 몇 년간 잘 작동했지만, 대상 사용자 규모가 커짐에 따라 일부 중요한 알려진 문제점들이 드러나기 시작했습니다:

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

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

제안

이 제안은 scope 당 단일 토큰 및 토큰 저장 문제를 해결하여, 등록 토큰이 필요하지 않도록 합니다. 러너 생성은 인증된 사용자의 컨텍스트에서 지정된 scope의 GitLab 러너 설정 페이지에서 발생하며, 추적 가능성을 제공합니다. 해당 페이지에서는 지원되는 환경에서 새로 생성된 러너를 구성하는 지침이 제공됩니다.

나머지 우려 사항들은 등록 토큰이 없어짐으로 인해 문제가 되지 않습니다.

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

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

이 제안에서, 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에서는 기존의 워크플로우를 권장하지 않습니다. 사용자들은 새로운 흐름을 통해 러너를 만들고 결과로 나온 인증 토큰을 오늘날처럼 gitlab-runner register 명령과 함께 사용하도록 유도됩니다. 이 접근 방식은 러너를 배포하는 사용자들에게 혼란을 줄입니다.

여러 대의 기계에서 러너 인증 토큰 재사용

기존의 자동 스케일링 모델에서는 새 작업을 실행해야 할 때마다 새로운 러너가 생성됩니다. 이로써 러너가 남아서 사용되지 않게 되는 상황이 많이 발생했습니다.

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

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

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

system_id 값 생성

우리는 gitlab-runner 설치에 항상 고유한 시스템 식별자가 할당되도록 합니다. 해당 ID는 기존 기계 식별자(예: Linux의 /etc/machine-id)에서 파생되어 개인 정보 보호를 위해 해싱된 것이며, 이 경우에는 s_로 접두사가 붙습니다. ID가 사용 불가능한 경우 무작위 문자열이 대신 사용되며, 그 경우에는 r_로 접두사가 붙습니다.

이 고유 ID는 gitlab-runner 프로세스를 식별하고 config.toml 파일에 대한 모든 러너의 POST /api/v4/jobs 요청으로 전송됩니다.

ID는 gitlab-runner 시작 시와 구성이 디스크에 저장될 때마다 생성되고 저장됩니다. 그러나 config.toml 파일의 루트에 ID를 저장하는 대신 새로운 파일인 .runner_system_id에 저장하며, 이렇게 함으로써 config.toml 파일이 매뉴얼으로 복사됨에 따라 ID가 재사용될 가능성을 줄입니다.

s_cpwhDr7zFz4xBJujFeEM

CI 작업에서의 러너 식별

사용자가 작업을 실행한 기계를 식별하기 위해 고유 식별자는 CI 작업 콘텍스트에 표시되어야 합니다. 처음으로, GitLab 러너는 빌드 로그에 고유 시스템 식별자를 포함하게 됩니다. 여기서 러너 토큰 SHA가 게시됩니다.

러너는 잠재적으로 다른 고유 시스템 식별자와 함께 재사용될 수 있으므로 고유 시스템 ID를 데이터베이스에 저장해야 합니다. 이는 고유 시스템 ID가 러너 토큰과 매핑될 수 있도록 보장합니다. 새 ci_runner_machines 테이블은 러너 관리자 각각에 대한 정보를 보유하며 러너가 마지막으로 연결된 시간 및 런타임 유형에 대한 정보가 포함됩니다.

장기적으로 관련 필드는 ci_runners에서 ci_runner_machines로 이동합니다. 그러나 삭제 마일스톤 이전에 해당 정보는 ci_runners에 유지될 것입니다. 즉, 해당 ci_runner_machines 레코드가 없는 경우에만 ci_runners를 대체로 사용할 수 있습니다. 러너가 오프라인인 경우와 같은 경우가 예상됩니다.

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

• 러너를 생성한 사용자를 추적하는 creator_id 열;
• ci_runners에 대한 열거형 열인 registration_type을 추가하여 러너가 레거시 register 방법을 사용하여 생성되었는지 또는 새 UI 기반 방법을 사용했는지를 신호하는 것입니다. 가능한 값은 :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 테이블을 건드리지 않는, 효율적인 낡은 러너 청소가 쉽습니다.

상세 내용

제안된 접근 방식에서는 전환 기간 동안 기존 등록 토큰 방법과 함께 사용할 수 있는 러너를 구성하는 새로운 방법을 만듭니다. 핵심은 러너가 새로운 러너를 등록하는 데 단일 “최고의” 토큰을 활용하는 API 호출을 하는 일을 피하는 것입니다.

새로운 워크플로우는 다음과 같습니다.

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

3. 만들기를 클릭하면 다음이 발생합니다:

   1. ci_runners 테이블에 새 러너(및 해당하는 glrt-로 접두사가 붙은 인증 토큰)가 생성됩니다.
   2. 사용자가이 새로운 러너를 기계에 구성하는 방법에 대한 지침이 표시됩니다. 지원되는 서로 다른 배포 시나리오(예: 셸, docker-compose, Helm 차트 등)에 대한 가능성을 제공합니다. 이 정보에는 사용자만 한 번 볼 수 있는 토큰이 포함되어 있으며 UI에서 동일한 러너를 여러 번 등록하지 말아야 한다는 것이 명확하게 표시됩니다.

4. 의도된 배포 시나리오(등록 명령)에 대한 지침을 복사하여 붙여넣으면 다음 작업이 수행됩니다:

   1. 지침에 따라 새 gitlab-runner register 명령을 실행하면 gitlab-runner은 주어진 러너 토큰으로 POST /api/v4/runners/verify를 호출합니다.
   2. POST /api/v4/runners/verify GitLab 엔드포인트가 토큰을 유효성 검사하면 config.toml 파일이 설정값으로 채워집니다.
   3. 러너가 작업을 위해 핑을 보낼 때마다 해당 ci_runner_machines 레코드는 러너에 대한 최신 정보로 “upserted”됩니다(Runner heartbeats처럼 Redis 캐시가 앞에 있습니다).

전환 기간 동안 인스턴스 및 최상위 그룹 소유자에게 allow_runner_registration_token 인스턴스/그룹 수준 설정을 제공하여 레거시 등록 토큰 기능을 비활성화하고 새 워크플로우만 사용하도록 강제할 수 있습니다. 새 등록 방법으로 러너를 등록하려는 gitlab-runner register 명령의 모든 시도는 POST /api/v4/runners 엔드포인트에 히트하려는 경우 HTTP 410 Gone 상태 코드가 됩니다.

인스턴스 설정은 하위 그룹에 상속됩니다. 즉, 인스턴스 방법에서 레거시 등록 방법을 비활성화하는 경우 하위 그룹/프로젝트는 레거시 등록 방법을 강제적으로 방지합니다.

등록 토큰 워크플로우는 폐지되며(gitlab-runner register 명령에 의해 폐지 알림이 인쇄됨) 새 워크플로우로 고객이 이동하고 개념이 안정화되는 경우, 향후 주요 릴리스에서 제거될 것입니다.

레거시 러너 처리

GitLab Runner의 레거시 버전은 요청에서 고유한 시스템 식별자를 보내지 않으며, Workhorse의 논리를 변경하여 고유 시스템 ID를 처리하지 않을 것입니다. 레거시 등록 시스템이 제거되고 러너가 새 버전으로 업그레이드된 후에 이를 개선할 수 있습니다.

이러한 레거시 러너로부터의 작업 핑은 <legacy> system_xid 필드 값이 포함된 ci_runner_machines 레코드를 생성합니다.

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

ci_runner_machines 레코드 유지 기간

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

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

ci_runner_machines 레코드의 성질적인 특성으로 인해 해당 레코드는 해당 러너의 마지막 연락 후 7일 후에 자동으로 정리됩니다.

필요한 적응

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

ci_runner_machines의 데이터가 필요한 경우, ci_runner_machines에서 일치하는 항목을 찾지 못했을 때 기존 필드에서 후퇴해야 합니다.

REST API

러너 토큰을 받는 API 엔드포인트는 보통 요청 바디의 JSON 매개변수로 러너 토큰과 함께 선택적인 system_id 매개변수를 함께 사용하도록 변경되어야 합니다.

GraphQL CiRunner 타입

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

오래된 러너 정리

오래된 러너를 정리하는 기능은 ci_runners 레코드 대신 ci_runner_machines 레코드를 정리하도록 적응되어야 합니다.

등록 토큰 지원이 제거된 후 어느 시점 이후에는 등록된 채로 오래된 러너를 정리하는 백그라운드 마이그레이션을 생성할 의향이 있습니다. (ci_runners 테이블에서 생성된 enum 열을 활용).

API를 통한 러너 생성

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

실행 계획

단계 1 - 폐기 요소

단계 2 - gitlab-runner를 system_id에 맞게 준비

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

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

Stage 4 - UI에서 러너 생성

단계 5 - 등록 토큰 옵션적 비활성화

단계 6 - 집행

단계 7 - 제거

FAQ

사용자 문서를 따르세요.

상태

Status: RFC.

담당자

제안:

DRIs:

Domain experts: