インスタンスexecutor

インスタンスexecutorは、オートスケールが有効なexecutorで、Runnerマネージャーが処理するジョブの予想される量に対応するために、オンデマンドでインスタンスを作成します。

ジョブがホストインスタンス、オペレーティングシステム、および接続されたデバイスへのフルアクセスを必要とする場合、インスタンスexecutorを使用できます。インスタンスexecutorは、さまざまなレベルの分離とセキュリティを備えたシングルテナントおよびマルチテナントのジョブに対応するように設定することもできます。

ネストされた仮想化

インスタンスexecutorは、GitLabが開発したネストされたデーモンによるネストされた仮想化をサポートします。ネストされたデーモンは、ジョブのような分離された短期間のワークロードに使用されるホストシステム上で、事前設定された仮想マシンの作成と削除を可能にします。ネストはApple Siliconインスタンスでのみサポートされています。

オートスケールのために環境を準備する

オートスケールのために環境を準備するには:

Fleetingプラグインをインストールして、Runnerマネージャーがインストールされ、設定されているターゲットプラットフォームで利用できるようにします。
使用しているプラットフォーム用のVMイメージを作成します。イメージには以下を含める必要があります:
- Git
- Runnerバイナリ
  ジョブアーティファクトキャッシュを処理するには、Runnerバイナリを仮想マシンにインストールし、Runner実行可能ファイルをデフォルトのパスに保持します。VMイメージはRunnerの実行を必要としません。VMイメージを使用して起動されたインスタンスを、GitLabにRunnerとして登録しないようにしてください。
- 実行する予定のジョブに必要な依存関係

executorをオートスケールするように設定する

前提条件:

管理者である必要があります。

インスタンスexecutorをオートスケールのために設定するには、config.tomlで次のセクションを更新します:

プリエンプティブモード

fleetingとtaskscalerを使用すると:

オンにすると、Runnerマネージャーはアイドルインスタンスが利用可能になるまで新しいCI/CDジョブをリクエストしません。このモードでは、CI/CDジョブはほぼ即座に実行されます。
プリエンプティブモードがオフの場合、Runnerマネージャーは、アイドルインスタンスがこれらのジョブを実行できるかどうかに関わらず、新しいCI/CDジョブをリクエストします。ジョブの数はmax_instancesとcapacity_per_instanceに基づいています。このモードでは、CI/CDジョブの開始時間が遅くなります。新しいインスタンスをプロビジョニングすることができず、CI/CDジョブが実行されない可能性があります。

AWSオートスケールグループの設定例

1インスタンスあたり1ジョブ

前提条件:

少なくともgitとRunnerがインストールされたAMI。
AWS Auto Scalingグループ。スケールポリシーにはnoneを使用します。Runnerがスケーリングを処理します。
IAMポリシーと適切な権限。

この設定では以下がサポートされています:

各インスタンスの容量は1です。
使用回数は1です。
アイドルスケールは5です。
アイドル時間は20分です。
最大インスタンス数は10です。

容量と使用回数を1に設定すると、各ジョブには他のジョブの影響を受けない安全な一時的なインスタンスが与えられます。ジョブが完了すると、実行されたインスタンスはすぐに削除されます。

各インスタンスの容量が1で、アイドルスケールが5の場合、Runnerは将来の需要に備えて5つのインスタンス全体を保持します。これらのインスタンスは少なくとも20分間維持されます。

Runnerのconcurrentフィールドは10に設定されています（最大インスタンス数 * 1インスタンスあたりの容量）。

concurrent = 10

