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

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

이 페이지에는 향후 제품, 기능 및 기능에 대한 정보가 포함되어 있습니다.
제공된 정보는 정보 제공 목적으로만 사용되어야 합니다.
구매 또는 계획 목적으로 이 정보를 의존하지 마십시오.
제품, 기능 또는 기능의 개발, 릴리스 및 일정은 변경되거나 지연될 수 있으며 GitLab Inc.의 단독 재량에 따릅니다.

GitLab 16.0에서는 러너 인증 토큰을 사용하여 러너를 등록하는 새로운 러너 생성 워크플로우를 도입했습니다.
등록 토큰을 사용하는 이전 워크플로우는 더 이상 사용되지 않으며, GitLab 18.0에서 제거될 예정입니다.

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

새 아키텍처에 대한 기술 설계 및 이유에 대한 정보는 Next GitLab Runner Token Architecture를 참조하세요.

새로운 러너 등록 워크플로우에 문제가 발생하거나 우려 사항이 있는 경우,
또는 아래 정보가 충분하지 않은 경우, 피드백 문제를 통해 저희에게 알려주실 수 있습니다.

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

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

  1. 러너를 생성합니다. GitLab UI에서 직접 또는 프로그래밍 방식으로.
  2. 러너 인증 토큰을 받습니다.
  3. 해당 구성으로 러너를 등록할 때 등록 토큰 대신 러너 인증 토큰을 사용합니다.
    여러 호스트에 등록된 러너 관리자들은 GitLab UI에서 동일한 러너 아래에 나타나지만, 식별 가능한 시스템 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. 러너 등록 워크플로우에서 등록 토큰을 인증 토큰으로 교체합니다.
caution
GitLab 17.0 이후에는 러너 등록 토큰이 비활성화됩니다.
새로운 러너를 등록하기 위해 저장된 러너 등록 토큰을 사용하려면,
토큰을 활성화해야 합니다.

GitLab 17.0 이후 등록 토큰 사용법

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

기존 러너에 대한 영향

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

GitLab Runner 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 <러너 구성 인수>

인증 토큰은 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 배포는 러너 인증 토큰을 러너 작업자 파드에 전달하고 러너 구성이 생성됩니다.

GitLab.com에 연결된 Kubernetes 호스팅 러너에서 runnerRegistrationToken 토큰 필드를 계속 사용하면, 러너 작업자 파드는 생성 시 GitLab 17.0 이후 더 이상 지원되지 않는 등록 API 방법을 사용하려고 시도합니다.

러너 인증 토큰을 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 차트를 사용하여 러너를 등록하기 위해 새로운 등록 워크플로우를 사용할 때,

파드 이름이 러너 세부 정보 페이지에 표시되지 않습니다.

자세한 내용은 이슈 423523를 참조하세요.

러너 인증 토큰이 회전 시 업데이트되지 않음

여러 러너 관리자에 등록된 동일한 러너에 대한 토큰 회전

여러 호스트 머신에 러너를 등록하기 위해 새로운 워크플로를 사용할 때

러너 인증 토큰이 자동으로 회전되면,

토큰 갱신 요청을 처리하는 첫 번째 러너 관리자만 새 토큰을 받습니다.

나머지 러너 관리자들은 잘못된 토큰을 계속 사용하여 연결이 끊깁니다.

이러한 관리자들을 수동으로 업데이트하여 새 토큰을 사용해야 합니다.

GitLab Operator에서의 토큰 회전

GitLab Operator와 함께 러너를 등록하기 위해 새로운 등록 워크플로를 사용할 때,

사용자 정의 리소스 정의에서 참조된 러너 인증 토큰은 토큰이 회전될 때 업데이트되지 않습니다.

이는 다음과 같은 경우에 발생합니다:

러너 인증 토큰 만료에 대한 자세한 내용은,

인증 토큰 보안을 참조하세요.

자세한 내용은 이슈 186을 참조하세요.