새로운 러너 등록 워크플로우로 마이그레이션

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

새로운 러너 등록 워크플로우

GitLab 16.0에서 러너 인증 토큰을 사용하여 러너를 등록하는 새로운 워크플로우를 소개했습니다. 등록 토큰을 사용하는 기존 워크플로우는 폐기되며 GitLab 18.0에서 제거될 예정입니다.

새 워크플로우의 현재 개발 상태에 대한 정보는 epic 7663를 참조하십시오.

새로운 아키텍처에 대한 기술적 설계 및 이유에 대한 정보는 Next GitLab Runner Token Architecture를 참조하십시오.

새로운 러너 등록 워크플로우를 사용하면 다음과 같은 이점이 있습니다:

  • 러너에 대한 소유권 레코드 유지 및 사용자에 대한 영향 최소화.
  • 동일한 인증 토큰을 여러 러너에 재사용할 수 있는 고유 시스템 ID의 추가. 자세한 내용은 GitLab Runner 구성 재사용을 참조하십시오.

계획된 변경의 예상 시간대

  • GitLab 15.10 이상에서는 새로운 러너 등록 워크플로우를 사용할 수 있습니다.
  • GitLab 17.0에서 러너 등록 토큰을 비활성화할 계획입니다.
  • GitLab 18.0에서 러너 등록 토큰 지원을 완전히 제거할 계획입니다.

러너 등록 워크플로우의 중단을 방지하십시오

GitLab 17.0까지는 기존 러너 등록 워크플로우를 계속 사용할 수 있습니다.

GitLab 17.0에서 기존 러너 등록 워크플로우가 자동으로 비활성화됩니다. 한정된 기간 동안 매뉴얼으로 기존 러너 등록 워크플로우를 다시 활성화할 수 있습니다. 자세한 내용은 GitLab 17.0 이후 등록 토큰 사용 방법을 참조하십시오.

GitLab 인스턴스를 GitLab 17.0으로 업그레이드하기 전에 조치를 취하지 않으면 러너 등록 워크플로우가 중단됩니다.

러너 워크플로우가 중단되지 않도록 하려면 다음을 수행해야 합니다:

  1. 인스턴스 러너 생성 및 인증 토큰 획들.
  2. 러너 등록 워크플로우에서 등록 토큰을 인증 토큰으로 교체합니다.

GitLab 17.0 이후 등록 토큰 사용 방법

GitLab 17.0 이후 등록 토큰을 계속 사용하려면:

  • GitLab.com에서는 GitLab 18.0까지 최상위 그룹 설정에서 기존 러너 등록 프로세스를 매뉴얼으로 다시 활성화할 수 있습니다.
  • GitLab Self-managed에서는 GitLab 18.0까지 관리자 영역 설정에서 기존 러너 등록 프로세스를 매뉴얼으로 다시 활성화할 수 있습니다.

등록 토큰 다시 활성화를 위한 UI 설정 구현 계획은 issue 411923에 제안되었습니다.

기존 러너에 미치는 영향

기존 러너는 18.0 이후에도 계속해서 정상적으로 작동합니다. 이 변경은 새로운 러너의 등록에만 영향을 미칩니다.

gitlab-runner register 명령 구문 변경

gitlab-runner register 명령은 등록 토큰을 더 이상 수용하지 않고 대신 GitLab 러너 관리 페이지에서 생성된 새로운 러너 인증 토큰을 수용합니다. 러너 인증 토큰은 glrt- 접두사로 식별됩니다.

GitLab UI에서 러너를 생성하면 이전에 gitlab-runner register 명령으로 프롬프트된 구성 값들을 지정합니다. 이러한 명령 행 옵션들은 폐기되었습니다.

러너 인증 토큰을 지정하면:

  • --token 명령 행 옵션을 사용하여 구성 값들을 수용하지 않습니다.
  • --registration-token 명령 행 옵션을 사용하여 구성 값들을 무시합니다.
토큰 등록 명령
러너 인증 토큰 gitlab-runner register --token $RUNNER_AUTHENTICATION_TOKEN
러너 등록 토큰 (폐기됨) gitlab-runner register --registration-token $RUNNER_REGISTRATION_TOKEN <runner configuration arguments>

인증 토큰은 접두사 glrt-를 가지고 있습니다.

자동화 워크플로우에 최소한의 방해를 보장하려면, 레거시 호환 등록 처리는 러너 인증 토큰이 기존 매개변수 --registration-token에서 지정된 경우에 트리거됩니다.

GitLab 15.9의 예시 명령어: 