[[runners]]
  name = "instance autoscaler example"
  url = "https://gitlab.com"
  token = "<token>"
  shell = "sh"

  executor = "instance"

  # Autoscaler config
  [runners.autoscaler]
    plugin = "aws" # in GitLab 16.11 and later, ensure you run `gitlab-runner fleeting install` to automatically install the plugin

    # in GitLab 16.10 and earlier, manually install the plugin and use:
    # plugin = "fleeting-plugin-aws"

    capacity_per_instance = 1
    max_use_count = 1
    max_instances = 10

    [runners.autoscaler.plugin_config] # plugin specific configuration (see plugin documentation)
      name             = "my-linux-asg"                # AWS Autoscaling Group name
      profile          = "default"                     # optional, default is 'default'
      config_file      = "/home/user/.aws/config"      # optional, default is '~/.aws/config'
      credentials_file = "/home/user/.aws/credentials" # optional, default is '~/.aws/credentials'

    [runners.autoscaler.connector_config]
      username          = "ec2-user"
      use_external_addr = true

    [[runners.autoscaler.policy]]
      idle_count = 5
      idle_time = "20m0s"

無制限の使用回数で1インスタンスあたり5つのジョブ

前提条件:

少なくともgitとRunnerがインストールされたAMI。
AWSオートスケールグループのスケールポリシーはnoneに設定されています。Runnerがスケーリングを処理します。
IAMポリシーと適切な権限。

この設定では以下がサポートされています:

各インスタンスの容量は5です。
無制限の使用回数。
アイドルスケールは5です。
アイドル時間は20分です。
最大インスタンス数は10です。

1インスタンスあたりの容量を5に設定し、使用回数を無制限にすると、各インスタンスはインスタンスのライフタイム全体で5つのジョブを同時に実行します。

アイドルスケールが5で、インスタンスのアイドル容量が5の場合、使用中の容量が5を下回るたびに1つのアイドルインスタンスが作成されます。アイドルインスタンスは少なくとも20分間維持されます。

これらの環境で実行されるジョブは、それらの間にほとんど分離がなく、各ジョブが他のジョブのパフォーマンスに影響を与える可能性があるため、信頼できるものである必要があります。

Runnerのconcurrentフィールドは50に設定されています（最大インスタンス数 * 1インスタンスあたりの容量）。

concurrent = 50

[[runners]]
  name = "instance autoscaler example"
  url = "https://gitlab.com"
  token = "<token>"
  shell = "sh"

  executor = "instance"

  # Autoscaler config
  [runners.autoscaler]
    plugin = "aws" # in GitLab 16.11 and later, ensure you run `gitlab-runner fleeting install` to automatically install the plugin

    # in GitLab 16.10 and earlier, manually install the plugin and use:
    # plugin = "fleeting-plugin-aws"

    capacity_per_instance = 5
    max_use_count = 0
    max_instances = 10

    [runners.autoscaler.plugin_config] # plugin specific configuration (see plugin documentation)
      name             = "my-windows-asg"              # AWS Autoscaling Group name
      profile          = "default"                     # optional, default is 'default'
      config_file      = "/home/user/.aws/config"      # optional, default is '~/.aws/config'
      credentials_file = "/home/user/.aws/credentials" # optional, default is '~/.aws/credentials'

    [runners.autoscaler.connector_config]
      username          = "Administrator"
      timeout           = "5m0s"
      use_external_addr = true

    [[runners.autoscaler.policy]]
      idle_count = 5
      idle_time = "20m0s"

1インスタンスあたり2ジョブ、無制限の使用、EC2 Macインスタンスでのネストされた仮想化

前提条件:

ネストとTartがインストールされたApple Silicon AMI。
Runnerが使用するTart VMイメージ。VMイメージは、ジョブのimageキーワードで指定されます。VMイメージには、少なくともgitとRunnerがインストールされている必要があります。
AWS Auto Scalingグループ。スケールポリシーにはnoneを使用します。これはRunnerがスケールを処理するためです。MacOS用のASGを設定する方法については、EC2 Macインスタンス向けオートスケールの実装を参照してください。
適切な権限が設定されたIAMポリシー。

この設定では以下がサポートされています:

各インスタンスの容量は2です。
無制限の使用回数。
分離されたジョブをサポートするためのネストされた仮想化。ネストされた仮想化は、ネストがインストールされたApple Siliconインスタンスでのみ利用可能です。
アイドルスケールは5です。
アイドル時間は20分です。
最大インスタンス数は10です。

