새로운 러너 등록 워크플로우로 마이그레이션
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
이 페이지에는 개발 중인 제품, 기능에 대한 정보가 포함되어 있습니다. GitLab 16.0은 러너 인증 토큰을 사용하여 러너를 등록하는 새로운 러너 생성 워크플로우를 도입했습니다. 새 워크플로우의 현재 개발 상태에 대한 자세한 내용은 에픽 7663을 참조하세요.
이 페이지에는 개발 중인 제품, 기능에 대한 정보가 포함되어 있습니다. 이 정보는 참고 목적으로만 제공되며, 구매 또는 계획 시 이 정보에 의존하지 마십시오.
GitLab 16.0은 러너 인증 토큰을 사용하여 러너를 등록하는 새로운 러너 생성 워크플로우를 도입했습니다. 등록 토큰을 사용하는 레거시 워크플로우는 권장되지 않습니다. 대신 러너 생성 워크플로우를 사용하세요.
새 워크플로우의 현재 개발 상태에 대한 자세한 내용은 에픽 7663을 참조하세요.
새 아키텍처의 기술적 설계 및 이유에 대한 자세한 내용은 차세대 GitLab Runner 토큰 아키텍처를 참조하세요.
새 러너 등록 워크플로우에 문제가 있거나 우려 사항이 있거나 더 많은 정보가 필요한 경우 피드백 이슈에 알려주세요.
새로운 러너 등록 워크플로우#
새로운 러너 등록 워크플로우에서:
- GitLab UI에서 직접 또는 프로그래밍 방식으로 러너를 생성합니다.
- 러너 인증 토큰을 받습니다.
- 이 구성으로 러너를 등록할 때 등록 토큰 대신 러너 인증 토큰을 사용합니다. 여러 호스트에 등록된 러너 매니저는 GitLab UI에서 동일한 러너 아래에 나타나지만 식별 시스템 ID가 있습니다.
새로운 러너 등록 워크플로우의 이점은 다음과 같습니다:
- 러너에 대한 소유권 기록 보존 및 사용자에 대한 영향 최소화.
- 고유한 시스템 ID 추가로 여러 러너에서 동일한 인증 토큰을 재사용할 수 있습니다. 자세한 내용은 GitLab Runner 구성 재사용을 참조하세요.
계획된 변경 사항의 예상 일정#
- GitLab 15.10 이상에서 새 러너 등록 워크플로우를 사용할 수 있습니다.
러너 등록 워크플로우가 중단되는 것을 방지#
GitLab 16.11 이하에서는 레거시 러너 등록 워크플로우를 사용할 수 있습니다.
GitLab 17.0 이상에서는 인스턴스 관리자 또는 그룹 소유자가 레거시 러너 등록 워크플로우를 비활성화할 수 있습니다. 자세한 내용은 GitLab 17.0 이후 등록 토큰 사용을 참조하세요.
새 워크플로우로 마이그레이션하지 않고 러너를 등록하면 러너 등록이 중단되고 gitlab-runner register 명령은 410 Gone - runner registration disallowed 오류를 반환합니다.
끊어진 워크플로우를 방지하려면:
- 러너를 생성하고 인증 토큰을 얻습니다.
- 러너 등록 워크플로우에서 등록 토큰을 인증 토큰으로 교체합니다.
GitLab 17.0 이후 등록 토큰 사용#
GitLab 17.0 이후 등록 토큰을 계속 사용하려면:
- GitLab.com에서 최상위 그룹 설정에서 레거시 러너 등록 프로세스를 수동으로 활성화할 수 있습니다.
- GitLab Self-Managed에서 Admin 영역 설정에서 레거시 러너 등록 프로세스를 수동으로 활성화할 수 있습니다.
기존 러너에 대한 영향#
기존 러너는 GitLab 17.0으로 업그레이드한 후에도 정상적으로 계속 작동합니다. 이 변경 사항은 새 러너 등록에만 영향을 미칩니다.
GitLab Runner Helm 차트는 job이 실행될 때마다 새 러너 포드를 생성합니다. 이러한 러너의 경우 등록 토큰을 사용하려면 레거시 러너 등록을 활성화하세요.
gitlab-runner register 명령 구문 변경#
gitlab-runner register 명령은 등록 토큰 대신 러너 인증 토큰을 허용합니다. Admin 영역의 러너 페이지에서 토큰을 생성할 수 있습니다. 러너 인증 토큰은 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 차트와 같은 자동 확장 시나리오에서, UI에서 생성된 러너 인증 토큰이 등록 토큰을 대체합니다. 이는 각 job에 대해 러너를 생성하는 대신 동일한 러너 구성이 job 전반에 걸쳐 재사용된다는 것을 의미합니다. 특정 러너는 러너 프로세스가 시작될 때 생성되는 고유한 시스템 ID로 식별될 수 있습니다.
프로그래밍 방식으로 러너 생성#
GitLab 15.11 이상에서는 POST /user/runners REST API를 사용하여 인증된 사용자로 러너를 만들 수 있습니다. 러너 구성이 동적이거나 재사용 불가능한 경우에만 사용해야 합니다. 러너 구성이 정적인 경우 기존 러너의 러너 인증 토큰을 재사용해야 합니다.
러너 생성 및 등록 자동화 방법에 대한 지침은 튜토리얼 러너 생성 및 등록 자동화를 참조하세요.
Helm 차트로 GitLab Runner 설치#
러너 등록 토큰이 비활성화된 경우 러너 등록 중에 일부 러너 구성 옵션을 설정할 수 없습니다. 이러한 옵션은 다음에서만 구성할 수 있습니다:
- UI에서 러너를 만들 때.
user/runnersREST API 엔드포인트를 사용하여.
다음 구성 옵션은 해당 시나리오에서 values.yaml에서 지원되지 않습니다:
## 러너 인증 토큰이 runnerRegistrationToken에 지정된 경우 등록은 성공하지만
## 다른 값은 무시됩니다.
runnerRegistrationToken: ""
locked: true
tags: ""
maximumTimeout: ""
runUntagged: true
protected: true
Kubernetes의 GitLab Runner의 경우, Helm 배포는 러너 인증 토큰을 러너 워커 포드에 전달하고 러너 구성을 만듭니다. GitLab 17.0 이상에서 GitLab.com에 연결된 Kubernetes 호스팅 러너에서 runnerRegistrationToken 토큰 필드를 사용하면 러너 워커 포드가 생성 중에 레거시 등록 API 방법을 사용하려고 합니다.
유효하지 않은 runnerRegistrationToken 필드를 runnerToken 필드로 교체하세요. secrets에 저장된 러너 인증 토큰도 수정해야 합니다.
레거시 러너 등록 워크플로우에서 필드는 다음과 같이 지정되었습니다:
apiVersion: v1
kind: Secret
metadata:
name: gitlab-runner-secret
type: Opaque
data:
runner-registration-token: "REDACTED" # DEPRECATED, set to ""
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로 러너를 등록하는 동안, Custom Resource Definition의 러너 인증 토큰이 토큰 교체 중에 업데이트되지 않습니다. 이는 다음과 같은 경우에 발생합니다:
- Custom Resource Definition에서 참조되는 비밀에서 러너 인증 토큰(
glrt-로 시작)을 사용하는 경우. - 러너 인증 토큰이 만료될 예정인 경우. 러너 인증 토큰 만료에 대한 자세한 내용은 인증 토큰 보안을 참조하세요.
자세한 내용은 이슈 186을 참조하세요.