튜토리얼: 러너 생성 및 등록 자동화

이 튜토리얼에서는 러너 생성 및 등록을 자동화하는 방법을 설명합니다.

러너 생성 및 등록을 자동화하려면:

  1. 개인 액세스 토큰 생성.
  2. 러너 구성 생성.
  3. GitLab Runner 설치 및 등록 자동화.
  4. 동일한 구성의 러너 보기.
note
이 튜토리얼의 지침은 더 이상 사용되지 않는 등록 토큰을 사용하는 등록 방법을 대체한 러너 인증 토큰으로 러너 생성 및 등록을 설명합니다. 추가 정보는
새로운 러너 등록 워크플로우를 참조하세요.

시작하기 전에

  • GitLab Runner는 GitLab 인스턴스에 설치되어 있어야 합니다.
  • 인스턴스 러너를 생성하려면 관리자인 권한이 필요합니다.
  • 그룹 러너를 생성하려면 관리자인 권한이 필요하거나 그룹의 소유자 역할이 필요합니다.
  • 프로젝트 러너를 생성하려면 관리자인 권한이 필요하거나 프로젝트의 유지 관리 역할이 필요합니다.

액세스 토큰 생성

REST API를 사용하여 러너를 생성할 수 있도록 액세스 토큰을 생성합니다.

다음 중 하나를 생성할 수 있습니다:

  • 공유, 그룹 및 프로젝트 러너와 함께 사용할 개인 액세스 토큰.
  • 그룹 및 프로젝트 러너와 함께 사용할 그룹 또는 프로젝트 액세스 토큰.

액세스 토큰은 GitLab UI에서 단 한 번만 볼 수 있습니다. 페이지를 떠나면 토큰에 대한 접근 권한이 더 이상 없습니다. HashiCorp Vault 또는 Keeper Secrets Manager Terraform 플러그인과 같은 비밀 관리 솔루션을 사용하여 토큰을 저장해야 합니다.

개인 액세스 토큰 생성

  1. 왼쪽 사이드바에서 아바타를 선택합니다.
  2. 프로필 편집을 선택합니다.
  3. 왼쪽 사이드바에서 액세스 토큰을 선택합니다.
  4. 새 토큰 추가를 선택합니다.
  5. 토큰의 이름과 만료 날짜를 입력합니다.
    • 토큰은 해당 날짜의 자정 UTC에 만료됩니다. 2024-01-01의 만료 날짜를 가진 토큰은 2024-01-01의 00:00:00 UTC에 만료됩니다.
    • 만료 날짜를 입력하지 않으면 만료 날짜가 현재 날짜보다 365일 뒤로 자동 설정됩니다.
    • 기본적으로 이 날짜는 현재 날짜보다 최대 365일이 될 수 있습니다.
  6. 범위 선택 섹션에서 create_runner 체크박스를 선택합니다.
  7. 개인 액세스 토큰 생성을 선택합니다.

프로젝트 또는 그룹 액세스 토큰 생성

caution
프로젝트 액세스 토큰은 내부 사용자로 처리됩니다. 내부 사용자가 프로젝트 액세스 토큰을 생성하면, 해당 토큰은 내부로 설정된 가시성 수준을 가진 모든 프로젝트에 접근할 수 있습니다.

프로젝트 액세스 토큰을 생성하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. 설정 > 액세스 토큰을 선택합니다.
  3. 새 토큰 추가를 선택합니다.
  4. 이름을 입력합니다. 토큰 이름은 그룹이나 프로젝트를 볼 수 있는 권한이 있는 모든 사용자에게 표시됩니다.
  5. 토큰의 만료 날짜를 입력합니다.
    • 토큰은 해당 날짜의 자정 UTC에 만료됩니다. 2024-01-01의 만료 날짜를 가진 토큰은 2024-01-01의 00:00:00 UTC에 만료됩니다.
    • 만료 날짜를 입력하지 않으면 만료 날짜가 현재 날짜보다 365일 뒤로 자동 설정됩니다.
    • 기본적으로 이 날짜는 현재 날짜보다 최대 365일이 될 수 있습니다.
    • 인스턴스 전역 최대 수명 설정은 자체 관리 인스턴스에서 허용 가능한 최대 수명을 제한할 수 있습니다.
  6. 역할 선택 드롭다운 목록에서:
    • 프로젝트 액세스 토큰의 경우 Maintainer를 선택합니다.
    • 그룹 액세스 토큰의 경우 Owner를 선택합니다.
  7. 범위 선택 섹션에서 create_runner 체크박스를 선택합니다.
  8. 프로젝트 액세스 토큰 생성을 선택합니다.

러너 구성 만들기

러너 구성은 요구에 맞게 러너를 구성하는 곳입니다.

러너 구성을 만든 후, 러너를 등록하기 위한 러너 인증을 받습니다.

하나 이상의 러너는 동일한 러너 인증 토큰으로 등록될 때 동일한 구성에 연결될 수 있습니다.

러너 구성은 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 번호입니다. ID 번호는 프로젝트 또는 그룹 개요 페이지에서 프로젝트 또는 그룹 이름 아래에 표시됩니다.

POST /user/runners REST 엔드포인트에서 액세스 토큰을 사용하여 러너를 만듭니다:

  1. 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>"

  2. 반환된 token 값을 안전한 위치나 비밀 관리 솔루션에 저장하십시오. token 값은 API 응답에서 한 번만 반환됩니다.

gitlab_user_runner Terraform 리소스로

Terraform을 사용하여 러너 구성을 만들려면, GitLab Terraform 제공자에서 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를 가집니다.

다음은 Google Compute Engine에 러너를 등록하고 배포하는 데 사용할 수 있는 자동화 워크플로의 예입니다:

  1. Terraform 코드 기반 인프라를 사용하여 Google Cloud Platform(GCP)에 호스팅된 가상 머신에 러너 애플리케이션을 설치합니다.

  2. GCP Terraform 제공자에서 metadata 키를 사용하여 GCP 가상 머신의 러너 구성 파일에 러너 인증 토큰을 추가합니다.

  3. 대상 GitLab 인스턴스에 러너를 등록하기 위해, GCP Terraform 제공자로부터 채워진 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

동일한 구성으로 실행기 보기

이제 실행기 생성 및 자동화가 완료되었으므로, GitLab UI에서 동일한 구성을 사용하는 실행기를 볼 수 있습니다.

  1. 왼쪽 사이드바에서 아래쪽에 있는 Admin을 선택합니다.

  2. CI/CD > Runners를 선택합니다.

  3. 검색 상자에 실행기 설명을 입력하거나 실행기 목록을 검색합니다.

  4. 동일한 구성을 사용하는 실행기를 보려면 Details 탭에서

    Runners 옆에 있는 Show details를 선택합니다.