各インスタンスの容量が2で、使用回数が無制限の場合、各インスタンスはインスタンスのライフタイム全体で2つのジョブを同時に実行します。

アイドルスケールが2の場合、使用中の容量が2を下回るたびに1つのアイドルインスタンスが作成されます。アイドルインスタンスは少なくとも24時間維持されます。この期間は、AWS MacOSインスタンスホストの24時間最小割り当て期間によるものです。

この環境で実行されるジョブは、各ジョブのネストされた仮想化にネストが使用されているため、信頼する必要はありません。これはApple siliconインスタンスでのみ機能します。

Runnerのconcurrentフィールドは8に設定されています（最大インスタンス数 * 1インスタンスあたりの容量）。

concurrent = 8

[[runners]]
  name = "macos applesilicon autoscaler example"
  url = "https://gitlab.com"
  token = "<token>"
  executor = "instance"

  [runners.instance]
    allowed_images = ["*"] # allow any nesting image

  [runners.autoscaler]
    capacity_per_instance = 2 # AppleSilicon can only support 2 VMs per host
    max_use_count = 0
    max_instances = 4

    plugin = "aws" # in GitLab 16.11 and later, ensure you run `gitlab-runner fleeting install` to automatically install the plugin

    # in GitLab 16.10 and earlier, manually install the plugin and use:
    # plugin = "fleeting-plugin-aws"

    [[runners.autoscaler.policy]]
      idle_count = 2
      idle_time  = "24h" # AWS's MacOS instances

    [runners.autoscaler.connector_config]
      username = "ec2-user"
      key_path = "macos-key.pem"
      timeout  = "1h" # connecting to a MacOS instance can take some time, as they can be slow to provision

    [runners.autoscaler.plugin_config]
      name = "mac2metal"
      region = "us-west-2"

    [runners.autoscaler.vm_isolation]
      enabled = true
      nesting_host = "unix:///Users/ec2-user/Library/Application Support/nesting.sock"

    [runners.autoscaler.vm_isolation.connector_config]
      username = "nested-vm-username"
      password = "nested-vm-password"
      timeout  = "20m"

Google Cloudインスタンスグループの設定例

Google Cloudインスタンスグループを使用した1インスタンスあたり1ジョブ

前提条件:

少なくともgitとRunnerがインストールされたカスタムイメージ。
オートスケールモードがdo not autoscaleに設定されているGoogle Cloudインスタンスグループ。Runnerがスケーリングを処理します。
適切な権限が設定されたIAMポリシー。GKEクラスターにRunnerをデプロイする場合は、KubernetesサービスアカウントとGCPサービスアカウントの間にIAMバインディングを追加できます。credentials_fileでキーファイルを使用する代わりに、iam.workloadIdentityUserロールでこのバインディングを追加し、GCPに対して認証できます。

この設定では以下がサポートされています:

インスタンスあたりのキャパシティ: 1
使用回数: 1
アイドルスケール: 5
アイドル時間: 20分
インスタンスの最大数: 10

キャパシティと使用回数が両方とも1に設定されている場合、各ジョブに、他のジョブの影響を受けない安全な一時インスタンスが与えられます。ジョブが完了すると、ジョブが実行されたインスタンスが直ちに削除されます。

アイドルスケールが5に設定されている場合、Runnerは将来の需要に備えて5つのインスタンスを維持します（インスタンスあたりのキャパシティが1であるため）。これらのインスタンスは少なくとも20分間維持されます。

Runnerのconcurrentフィールドは10（インスタンスの最大数*インスタンスあたりのキャパシティ）に設定されます。

concurrent = 10

