새로운 러너 등록 워크플로우로 이전하기

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
이 페이지에는 예정된 제품, 기능 및 기능과 관련된 정보가 포함되어 있습니다. 중요한 점은 제시된 정보가 정보 목적으로만 제공된다는 것입니다. 이 정보를 구매 또는 계획 목적으로 의존하지 마십시오. 제품, 기능 또는 기능의 개발, 릴리스 및 타이밍은 변경되거나 지연 될 수 있으며 GitLab Inc.의 재량에 따라 달려 있습니다.

GitLab 16.0에서 러너 생성 워크플로우를 새로 소개했습니다. 이 워크플로우는 러너 인증 토큰을 사용하여 러너를 등록합니다. 레가시 워크플로우인 등록 토큰을 사용하는 것은 없어지고 GitLab 18.0에서 제거될 예정입니다.

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

새 아키텍처의 기술적인 설계 및 이유에 대한 정보는 다음 GitLab 러너 Token 구조를 참조하세요.

새 러너 등록 워크플로우에 대한 문제 또는 우려 사항이 있거나 다음 정보가 충분하지 않은 경우, 피드백 이슈에 알려주세요.

새 러너 등록 워크플로우

새 러너 등록 워크플로우에서 다음을 수행합니다:

  1. GitLab UI에서 러너를 직접 생성하거나 프로그래밍적으로 생성합니다.
  2. 러너 인증 토큰을 받습니다.
  3. 이 구성으로 러너를 등록할 때 등록 토큰 대신 러너 인증 토큰을 사용합니다. 여러 호스트에 등록된 러너 관리자는 식별 시스템 ID가 있는 동일한 러너 아래에 나타납니다.

새 러너 등록 워크플로우에는 다음과 같은 이점이 있습니다:

  • 러너의 소유권 레코드가 유지되고 사용자에게 미치는 영향이 최소화됩니다.
  • 고유한 시스템 ID의 추가로 동일한 인증 토큰을 여러 러너에 재사용할 수 있습니다. 자세한 정보는 GitLab 러너 구성 재사용을 참조하세요.

계획된 변경의 예상 시간 테이블

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

러너 등록 워크플로우의 중단 방지

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

GitLab 17.0에서는 레거시 러너 등록 워크플로우가 자동으로 비활성화됩니다. 일정 기간 동안 수동으로 다시 활성화할 수 있습니다. 자세한 정보는 GitLab 17.0 이후 등록 토큰 사용을 참조하세요.

GitLab 인스턴스가 GitLab 17.0으로 업그레이드되기 전에 조치를 취하지 않으면 러너 등록 워크플로우가 중단되고 gitlab-runner register 명령은 410 Gone - runner registration disallowed 오류를 받게 됩니다.

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

  1. 러너를 생성하고 인증 토큰을 받습니다.
  2. 러너 등록 워크플로우에서 등록 토큰을 인증 토큰으로 교체합니다.

경고: GitLab 17.0 이상에서 러너 등록 토큰은 비활성화됩니다. 저장된 러너 등록 토큰을 사용하여 새 러너를 등록하려면 토큰을 활성화해야 합니다.

GitLab 17.0 이후 등록 토큰 사용

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

기존 러너에 미치는 영향

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

GitLab 러너 Helm 차트는 작업 실행 시마다 새로운 러너 파드를 생성합니다. 이러한 러너를 사용하려면 레거시 러너 등록 활성화가 필요합니다. GitLab 18.0 이후에는 새 러너 등록 워크플로우로 마이그레이션해야 합니다.

gitlab-runner register 명령 구문 변경

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

GitLab UI에서 러너를 생성할 때, 이전에 gitlab-runner register 명령에서 프롬프트된 명령줄 옵션 값을 지정합니다. 이러한 명령줄 옵션은 폐기 예정되었습니다.

러너 인증 토큰이 있는 경우:

  • --token 명령줄 옵션으로 지정하면 gitlab-runner register 명령은 구성 값을 허용하지 않습니다.
  • --registration-token 명령줄 옵션으로 지정하면 gitlab-runner register 명령은 구성 값을 무시합니다.
토큰 등록 명령
러너 인증 토큰 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 "REDACTED"

GitLab 15.10 이상에서는 UI에서 러너를 만들고 태그 목록, 잠금 상태 및 액세스 수준과 같은 일부 속성을 지정합니다. GitLab 15.11 이상에서는 러너 인증 토큰에 glrt- 접두사가 있는 경우 이러한 속성을 register에 인수로 더 이상 허용하지 않습니다.

다음 예시에서는 새 명령이 표시됩니다: 

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

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

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

잘못된 runnerRegistrationToken 필드의 대체 필드는 runnerToken 필드입니다. Kubernetes에 있는 GitLab Runner의 맥락에서, Helm deploy는 러너 인증 토큰을 러너 워커 파드로 전달하고 러너 구성이 생성됩니다. 만약, GitLab.com에 연결된 Kubernetes 호스트 러너에서 계속해서 runnerRegistrationToken 토큰 필드를 사용한다면, 러너 워커 파드는, 생성 시, 더 이상 지원되지 않는 등록 API 방법을 사용하려고 시도합니다 (GitLab 17.0부터 더 이상 지원되지 않음).

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"

참고: 시크릿 관리 솔루션이 runner-registration-token에 빈 문자열을 설정할 수 없는 경우, 임의의 문자열로 설정할 수 있습니다. 그러면 runner-token이 있는 경우 무시됩니다.

알려진 문제

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

Helm 차트를 사용하여 러너를 등록하는 새로운 등록 워크플로를 사용할 때, 러너 세부 정보 페이지에 포드 이름이 표시되지 않습니다. 자세한 정보는 issue 423523를 참조하세요.

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

동일한 러너가 여러 러너 매니저에 등록되어 있는 경우 토큰 로테이션

새로운 워크플로를 사용하여 여러 호스트 머신에 러너를 등록하고 러너 인증 토큰이 자동으로 로테이션되는 경우, 토큰 갱신 요청을 처리하는 첫 번째 러너 매니저만 새 토큰을 받습니다. 나머지 러너 매니저는 계속해서 잘못된 토큰을 사용하고 연결이 끊어집니다. 이러한 매니저를 수동으로 업데이트하여 새 토큰을 사용해야 합니다.

GitLab Operator에서 토큰 로테이션

새로운 등록 워크플로를 사용하여 GitLab Operator로 러너를 등록하는 경우, 토큰이 로테이션이 되어도 커스텀 리소스 정의에 의해 참조되는 러너 인증 토큰이 업데이트되지 않습니다.

  • 커스텀 리소스 정의에서 참조된 시크릿에서 glrt-로 시작하는 러너 인증 토큰을 사용하는 경우
  • 러너 인증 토큰이 만료되어야 하는 경우 러너 인증 토큰 만료에 대한 자세한 정보는 Authentication token security를 참조하세요.

자세한 정보는 issue 186을 참조하세요.