gitlab-runner register \
    --non-interactive \
    --executor "shell" \
    --url "https://gitlab.com/" \
    --tag-list "shell,mac,gdk,test" \
    --run-untagged "false" \
    --locked "false" \
    --access-level "not_protected" \
    --registration-token "GR1348941C6YcZVddc8kjtdU-yWYD"

GitLab 15.10 이상에서는 UI에서 러너 및 태그 디렉터리, 잠금 상태, 액세스 권한 수준과 같은 일부 속성을 생성하고 구성할 수 있습니다. GitLab 15.11 이상에서는 이러한 속성들이 더 이상 register에 인수로서 수락되지 않습니다. 이러한 속성들은 새로운 명령으로 지정됩니다.

다음 예시는 새로운 명령을 보여줍니다: 

gitlab-runner register \
    --non-interactive \
    --executor "shell" \
    --url "https://gitlab.com/" \
    --token "glrt-2CR8_eVxiioB1QmzPZwa"

오토스케일링에 미치는 영향

GitLab Runner Operator 또는 GitLab Runner Helm Chart와 같은 오토스케일링 시나리오에서 등록 토큰은 UI에서 생성된 러너 인증 토큰으로 대체됩니다. 이는 각 작업에 대해 러너를 만드는 대신에 동일한 러너 구성이 작업 전체에 재사용됨을 의미합니다. 특정 러너는 러너 프로세스가 시작될 때 생성되는 고유한 시스템 ID로 식별할 수 있습니다.

프로그래밍 방식으로 러너 생성

GitLab 15.11부터는 POST /user/runners REST API를 사용하여 인증된 사용자로써 러너를 만들 수 있습니다. 이는 러너 구성이 동적이거나 재사용할 수 없는 경우에만 사용해야 합니다. 러너 구성이 정적인 경우 기존 러너의 러너 인증 토큰을 재사용해야 합니다.

러너 생성 및 등록을 자동화하는 방법에 대한 지침은 러너 생성 및 등록 자동화하기를 참조하십시오.

Helm 차트로 GitLab Runner 설치하기

러너 등록 중에 일부 러너 구성 옵션을 설정할 수 없습니다. 이러한 옵션은 다음과 같이 구성할 수 있습니다:

  • UI에서 러너를 만들 때
  • user/runners REST API 엔드포인트로

다음 구성 옵션은 values.yaml에서 더 이상 지원되지 않습니다: 

## 모든 이 필드들이 사용되지 않으며 GitLab Runner 18.0 및 이후 버전에서 이를 지정하는 경우 러너를 시작하지 못합니다.
## runnerRegistrationToken에 러너 인증 토큰이 지정된 경우 등록은 성공하지만 다른 값들은 무시됩니다.
runnerRegistrationToken: ""
locked: true
tags: ""
maximumTimeout: ""
runUntagged: true
protected: true

러너 인증 토큰을 secrets에 저장하는 경우 이를 수정해야 합니다.

이전 러너 등록 워크플로에서 필드는 다음과 같이 지정되었습니다: 

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
type: Opaque
data:
  runner-registration-token: "REDACTED" # 사용되지 않음, ""로 설정
  runner-token: ""

새로운 러너 등록 워크플로에서는 대신 runner-token을 사용해야 합니다: 

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
type: Opaque
data:
  runner-registration-token: "" # 호환성을 위해 빈 문자열로 남겨야 함
  runner-token: "REDACTED"
note
시크릿 관리 솔루션이 runner-registration-token에 빈 문자열을 설정할 수 없는 경우 아무 문자열로 설정할 수 있습니다. 이는 runner-token이 있을 때 무시될 것입니다.

알려진 문제

러너 세부 정보 페이지에 포드 이름이 표시되지 않음

Helm 차트를 사용하여 러너를 등록할 때 새 등록 워크플로를 사용하는 경우 러너의 세부 정보 페이지에는 포드 이름이 표시되지 않습니다. 자세한 내용은 이슈 423523을 참조하십시오.

러너 인증 토큰이 로테이션될 때 업데이트되지 않음

새 등록 워크플로를 사용하여 GitLab Operator로 러너를 등록하는 경우, 사용자 정의 리소스 정의에서 참조하는 러너 인증 토큰이 로테이션될 때 업데이트되지 않습니다. 이는 다음 경우에 발생합니다:

  • 사용자 정의 리소스 정의에서 시크릿으로 참조하는 러너 인증 토큰을 사용하고 있을 때 (glrt-로 접두어가 붙는) 사용자 정의 리소스 정의에서 참조.
  • 러너 인증 토큰이 만료될 경우 러너 인증 토큰 만료에 대한 자세한 내용은 인증 토큰 보안을 참조하십시오.

자세한 내용은 issue 186을 참조하십시오.