[[runners]]
  name = "instance autoscaler example"
  url = "https://gitlab.com"
  token = "<token>"
  shell = "sh"

  executor = "instance"

  # Autoscaler config
  [runners.autoscaler]
    plugin = "googlecloud" # for >= 16.11, ensure you run `gitlab-runner fleeting install` to automatically install the plugin

    # for versions < 17.0, manually install the plugin and use:
    # plugin = "fleeting-plugin-googlecompute"

    capacity_per_instance = 1
    max_use_count = 1
    max_instances = 10

    [runners.autoscaler.plugin_config] # plugin specific configuration (see plugin documentation)
      name             = "my-linux-instance-group" # Google Cloud Instance Group name
      project          = "my-gcp-project"
      zone             = "europe-west1-c"
      credentials_file = "/home/user/.config/gcloud/application_default_credentials.json" # optional, default is '~/.config/gcloud/application_default_credentials.json'

    [runners.autoscaler.connector_config]
      username          = "runner"
      use_external_addr = true

    [[runners.autoscaler.policy]]
      idle_count = 5
      idle_time = "20m0s"

Google Cloudインスタンスグループを使用した、1インスタンスあたり5ジョブ、無制限の使用

前提条件:

少なくともgitとRunnerがインストールされたカスタムイメージ。
インスタンスグループ。「オートスケールモード」には「オートスケールしない」を選択してください。これはRunnerがスケールを処理するためです。
IAMポリシーと適切な権限。

この設定では以下がサポートされています:

1インスタンスあたりの容量は5です。
無制限の使用回数
アイドルスケール: 5
アイドル時間: 20分
インスタンスの最大数: 10

容量を5に設定し、使用回数を無制限にすると、各インスタンスはインスタンスのライフタイム全体で5つのジョブを同時に実行します。

アイドルスケールが5の場合、使用中の容量が5を下回るたびに1つのアイドルインスタンスが作成されます。アイドルインスタンスは少なくとも20分間維持されます。

Runnerのconcurrentフィールドは50に設定されています（最大インスタンス数 * 1インスタンスあたりの容量）。

concurrent = 50

[[runners]]
  name = "instance autoscaler example"
  url = "https://gitlab.com"
  token = "<token>"
  shell = "sh"

  executor = "instance"

  # Autoscaler config
  [runners.autoscaler]
    plugin = "googlecloud" # for >= 16.11, ensure you run `gitlab-runner fleeting install` to automatically install the plugin

    # for versions < 17.0, manually install the plugin and use:
    # plugin = "fleeting-plugin-googlecompute"

    capacity_per_instance = 5
    max_use_count = 0
    max_instances = 10

    [runners.autoscaler.plugin_config] # plugin specific configuration (see plugin documentation)
      name             = "my-windows-instance-group" # Google Cloud Instance Group name
      project          = "my-gcp-project"
      zone             = "europe-west1-c"
      credentials_file = "/home/user/.config/gcloud/application_default_credentials.json" # optional, default is '~/.config/gcloud/application_default_credentials.json'

    [runners.autoscaler.connector_config]
      username          = "Administrator"
      timeout           = "5m0s"
      use_external_addr = true

    [[runners.autoscaler.policy]]
      idle_count = 5
      idle_time = "20m0s"

Azureスケールセットの設定例

Azureスケールセットを使用した1インスタンスあたり1ジョブ

前提条件:

少なくともgitとRunnerがインストールされたカスタムイメージ。
オートスケールモードがmanualに設定されており、オーバープロビジョニングがオフになっているAzureスケールセット。Runnerがスケーリングを処理します。

この設定では以下がサポートされています:

インスタンスあたりのキャパシティ: 1
使用回数: 1
アイドルスケール: 5
アイドル時間: 20分
インスタンスの最大数: 10

Runnerのconcurrentフィールドは10（インスタンスの最大数*インスタンスあたりのキャパシティ）に設定されます。

concurrent = 10

