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

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

러너 생성 및 등록 자동화를 위해 다음을 수행합니다.

  1. 개인 액세스 토큰 만들기.
  2. 러너 구성 만들기.
  3. GitLab 러너 설치 및 등록 자동화.
  4. 동일한 구성으로 러너 보기.

참고: 이 튜토리얼의 지침은 이전에 등록 토큰을 사용하던 방법을 대체한 러너 인증 토큰을 사용한 러너 생성 및 등록을 설명합니다. 자세한 내용은 새로운 러너 등록 워크플로우을 참조하십시오.

시작하기 전에

  • GitLab 러너가 GitLab 인스턴스에 설치되어 있어야 합니다.
  • 인스턴스 러너를 만들려면 관리자여야 합니다.
  • 그룹 러너를 만들려면 관리자이거나 그룹에 대한 소유자 역할이 있어야 합니다.
  • 프로젝트 러너를 만들려면 관리자이거나 프로젝트에 대한 Maintainer 역할이 있어야 합니다.

액세스 토큰 만들기

액세스 토큰을 만들어 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. 개인 액세스 토큰 생성을 선택합니다.

프로젝트 또는 그룹 액세스 토큰 만들기

경고: 프로젝트 액세스 토큰은 내부 사용자로 취급됩니다. 내부 사용자가 프로젝트 액세스 토큰을 만드는 경우 해당 토큰은 내부로 설정된 모든 프로젝트에 액세스할 수 있습니다.

프로젝트 액세스 토큰을 만들려면:

  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=<프로젝트_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. API 응답에서 반환된 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. 왼쪽 사이드바에서 맨 아래쪽에 있는 관리자를 선택합니다.
  2. CI/CD > 러너를 선택합니다.
  3. 검색 상자에 러너 설명을 입력하거나 러너 목록을 검색합니다.
  4. 동일한 구성을 사용하는 러너를 보려면 세부 정보 탭에서 러너 보기를 선택합니다.