자습서: 러너 생성 및 등록 자동화
이 자습서에서는 러너 생성 및 등록을 자동화하는 방법에 대해 설명합니다.
러너 생성 및 등록을 자동화하려면:
이 자습서의 지침은 러너 인증 토큰을 사용하여 러너 생성 및 등록하는 방법을 설명하며, 이는 더 이상 사용되지 않는 등록 토큰을 대체합니다. 자세한 정보는 새 러너 등록 워크플로우를 참조하십시오.
시작하기 전에
- GitLab 러너는 GitLab 인스턴스에 설치되어 있어야 합니다.
- 인스턴스 러너를 만들려면 관리자여야 합니다.
- 그룹 러너를 만들려면 관리자이거나 그룹의 소유자 역할이어야 합니다.
- 프로젝트 러너를 만들려면 관리자이거나 프로젝트의 유지자 역할이어야 합니다.
액세스 토큰 생성
액세스 토큰을 만들어 REST API를 사용하여 러너를 만들 수 있습니다.
다음과 같이 생성할 수 있습니다:
- 공유, 그룹 및 프로젝트 러너에 사용할 개인 액세스 토큰.
- 그룹 및 프로젝트 러너에 사용할 그룹 또는 프로젝트 액세스 토큰.
액세스 토큰은 GitLab UI에서 한 번만 표시됩니다. 페이지를 떠나면 토큰에 더 이상 액세스할 수 없습니다. 토큰을 저장하려면 HashiCorp Vault나 Keeper Secrets Manager Terraform 플러그인과 같은 비밀 관리 솔루션을 사용해야 합니다.
개인 액세스 토큰 생성
- 왼쪽 사이드바에서 아바타를 선택합니다.
- 프로필 편집을 선택합니다.
- 왼쪽 사이드바에서 액세스 토큰을 선택합니다.
- 새 토큰 추가를 선택합니다.
- 토큰의 이름과 만료 날짜를 입력합니다.
- 토큰은 해당 날짜에 UTC 자정에 만료됩니다.
- 만료 날짜를 입력하지 않으면 자동으로 현재 날짜로부터 365일 후로 설정됩니다.
- 기본적으로 이 날짜는 현재 날짜로부터 최대 365일 후까지 설정할 수 있습니다.
- 선택한 범위 섹션에서 create_runner 확인란을 선택합니다.
- 개인 액세스 토큰 생성을 선택합니다.
프로젝트 또는 그룹 액세스 토큰 생성
프로젝트 액세스 토큰을 생성하려면:
- 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트 또는 그룹을 찾습니다.
- 설정 > 액세스 토큰을 선택합니다.
- 새 토큰 추가를 선택합니다.
- 이름을 입력합니다. 해당 토큰 이름은 그룹이나 프로젝트를 볼 수 있는 권한이 있는 모든 사용자에게 표시됩니다.
- 토큰의 만료 날짜를 입력합니다.
- 토큰은 해당 날짜에 UTC 자정에 만료됩니다.
- 만료 날짜를 입력하지 않으면 자동으로 현재 날짜로부터 365일 후로 설정됩니다.
- 기본적으로 이 날짜는 현재 날짜로부터 최대 365일 후까지 설정될 수 있습니다.
- Self-Managed형 인스턴스에서는 액세스 토큰 수명 제한 설정이 최대 허용 가능한 수명을 제한할 수 있습니다.
-
역할 선택 드롭다운 디렉터리에서:
- 프로젝트 액세스 토큰의 경우 Maintainer를 선택합니다.
- 그룹 액세스 토큰의 경우 Owner를 선택합니다.
- 범위 선택 섹션에서 create_runner 확인란을 선택합니다.
- 프로젝트 액세스 토큰 생성을 선택합니다.
러너 구성 생성
러너 구성은 러너를 요구 사항에 맞게 구성하는 곳입니다.
러너 구성을 만든 후에는 러너 인증을 받아 러너를 등록할 수 있습니다. 동일한 러너 인증 토큰으로 여러 개의 러너를 동일한 구성에 등록할 수 있습니다. 러너 구성은 config.toml
파일에 저장됩니다.
러너 구성을 만들기 위해 다음을 사용할 수 있습니다:
- GitLab REST API.
-
gitlab_user_runner
Terraform 리소스.
GitLab REST API를 사용하여
시작하기 전에 다음이 필요합니다:
- GitLab 인스턴스의 URL. 예를 들어, 프로젝트가
gitlab.example.com/yourname/yourproject
에 호스팅된 경우, GitLab 인스턴스 URL은https://gitlab.example.com
입니다. - 그룹 또는 프로젝트의 ID 번호(그룹 또는 프로젝트 개요 페이지에서 프로젝트 또는 그룹 이름 아래에 표시됨)는 그룹 또는 프로젝트 러너에 필요합니다.
러너를 만들기 위해 POST /user/runners
REST 엔드포인트에서 액세스 토큰을 사용합니다:
-
curl
을 사용하여 러너를 만들기 위해 엔드포인트를 호출합니다:프로젝트curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners" --data "runner_type=project_type" --data "project_id=<project_id>" --data "description=<your_runner_description>" --data "tag_list=<your_comma_separated_job_tags>" --header "PRIVATE-TOKEN: <project_access_token>"
그룹curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners" --data "runner_type=group_type" --data "group_id=<group_id>" --data "description=<your_runner_description>" --data "tag_list=<your_comma_separated_job_tags>" --header "PRIVATE-TOKEN: <group_access_token>"
공유curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners" --data "runner_type=instance_type" --data "description=<your_runner_description>" --data "tag_list=<your_comma_separated_job_tags>" --header "PRIVATE-TOKEN: <personal_access_token>"
-
반환된
token
값을 안전한 위치나 비밀 관리 솔루션에 저장합니다.token
값은 API 응답에서 한 번만 반환됩니다.
gitlab_user_runner
Terraform 리소스 사용하여
Terraform을 사용하여 러너 구성을 만들려면 GitLab Terraform provider의 gitlab_user_runner
Terraform 리소스를 사용합니다.
다음은 예제 구성 블록입니다:
resource "gitlab_user_runner" "example_runner" {
runner_type = "instance_type"
description = "my-runner"
tag_list = ["shell", "docker"]
}
러너 설치 및 등록 자동화
공용 클라우드의 가상 머신 인스턴스에 러너를 호스트하는 경우, 러너 설치와 등록을 자동화할 수 있습니다.
러너와 해당 구성을 만든 후, 동일한 러너 인증 토큰을 사용하여 동일한 구성에 여러 러너를 등록할 수 있습니다. 예를 들어, 동일한 러너 인증 토큰으로 동일한 실행자 유형과 작업 태그를 가진 여러 개의 인스턴스 러너를 대상 컴퓨팅 호스트에 배포할 수 있습니다. 동일한 러너 인증 토큰으로 등록된 각 러너는 GitLab Runner에 의해 무작위로 생성되어 로컬 파일 시스템에 저장되는 고유한 system_id
를 가지게 됩니다.
다음은 등록 및 배포를 위해 사용할 수 있는 자동화 작업 흐름의 예시입니다.
- 인프라 구조로 Terraform을 사용하여 Google Cloud Platform (GCP)에 호스팅된 가상 머신에 러너 애플리케이션을 설치합니다.
-
GCP Terraform provider에서
metadata
키를 사용하여 러너 인증 토큰을 GCP 가상 머신의 러너 구성 파일에 추가합니다. -
대상 GitLab 인스턴스에 러너를 등록하려면 GCP Terraform provider에서 생성된
cloud-init
스크립트를 사용합니다. 다음은 예시입니다:#!/bin/bash apt update curl --location "https://packages.gitlab.com/install/repositories/runner/ gitlab-runner/script.deb.sh" | bash GL_NAME=$(curl 169.254.169.254/computeMetadata/v1/instance/name --header "Metadata-Flavor:Google") GL_EXECUTOR=$(curl 169.254.169.254/computeMetadata/v1/instance/attributes/ gl_executor --header "Metadata-Flavor:Google") apt update apt install -y gitlab-runner gitlab-runner register --non-interactive --name="$GL_NAME" --url="https://gitlab.com" --token="$RUNNER_TOKEN" --request-concurrency="12" --executor="$GL_EXECUTOR" --docker-image="alpine:latest" systemctl restart gitlab-runner
동일한 구성을 사용하는 러너 보기
러너(runner) 생성과 자동화를 완료했으므로 이제 GitLab UI에서 동일한 구성을 사용하는 러너를 볼 수 있습니다.
- 왼쪽 사이드바에서 맨 아래에서 관리 영역(Admin Area)을 선택합니다.
- CI/CD > 러너를 선택합니다.
- 검색 상자에 러너 설명을 입력하거나 러너 디렉터리을 검색합니다.
- 동일한 구성을 사용하는 러너를 보려면 세부정보(Details) 탭에서 러너(Runners) 옆의 세부정보 표시(Show details)를 선택합니다.