• 요약
• 제안
  • 현재와 새 러너 등록 흐름 비교
  • 등록 토큰 대신 인증 토큰 사용하기
  • 전환 기간
  • 여러 시스템에서 러너 인증 토큰 재사용하기
    • system_id 값 생성
  • CI 작업에서 러너 식별
• 이점
• 세부 정보
  • 레거시 러너 처리
  • ci_runner_machines 레코드 수명
  • 필요한 적응 사항
    • ci_runner_machines 테이블로의 이관
    • REST API
    • GraphQL CiRunner 유형
    • 낡은(Stale) 러너 정리
  • API를 통한 러너 생성
• 구현 계획
  • 단계 1 - 폐기
  • 단계 2 - system_id를 위한 gitlab-runner 준비
  • 단계 2a - gitlab-runner Helm Chart와 gitlab-runner Operator 준비
  • 단계 3 - 데이터베이스 변경
  • Stage 4 - UI에서 러너 생성
  • Stage 5 - 등록 토큰 비활성화(옵션)
  • Stage 6 - 시행
  • Stage 7 - 제거 사항
• FAQ
• 상태
• 담당자

다음 GitLab Runner 토큰 아키텍처

요약

GitLab Runner는 신뢰할 수 있고 동시에 안정적인 환경에서 CI/CD 작업을 실행하는 GitLab CI/CD의 핵심 구성 요소입니다. 서비스의 초창기부터 Ruby 프로그램으로 시작되었으며, 러너는 GitLab 인스턴스에 등록됩니다. 그때 사용되는 것이 랜덤으로 생성된 텍스트 문자열인 등록 토큰입니다. 등록 토큰은 해당 범위(인스턴스, 그룹 또는 프로젝트)에 대해 고유합니다. 등록 토큰은 러너를 등록한 당사자가 인스턴스, 그룹 또는 프로젝트에 관리 액세스 권한을 가지고 있음을 증명합니다.

이 방식은 초기 몇 년 동안 잘 작동했지만, 대상 사용자가 늘어나면서 몇 가지 주요 알려진 문제점이 드러나기 시작했습니다:

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

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

제안

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

등록 토큰이 없어지므로 남은 우려 사항이 없어집니다.

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

:::mermaid graph TD subgraph new[새로운 등록 흐름] A[GitLab: 사용자가 GitLab UI에서 러너를 만들고 러너 구성을 추가합니다] –>|GitLab: ci_runners 레코드를 생성하고
새로운 ‘glrt-‘ 접두사가 붙은 인증 토큰을 반환| B B(러너: 사용자가 ‘gitlab-runner register’ 명령을 실행하여
GitLab 인스턴스에 새로운 러너 매니저를 등록할 때 인증 토큰을 사용) –> C{러너: gitlab-runner 구성 디렉토리에 .runner_system_id 파일이 있습니까?} C –>|예| D[러너: 기존 시스템 ID 읽기] –> F C –>|아니요| E[러너: 고유한 시스템 ID 생성 및 저장] –> F F[러너: ‘POST /runner/verify’ 요청을 발행하여 인증 토큰 유효성 검사] –> G{GitLab: 인증 토큰이 유효합니까?} G –>|예| H[GitLab: ci_runner_machine 데이터베이스 레코드 생성(없는 경우)] –> J[러너: .config.toml에 인증 토큰 저장] G –>|아니요| I(GitLab: ‘403 Forbidden’ 오류 반환) –> K(gitlab-runner register 명령 실패) J –> Z(러너 및 러너 매니저 사용 가능) end

subgraph current[<b>현재 등록 흐름</b>]
A'[<b>GitLab</b>: 사용자가 GitLab UI에서 러너 등록 토큰을 검색] --> B'
B'[<b>러너</b>: 사용자가 'gitlab-runner register' 명령을 실행하여<br/>새 러너를 등록하기 위해 등록 토큰을 사용] -->|<b>러너</b>: 'POST /runner request' 발행하여 새로운 러너를 생성하고<br/>인증 토큰을 얻음| C'{<b>GitLab</b>: 등록 토큰이 유효합니까?}
C' -->|예| D'[<b>GitLab</b>: ci_runners 데이터베이스 레코드 생성] --> F'
C' -->|아니요| E'(<b>GitLab</b>: '403 Forbidden' 오류 반환) --> K'(gitlab-runner register 명령 실패)
F'[<b>러너</b>: 응답에서 인증 토큰 저장<br/>.config.toml에 저장] --> Z'(러너 사용 가능)
end

style new fill:#f2ffe6 :::

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

이 제안에서는 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 러너 당 CI 러너의 제한을 최종적으로 낮출 수 있어야 합니다.

system_id 값 생성

우리는 언제나 gitlab-runner 설치에 독특한 시스템 식별자가 할당되도록 합니다. 이 식별자는 기존의 기계 식별자 (예: Linux의 /etc/machine-id)에서 파생되며 개인 정보 보호를 위해 해시 처리되며, 이 경우 s_로 접두사가 붙습니다. 식별자를 사용할 수 없는 경우에는 무작위 문자열을 대신 사용하며, 이 경우 r_로 접두사가 붙습니다.

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