[[runners]]
  name = "instance autoscaler example"
  url = "https://gitlab.com"
  token = "<token>"
  shell = "sh"

  executor = "instance"

  # Autoscaler config
  [runners.autoscaler]
    plugin = "azure" # for >= 16.11, ensure you run `gitlab-runner fleeting install` to automatically install the plugin

    # for versions < 17.0, manually install the plugin and use:
    # plugin = "fleeting-plugin-azure"

    capacity_per_instance = 1
    max_use_count = 1
    max_instances = 10

    [runners.autoscaler.plugin_config] # plugin specific configuration (see plugin documentation)
      name                = "my-linux-scale-set" # Azure scale set name
      subscription_id     = "9b3c4602-cde2-4089-bed8-889e5a3e7102"
      resource_group_name = "my-resource-group"

    [runners.autoscaler.connector_config]
      username               = "runner"
      password               = "my-scale-set-static-password"
      use_static_credentials = true
      timeout                = "10m"
      use_external_addr      = true

    [[runners.autoscaler.policy]]
      idle_count = 5
      idle_time  = "20m0s"

Azureスケールセットを使用した、1インスタンスあたり5ジョブ、無制限の使用

前提条件:

少なくともgitとRunnerがインストールされたカスタムイメージ。
オートスケールモードがmanualに設定されており、オーバープロビジョニングがオフになっているAzureスケールセット。Runnerがスケーリングを処理します。

この設定では以下がサポートされています:

1インスタンスあたりの容量は5です。
無制限の使用回数
アイドルスケール: 5
アイドル時間: 20分
インスタンスの最大数: 10

容量を5に設定し、使用回数を無制限にすると、各インスタンスはインスタンスのライフタイム全体で5つのジョブを同時に実行します。

アイドルスケールが2の場合、使用中の容量が5を下回るたびに1つのアイドルインスタンスが作成されます。アイドルインスタンスは少なくとも20分間維持されます。

Runnerのconcurrentフィールドは50に設定されています（最大インスタンス数 * 1インスタンスあたりの容量）。

concurrent = 50

[[runners]]
  name = "instance autoscaler example"
  url = "https://gitlab.com"
  token = "<token>"
  shell = "sh"

  executor = "instance"

  # Autoscaler config
  [runners.autoscaler]
    plugin = "azure" # for >= 16.11, ensure you run `gitlab-runner fleeting install` to automatically install the plugin

    # for versions < 17.0, manually install the plugin and use:
    # plugin = "fleeting-plugin-azure"

    capacity_per_instance = 5
    max_use_count = 0
    max_instances = 10

    [runners.autoscaler.plugin_config] # plugin specific configuration (see plugin documentation)
      name                = "my-windows-scale-set" # Azure scale set name
      subscription_id     = "9b3c4602-cde2-4089-bed8-889e5a3e7102"
      resource_group_name = "my-resource-group"

    [runners.autoscaler.connector_config]
      username               = "Administrator"
      password               = "my-scale-set-static-password"
      use_static_credentials = true
      timeout                = "10m"
      use_external_addr      = true

    [[runners.autoscaler.policy]]
      idle_count = 5
      idle_time = "20m0s"

スロットベースのcgroupのサポート

インスタンスexecutorは、同時実行ジョブ間のリソース分離を改善するために、スロットベースのcgroupをサポートしています。有効にすると、GITLAB_RUNNER_SLOT_CGROUP環境変数がジョブに自動的に提供され、スロット固有のcgroupでプロセスを実行できるようになります。

スロットベースのcgroupに関する詳細情報（利点、前提条件、設定、セットアップ手順を含む）については、スロットベースのcgroupサポートを参照してください。

Runnerスロットcgroup環境変数の使用

インスタンスexecutorは、GITLAB_RUNNER_SLOT_CGROUP環境変数をジョブに提供します。この変数をsystemd-runやcgexecのようなツールと組み合わせて使用し、スロット固有のcgroupでプロセスを実行します。

使用例とトラブルシューティングについては、スロットベースcgroupドキュメントのインスタンスexecutorセクションを参照してください。

トラブルシューティング

インスタンスexecutorを使用する際、次の問題が発生する可能性があります:

`sh: 1: eval: Running on ip-x.x.x.x via runner-host...n: not found`

このエラーは通常、準備ステップのevalコマンドが失敗したときに発生します。このエラーを解決するには、bash Shellに切り替えて、機能フラグ FF_USE_NEW_BASH_EVAL_STRATEGYを有効にします。