새 러너 등록 워크플로로 마이그레이션하기

새 러너 등록 워크플로로 마이그레이션하기

러너 생성 워크플로는 러너 인증 토큰을 사용해 러너를 등록해요. 등록 토큰을 사용하는 기존(레거시) 워크플로는 권장되지 않아요. 러너 생성 워크플로를 대신 사용하세요.

출처: 문서

본문

새 러너 등록 워크플로

새 러너 등록 워크플로에서는 다음을 해요.

1. GitLab UI에서 직접 또는 프로그래밍 방식으로 러너를 만들어요.
2. 러너 인증 토큰을 받아요.
3. 이 구성으로 러너를 등록할 때 등록 토큰 대신 러너 인증 토큰을 사용해요. 여러 호스트에 등록된 러너 매니저는 GitLab UI에서 같은 러너 아래에 나타나지만, 식별용 시스템 ID가 붙어요.

새 러너 등록 워크플로에는 다음 이점이 있어요.

• 러너의 소유권 기록이 보존되고 사용자에게 미치는 영향이 최소화됨.
• 고유한 시스템 ID 추가로 여러 러너에서 같은 인증 토큰을 재사용할 수 있음. 자세한 내용은 GitLab Runner 구성 재사용을 참고해요.

러너 등록 워크플로가 깨지지 않도록 하기

GitLab 17.0 이상에서는 인스턴스 관리자나 그룹 소유자가 레거시 러너 등록 워크플로를 비활성화할 수 있어요. 자세한 내용은 GitLab 17.0 이후 등록 토큰 사용을 참고해요.

새 워크플로로 마이그레이션하지 않고 러너를 등록하면 러너 등록이 깨지고, gitlab-runner register 명령이 410 Gone - runner registration disallowed 오류를 반환해요.

워크플로가 깨지지 않게 하려면:

1. 러너를 만들고 인증 토큰을 얻어요.
2. 러너 등록 워크플로의 등록 토큰을 인증 토큰으로 교체해요.

GitLab 17.0 이후 등록 토큰 사용하기

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

• GitLab.com에서는 최상위 그룹 설정에서 수동으로 레거시 러너 등록 프로세스를 활성화할 수 있어요.
• GitLab Self-Managed에서는 Admin 영역 설정에서 수동으로 레거시 러너 등록 프로세스를 활성화할 수 있어요.

기존 러너에 미치는 영향

기존 러너는 GitLab 17.0으로 업그레이드한 후에도 평소처럼 계속 동작해요. 이 변경은 새 러너 등록에만 영향을 줘요.

GitLab Runner Helm 차트는 잡이 실행될 때마다 새 러너 포드를 생성해요. 이런 러너는 등록 토큰을 사용하려면 레거시 러너 등록을 활성화해야 해요.

gitlab-runner register 명령 문법 변경

gitlab-runner register 명령은 등록 토큰 대신 러너 인증 토큰을 받아요. Admin 영역의 Runners 페이지에서 토큰을 생성할 수 있어요. 러너 인증 토큰은 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-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"

러너 인증 토큰을 사용하면 이 속성들을 UI에서 러너를 만들 때 설정하고, 등록 명령은 토큰만 필요해요.

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

자동 확장에 미치는 영향

GitLab Runner Operator나 GitLab Runner Helm Chart 같은 자동 확장 시나리오에서, UI에서 생성된 러너 인증 토큰이 등록 토큰을 대체해요. 즉, 잡마다 러너를 만드는 대신 같은 러너 구성을 잡들 사이에 재사용한다는 의미예요. 특정 러너는 러너 프로세스가 시작될 때 생성되는 고유한 시스템 ID로 식별할 수 있어요.

프로그래밍 방식으로 러너 만들기

POST /user/runners REST API를 사용해 인증된 사용자로 러너를 만들 수 있어요. 이는 러너 구성이 동적이거나 재사용할 수 없는 경우에만 사용해야 해요. 러너 구성이 정적이면 기존 러너의 러너 인증 토큰을 재사용해야 해요.

러너 생성과 등록을 자동화하는 방법은 러너 생성과 등록 자동화 튜토리얼을 참고해요.

Helm 차트로 GitLab Runner 설치하기

러너 등록 토큰이 비활성화되면 여러 러너 구성 옵션을 러너 등록 중에 설정할 수 없어요. 이 옵션들은 다음에서만 구성할 수 있어요.

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

다음 구성 옵션은 그 시나리오에서 [values.yaml](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/blob/main/values.yaml)에서 지원되지 않아요.

## If a runner authentication token is specified in runnerRegistrationToken, the registration will succeed, however the
## other values will be ignored.
runnerRegistrationToken: ""
locked: true
tags: ""
maximumTimeout: ""
runUntagged: true
protected: true

Kubernetes의 GitLab Runner에서 Helm 배포는 러너 인증 토큰을 러너 워커 포드에 전달하고 러너 구성을 만들어요. GitLab 17.0 이상에서 GitLab.com에 연결된 Kubernetes 호스팅 러너에 runnerRegistrationToken 토큰 필드를 사용하면 러너 워커 포드가 생성 중에 레거시 Registration 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: "" # need to leave as an empty string for compatibility reasons
  runner-token: "REDACTED"

시크릿 관리 솔루션이 runner-registration-token에 빈 문자열을 설정하지 못하게 한다면 아무 문자열로 설정할 수 있어요. runner-token이 있으면 이 값은 무시돼요.

알려진 문제

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

새 등록 워크플로로 Helm 차트에 러너를 등록하면 러너 세부 정보 페이지에 포드 이름이 나타나지 않아요. 자세한 내용은 issue 423523을 참고해요.

러너 인증 토큰이 교체(rotation)될 때 업데이트되지 않음

여러 러너 매니저에 등록된 같은 러너의 토큰 교체

자동 토큰 교체와 함께 새 워크플로를 통해 여러 호스트 머신에 러너를 등록하면, 첫 번째 러너 매니저만 새 토큰을 받아요. 나머지 러너 매니저는 무효한 토큰을 계속 사용하다가 연결이 끊겨요. 이 매니저들을 새 토큰을 사용하도록 수동으로 업데이트해야 해요.

GitLab Operator의 토큰 교체

새 워크플로를 통한 GitLab Operator 러너 등록 중에 Custom Resource Definition의 러너 인증 토큰이 토큰 교체 중에 업데이트되지 않아요. 이것은 다음 경우에 발생해요.

• Custom Resource Definition이 참조하는 시크릿에서 glrt- 접두사의 러너 인증 토큰을 사용 중.
• 러너 인증 토큰이 만료될 예정인 경우.

러너 인증 토큰 만료에 대한 자세한 내용은 인증 토큰 보안을 참고해요.

자세한 내용은 issue 186을 참고해요.

더 알아보기

러너의 범위(프로젝트/그룹/인스턴스)와 만드는 방법은 러너 문서에서, 러너 생성과 등록을 완전히 자동화하는 방법은 러너 생성과 등록 자동화 튜토리얼을 함께 읽어보는 걸 추천해요.