자습서: 러너 생성 및 등록 자동화

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

이 자습서에서는 러너 생성 및 등록을 자동화하는 방법에 대해 설명합니다.

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

  1. 개인 액세스 토큰 생성.
  2. 러너 구성 생성.
  3. GitLab 러너 설치 및 등록 자동화.
  4. 동일한 구성을 가진 러너 보기.
note
이 자습서의 지침은 러너 인증 토큰을 사용하여 러너 생성 및 등록하는 방법을 설명하며, 이는 등록 토큰을 사용하는 방법을 대체한 것입니다. 자세한 정보는 새로운 러너 등록 워크플로우를 참조하십시오.

시작하기 전에

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

액세스 토큰 생성

러너를 생성하기 위해 REST API를 사용할 수 있는 액세스 토큰을 생성하세요.

다음과 같은 액세스 토큰을 생성할 수 있습니다:

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

액세스 토큰은 GitLab UI에서 한 번만 표시됩니다. 페이지를 나가면 더 이상 토큰에 액세스할 수 없습니다. 토큰을 저장할 때는 HashiCorp Vault나 Keeper Secrets Manager Terraform 플러그인과 같은 보안 관리 솔루션을 사용해야 합니다.

개인 액세스 토큰 생성

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

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

caution
프로젝트 액세스 토큰은 내부 사용자로 취급됩니다. 내부 사용자가 프로젝트 액세스 토큰을 생성하면 해당 토큰은 내부로 설정된 모든 프로젝트에 액세스할 수 있습니다.

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

  1. 왼쪽 사이드바에서 검색 또는 이동하여 프로젝트 또는 그룹을 찾습니다.
  2. 설정 > 액세스 토큰을 선택합니다.
  3. 새 토큰 추가를 선택합니다.
  4. 이름을 입력합니다. 토큰 이름은 해당 그룹 또는 프로젝트를 볼 수 있는 권한을 가진 모든 사용자에게 표시됩니다.
  5. 토큰의 만료 날짜를 입력합니다.
    • 토큰은 해당 날짜에 UTC 자정에 만료됩니다.
    • 만료 날짜를 입력하지 않으면 자동으로 현재 날짜로부터 365일 후로 설정됩니다.
    • 기본적으로 이 날짜는 현재 날짜로부터 최대 365일 후까지 설정할 수 있습니다.
    • 인스턴스 전체에서 액세스 토큰의 최대 수명 제한 설정은 Self-managed 인스턴스에서 허용되는 최대 수명을 제한할 수 있습니다.
  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=<프로젝트_id>"
  --data "description=<러너_설명>"
  --data "tag_list=<쉼표로_구분된_작업_태그>"
  --header "PRIVATE-TOKEN: <프로젝트_액세스_토큰>"
    그룹
    curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners"
  --data "runner_type=group_type"
  --data "group_id=<그룹_id>"
  --data "description=<러너_설명>"
  --data "tag_list=<쉼표로_구분된_작업_태그>"
  --header "PRIVATE-TOKEN: <그룹_액세스_토큰>"
    공유
    curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners"
  --data "runner_type=instance_type"
  --data "description=<러너_설명>"
  --data "tag_list=<쉼표로_구분된_작업_태그>"
  --header "PRIVATE-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 러너에서 무작위로 생성되고 로컬 파일 시스템에 저장되는 고유한 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. 왼쪽 사이드바에서 하단에 관리 영역을 선택합니다.
  2. CI/CD > 러너를 선택합니다.
  3. 검색 상자에 러너 설명을 입력하거나 러너 디렉터리을 검색합니다.
  4. 동일한 구성을 사용하는 러너를 보려면 세부 정보 탭에서 러너 표시를 선택합니다.