GitLab Runnerインフラストラクチャツールキット

GitLab Runner Infrastructure Toolkit（GRIT）は、パブリッククラウドプロバイダー上で多くの一般的なRunnerの設定を作成および管理するために使用できる、Terraformモジュールのライブラリです。

GRITでRunnerを作成する

GRITを使用して、AWSでオートスケールLinux Dockerをデプロイするには、次の手順を実行します:

1. GitLabおよびAWSへのアクセスを提供するには、次の変数を設定します:

   • GITLAB_TOKEN
   • AWS_REGION
   • AWS_SECRET_ACCESS_KEY
   • AWS_ACCESS_KEY_ID

2. 最新のGRITリリースをダウンロードし、.local/gritに展開します。

3. main.tfTerraformモジュールを作成します:

   module "runner" {
     source = ".local/grit/scenarios/aws/linux/docker-autoscaler-default"
   
     name               = "grit-runner"
     gitlab_project_id  = "39258790" # gitlab.com/josephburnett/hello-runner
     runner_description = "Autoscaling Linux Docker runner on AWS deployed with GRIT. "
     runner_tags        = ["aws", "linux"]
     max_instances      = 5
     min_support        = "experimental"
   }

4. モジュールを初期化して適用します:

   terraform init
   terraform apply

これらの手順では、GitLabプロジェクトに新しいRunnerを作成します。Runnerマネージャーは、docker-autoscaler executorを使用して、awsおよびlinuxとしてタグ付けされたジョブを実行します。Runnerは、ワークロードに基づいて、新しいオートスケールグループ（ASG）を介して1～5個のVMをプロビジョニングします。ASGは、Runnerチームが所有するパブリックAMIを使用します。RunnerマネージャーとASGはどちらも、新しいVPCで動作します。すべてのリソースは、指定された値（grit-runner）に基づいて命名されます。これにより、単一のAWSプロジェクト内で、異なる名前を持つこのモジュールの複数のインスタンスを作成できます。

サポートレベルとmin_supportパラメータ

すべてのGRITモジュールにmin_support値を指定する必要があります。このパラメータは、オペレーターがデプロイに必要な最小サポートレベルを指定します。GRITモジュールは、none、experimental、beta、またはGAのサポート指定に関連付けられています。目標は、すべてのモジュールがGAステータスに到達することです。

noneは特殊なケースです。主にテストや開発用途を想定したモジュールであり、サポートの保証はありません。

experimental、beta、およびgaのモジュールは、GitLabの開発ステージの定義に準拠しています。

責任共有モデル

GRITは、作成者（モジュールのデベロッパー）とオペレーター（GRITでデプロイするユーザー）間の責任共有モデルに基づいて動作します。各ロールの具体的な責任とサポートレベルの決定方法について詳しくは、GORPドキュメントの「責任の共有」セクションをご覧ください。

Runnerの状態を管理する

Runnerを維持するには、次の手順を実行します:

1. GitLabプロジェクトにモジュールをチェックインします。

2. Terraformの状態をGitLab Terraformのbackend.tfに保存します:

   terraform {
     backend "http" {}
   }

3. .gitlab-ci.ymlを使用して変更を適用します:

   terraform-apply:
     variables:
       TF_HTTP_LOCK_ADDRESS: "https://gitlab.com/api/v4/projects/${CI_PROJECT_ID}/terraform/state/${NAME}/lock"
       TF_HTTP_UNLOCK_ADDRESS: ${TF_HTTP_LOCK_ADDRESS}
       TF_HTTP_USERNAME: ${GITLAB_USER_LOGIN}
       TF_HTTP_PASSWORD: ${GITLAB_TOKEN}
       TF_HTTP_LOCK_METHOD: POST
       TF_HTTP_UNLOCK_METHOD: DELETE
     script:
       - terraform init
       - terraform apply -auto-approve

Runnerを削除する

Runnerとそのインフラストラクチャを削除するには、次の手順を実行します:

terraform destroy

サポートされている設定

高度な設定

トップレベルモジュール

プロバイダー内のトップレベルモジュールは、Runnerの設定のうち、強く分離された構成要素や任意の設定項目を表します。たとえば、fleetingとrunnerは、アクセス認証情報とインスタンスグループ名のみを共有するため、別個のモジュールです。vpcも、一部のユーザーが独自のVPCを提供するため、別個のモジュールです。既存のVPCを利用しているユーザーは、他のGRITモジュールと連携するために、対応する入力構造を作成するだけで済みます。

たとえば、トップレベルのVPCモジュールを使用して、VPCを必要とするモジュールのVPCを作成できます:

module "runner" {
   source = ".local/grit/modules/aws/runner"

   vpc = {
      id         = module.vpc.id
      subnet_ids = module.vpc.subnet_ids
   }

   # ...additional config omitted
}

module "vpc" {
   source   = ".local/grit/modules/aws/vpc"

   zone = "us-east-1b"

   cidr        = "10.0.0.0/16"
   subnet_cidr = "10.0.0.0/24"
}

ユーザーは独自のVPCを指定することもでき、その場合はGRITのVPCモジュールを使用する必要はありません:

module "runner" {
   source = ".local/grit/modules/aws/runner"

   vpc = {
      id         = PREEXISTING_VPC_ID
      subnet_ids = [PREEXISTING_SUBNET_ID]
   }

   # ...additional config omitted
}

GRITへのコントリビュート

GRITでは、コミュニティコントリビュートを歓迎しています。コントリビュートを行う前に、以下の資料をご確認ください:

開発者起源証明書およびライセンス

GRITへのすべてのコントリビューションは、開発者起源証明書およびライセンスに従うものとします。コントリビュートすることにより、現在および将来のGitLab, Inc. に提出されたコントリビューションに対するこれらの利用規約に同意したものとみなされます。

行動規範

GRITは、コントリビューター規約から採用されたGitLabの行動規範に従います。本プロジェクトは、参加者の背景やアイデンティティにかかわらず、すべての人が安心して参加できる、ハラスメントのない環境づくりに取り組んでいます。

コントリビューションのガイドライン

GRITにコントリビュートする場合は、次のガイドラインに従ってください:

• 全体的なアーキテクチャ設計については、GORPガイドラインを確認してください。
• Terraformを使用するためのGoogleのベストプラクティスに従ってください。
• 複雑さや重複を減らすため、再利用可能なモジュールアプローチに従ってください。
• コントリビューションに適切なGoテストを含めてください。

テストとLint

GRITは、品質を確保するために、いくつかのテストツールとLintツールを使用しています:

• インテグレーションテスト: Terraformプランを検証するために、Terratestを使用します。
• E2Eテスト: e2eディレクトリで利用できます。
• Terraform Lint: tflint、terraform fmt、およびterraform validateを使用します。
• Go Lint: Goコード（主にテスト）には、golangci-lintを使用します。
• ドキュメント: GitLabドキュメントのスタイルガイドラインに従い、valeとmarkdownlintを使用します。

開発環境のセットアップ、テストの実行、Lintの詳細な手順については、CONTRIBUTING.mdを参照してください。

GRITのユーザー

GRITは、GitLabエコシステム内のさまざまなチームやサービスで採用されています:

• GitLab Dedicated: GitLab DedicatedのホストされたRunnerは、GRITを使用してRunnerインフラストラクチャをプロビジョニングおよび管理します。
• GitLab Self-Managed: GRITは、多くのGitLab Self-Managedユーザーから高い要望を受けています。すでに一部の組織では、Runnerのデプロイを標準化された方法で管理するために、GRITの導入を開始しています。

組織でGRITを使用していて、このセクションで紹介したい場合は、マージリクエストを開いてください。