ID는 gitlab-runner 시작시 및 구성을 디스크에 저장할 때 생성되고 저장됩니다. 그러나 config.toml의 루트에 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 레코드가 존재하지 않을 때에 대비하여 되도록 필요할 것입니다. 예상 시나리오는 러너가 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
);

이점

• 사용자들이 개념을 이해하기 쉽습니다: 2 종류의 토큰 대신, 단일 유형의 토큰인 러너 인증 토큰이 있습니다. 2 종류의 토큰을 가지고 있는 것은 문제를 논의할 때 자주 오해를 일으킵니다;
• 러너는 항상 생산한 사용자에게 연결될 수 있으며 감사 로그를 사용하여 추적할 수 있습니다;
• CI 러너의 클레임은 생성 시간에 알려져 있으며 러너에서 변경될 수 없습니다(예: access_level/protected 플래그 변경). 그러나 인증된 사용자는 여전히 GitLab UI를 통해 이러한 설정을 편집할 수 있습니다;
• ci_runner 테이블에 영향을 주지 않는 효과적인 생성되지 않은 러너 정리가 가능합니다.

세부 정보

제안된 방법에서는 전환 기간 동안 현재 등록 토큰 방법과 함께 사용할 수 있는 러너를 구성할 수 있는 독특한 방법을 만듭니다. 이 아이디어는 러너가 새로운 러너를 등록할 수 있는 단일 “신의 것 같은” 토큰을 활용하는 API 호출을 피하는 것입니다.

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

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

3. 사용자가 ‘생성’을 클릭하면 다음이 발생합니다:

   1. 새로운 러너와(glrt- 접두사가 있는) 인증 토큰이 ci_runners 테이블에 생성됩니다;
   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”) 상태가 됩니다(러너 heartbeats에 대한 것과 같이 앞에 Redis 캐시가 포함됨).

전환 기간의 일환으로, 운영자와 최상위 그룹 소유자에게 레거시 등록 토큰 기능을 비활성화하고 새로운 작업 흐름만 사용하도록 강제하는 인스턴스/그룹-단위 설정(allow_runner_registration_token)이 제공됩니다. gitlab-runner register 명령에 의한 새 러너 등록 시 POST /api/v4/runners 엔드포인트로의 시도는 HTTP 410 Gone 상태 코드로 결과됩니다.

인스턴스 설정은 하위 그룹에 상속됩니다. 이는 인스턴스 수준에서 레거시 등록 방법이 비활성화되면 자손 그룹/프로젝트가 반드시 레거시 등록 방법을 방지합니다.

등록 토큰 작업 흐름은 사용이 중단될 예정입니다(gitlab-runner register 명령에 의해 출려되는 사용 중단 공지 후)하고 새 작업 흐름으로 마이그레이션하는 고객이 안전하다는 것이 검증된 다음, 향후 주요 릴리스에서 제거될 것입니다.

레거시 러너 처리

레거시 버전의 GitLab 러너는 요청에 고유 시스템 식별자를 보내지 않으며, 워크호스에서 고유 시스템 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에서 일치하는 항목이 없을 경우에는 기존 ci_runner의 필드로 되돌아야 합니다.

REST API

러너 토큰을 받는 API 엔드포인트는 러너 토큰과 함께 선택적으로 system_id 매개변수를 받도록 변경되어야 합니다(대부분 요청 본문의 JSON 매개변수로 제공됨).

GraphQL CiRunner 유형

CiRunner 유형은 ci_runners 모델을 밀접하게 반영합니다. 이는 제안된 방식에서 ipAddress, architectureName, executorName 등과 같은 기계 정보가 더 이상 단일 값이 아니라는 것을 의미합니다. 우리는 당분간 그 사실을 받아들일 수 있으며, 쉼표로 구분된 고유한 값의 목록을 반환하기 시작할 수 있습니다. 해당 CiRunner 필드는 ci_runner_machines 항목의 값을 반환해야 합니다(ci_runner 레코드가 존재하지 않는 경우에는 ci_runner 레코드로 되돌아야 함).

낡은(Stale) 러너 정리

낡은(Stale) 러너를 정리하는 기능은 ci_runners 레코드가 아닌 ci_runner_machines 레코드를 정리하도록 적응되어야 합니다.

등록 토큰 지원이 제거된 후 언젠가, 우리는 ci_runners 테이블에서 생성된 낡은(Stale) 러너를 정리하기 위한 백그라운드 이관을 만들고 싶어할 것입니다( ci_runners 테이블에서 생성된 열거형 열을 활용).

API를 통한 러너 생성

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

구현 계획

단계 1 - 폐기

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

단계 2a - gitlab-runner Helm Chart와 gitlab-runner Operator 준비

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

(이하 생략)

Stage 4 - UI에서 러너 생성

Stage 5 - 등록 토큰 비활성화(옵션)

Stage 6 - 시행

Stage 7 - 제거 사항

FAQ

사용자 설명서을 따르세요.

상태

상태: RFC.

담당자

제안:

DRIs:

도메인 전문가: