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

スロットベースのcgroupサポートにより、オートスケールでGitLab Runnerを使用する際のリソースの分離と管理が向上します。スロットベースのcgroupは、オートスケーラーによって割り当てられたスロット番号に基づいて、ジョブを特定のコントロールグループ（cgroup）に自動的に割り当てます。

メリット

リソース分離の向上: 同じインスタンス上の同時実行ジョブ間のリソース干渉を防ぎます。
モニタリングの簡素化: スロットごとのリソース使用量を個別に追跡できます。
デバッグの改善: Cgroupベースのメトリクスは、リソースを大量に消費するジョブの特定に役立ちます。
きめ細かい制御: 予測可能なパフォーマンスのために、スロットごとにリソース制限を設定します。

サポートされているexecutor

スロットベースのcgroupは、スロット管理にtaskscalerを使用するオートスケールexecutorで動作します:

前提要件

cgroup v2をサポートするLinuxホスト
初期cgroup階層セットアップのためのルートアクセス
オートスケーラー機能を備えたGitLab Runner
スロット割り当て用のtaskscaler（オートスケーラーによって自動的に提供されます）

設定

スロットベースのcgroupサポートを有効にするには、以下をconfig.tomlに追加します。

`systemd` cgroupドライバーを使用するDockerの場合

Dockerがsystemd cgroupドライバー（最も一般的）を使用している場合は、systemdスライス形式を使用します:

[[runners]]
  name = "my-autoscaler-runner"
  executor = "docker-autoscaler"
  use_slot_cgroups = true
  slot_cgroup_template = "runner-slot-${slot}.slice"

  [runners.autoscaler]
    capacity_per_instance = 4

`cgroupfs`ドライバーを使用するDockerの場合

Dockerがcgroupfsドライバーを使用している場合は、raw cgroupパス形式を使用します:

[[runners]]
  name = "my-autoscaler-runner"
  executor = "docker-autoscaler"
  use_slot_cgroups = true
  slot_cgroup_template = "gitlab-runner/slot-${slot}"

  [runners.autoscaler]
    capacity_per_instance = 4

設定オプション

設定	説明	デフォルト
`use_slot_cgroups`	スロットベースのcgroup割り当てを有効にする	`false`
`slot_cgroup_template`	cgroupパスのテンプレート。プレースホルダーとして`${slot}`を使用してください。形式はDockerのcgroupドライバーによって異なります（systemd: `runner-slot-${slot}.slice`、cgroupfs: `gitlab-runner/slot-${slot}`）。	`"gitlab-runner/slot-${slot}"`

テンプレートは、スロット番号のプレースホルダーとして${slot}を使用したbashスタイルの変数展開を使用します。例:

systemdドライバーの場合: スロット5の場合、runner-slot-${slot}.sliceはrunner-slot-5.sliceになります
cgroupfsドライバーの場合: スロット5の場合、gitlab-runner/slot-${slot}はgitlab-runner/slot-5になります

docker info | grep "Cgroup Driver"を使用して、Docker cgroupドライバーを確認してください:

Docker固有の設定

Docker Autoscaler executorを使用する場合、サービスコンテナに対して個別のテンプレートを指定できます:

[[runners]]
  executor = "docker-autoscaler"
  use_slot_cgroups = true
  slot_cgroup_template = "runner-slot-${slot}.slice"

  [runners.docker]
    service_slot_cgroup_template = "runner-slot-${slot}.slice"

設定	説明	デフォルト
`service_slot_cgroup_template`	サービスコンテナcgroupパスのテンプレート。Dockerのcgroupドライバー形式と一致する必要があります	`slot_cgroup_template`と同じです。

環境セットアップ

スロットベースのcgroupを有効にする前に、Runnerホストでcgroup階層を準備します。

systemd cgroupドライバーのセットアップスクリプト

Dockerがsystemd cgroupドライバー（docker info | grep "Cgroup Driver"で確認）を使用している場合は、raw cgroupディレクトリの代わりにsystemdスライスを作成する必要があります。

セットアップスクリプトを作成します（gitlab-runner-systemd-slice-setup.sh）:

#!/bin/bash
# gitlab-runner-systemd-slice-setup.sh
# Script to set up systemd slices for GitLab Runner slot-based cgroups
# This example configures 4 slots on an 8-core machine, with each slot pinned to 2 CPUs

set -e

MAX_SLOTS=4  # Adjust based on your capacity_per_instance configuration

# CPU pinning configuration (2 CPUs per slot on an 8-core machine)
# Format: comma-separated CPU list for systemd AllowedCPUs
declare -a CPU_ASSIGNMENTS=(
    "0,1"    # Slot 0: CPUs 0 and 1
    "2,3"    # Slot 1: CPUs 2 and 3
    "4,5"    # Slot 2: CPUs 4 and 5
    "6,7"    # Slot 3: CPUs 6 and 7
)

# Check if running as root
if [[ $EUID -ne 0 ]]; then
   echo "This script must be run as root for systemd slice setup"
   exit 1
fi

# Verify systemd is available
if ! command -v systemctl &> /dev/null; then
    echo "Error: systemctl not found. This script requires systemd."
    exit 1
fi

echo "Setting up systemd slices for GitLab Runner"
echo "Configuration: $MAX_SLOTS slots on an 8-core machine (2 CPUs per slot)"

for ((slot=0; slot<MAX_SLOTS; slot++)); do
    slice_name="runner-slot-${slot}.slice"
    echo "Creating systemd slice: $slice_name (CPUs: ${CPU_ASSIGNMENTS[$slot]})"

    # Create systemd slice configuration
    cat > "/etc/systemd/system/$slice_name" <<EOF
[Unit]
Description=GitLab Runner Slot $slot
Before=slices.target

[Slice]
CPUAccounting=true
MemoryAccounting=true
AllowedCPUs=${CPU_ASSIGNMENTS[$slot]}
EOF

done

# Reload systemd to pick up new slice units
systemctl daemon-reload

# Start all slices
for ((slot=0; slot<MAX_SLOTS; slot++)); do
    slice_name="runner-slot-${slot}.slice"
    systemctl start "$slice_name"
done

echo ""
echo "Systemd slices created successfully!"
echo ""
echo "Verifying slices:"
for ((slot=0; slot<MAX_SLOTS; slot++)); do
    slice_name="runner-slot-${slot}.slice"
    status=$(systemctl is-active "$slice_name" 2>/dev/null || echo "inactive")
    echo "  $slice_name: $status"
done

echo ""
echo "To verify CPU assignments, check:"
echo "  systemctl show runner-slot-0.slice | grep AllowedCPUs"

セットアップスクリプトを実行します:

chmod +x gitlab-runner-systemd-slice-setup.sh
sudo ./gitlab-runner-systemd-slice-setup.sh

`cgroupfs`ドライバーのセットアップスクリプト（代替）

Dockerがcgroupfsの代わりにsystemdドライバーを使用している場合は、raw cgroupディレクトリを作成するこの代替スクリプトを使用します:

#!/bin/bash
# gitlab-runner-cgroup-setup.sh
# Script to set up cgroup v2 hierarchy for GitLab Runner slot-based cgroups
# This example configures 4 slots on an 8-core machine, with each slot pinned to 2 CPUs
# Use this script only if Docker is using the cgroupfs driver (not systemd)

set -e

CGROUP_ROOT="/sys/fs/cgroup"
RUNNER_CGROUP="gitlab-runner"
MAX_SLOTS=4  # Adjust based on your capacity_per_instance configuration

# CPU pinning configuration (2 CPUs per slot on an 8-core machine)
# Format: "cpu_list" - adjust based on your CPU topology
declare -a CPU_ASSIGNMENTS=(
    "0-1"    # Slot 0: CPUs 0 and 1
    "2-3"    # Slot 1: CPUs 2 and 3
    "4-5"    # Slot 2: CPUs 4 and 5
    "6-7"    # Slot 3: CPUs 6 and 7
)

# Check if running as root
if [[ $EUID -ne 0 ]]; then
   echo "This script must be run as root for cgroup setup"
   exit 1
fi

# Verify cgroup v2 is available
if [[ ! -f "$CGROUP_ROOT/cgroup.controllers" ]]; then
    echo "Error: cgroup v2 not detected. This script requires cgroup v2."
    exit 1
fi

echo "Setting up cgroup v2 hierarchy for GitLab Runner"
echo "Configuration: $MAX_SLOTS slots on an 8-core machine (2 CPUs per slot)"

# Create base runner cgroup
mkdir -p "$CGROUP_ROOT/$RUNNER_CGROUP"

# Enable controllers if available
if [[ -f "$CGROUP_ROOT/cgroup.controllers" ]]; then
    echo "+memory +cpu +cpuset" > "$CGROUP_ROOT/cgroup.subtree_control" 2>/dev/null || true
fi

# Create slot-specific cgroups
for ((slot=0; slot<MAX_SLOTS; slot++)); do
    slot_path="$CGROUP_ROOT/$RUNNER_CGROUP/slot-$slot"
    echo "Creating cgroup for slot $slot (CPUs: ${CPU_ASSIGNMENTS[$slot]})"

    mkdir -p "$slot_path"

    # Enable controllers for this slot
    if [[ -f "$CGROUP_ROOT/$RUNNER_CGROUP/cgroup.controllers" ]]; then
        echo "+memory +cpu +cpuset" > "$CGROUP_ROOT/$RUNNER_CGROUP/cgroup.subtree_control" 2>/dev/null || true
    fi

    # Pin slot to specific CPUs
    echo "${CPU_ASSIGNMENTS[$slot]}" > "$slot_path/cpuset.cpus"

    # Set memory nodes (usually 0 for single NUMA node systems)
    echo "0" > "$slot_path/cpuset.mems"

    # Set permissions for GitLab Runner user
    chown -R gitlab-runner:gitlab-runner "$slot_path" 2>/dev/null || true
done

echo "Cgroup setup complete!"

# Verify setup
echo ""
echo "Verifying cgroup setup:"
for ((slot=0; slot<MAX_SLOTS; slot++)); do
    slot_path="$CGROUP_ROOT/$RUNNER_CGROUP/slot-$slot"
    cpus=$(cat "$slot_path/cpuset.cpus")
    echo "  Slot $slot: CPUs $cpus"
done

セットアップスクリプトを実行します:

chmod +x gitlab-runner-cgroup-setup.sh
sudo ./gitlab-runner-cgroup-setup.sh

動作の仕組み

Docker Autoscaler executor

Docker Autoscaler executorは、--cgroup-parentフラグを使用して、スロットベースのcgroupパスをDockerコンテナに自動的に適用します。ビルドコンテナとサービスコンテナは両方とも、ジョブスクリプトを変更しなくても、スロット固有のcgroupに割り当てられます。

インスタンスexecutor

インスタンスexecutorは、ジョブにGITLAB_RUNNER_SLOT_CGROUP環境変数を提供します。この変数をジョブスクリプトで使用して、スロット固有のcgroupでプロセスを実行できます。

`systemd-run`を使用する

job:
  script:
    - echo "Running in cgroup $GITLAB_RUNNER_SLOT_CGROUP"
    - systemd-run --scope --slice=$GITLAB_RUNNER_SLOT_CGROUP ./my-process

`cgexec`を使用する

job:
  script:
    - echo "Running in cgroup $GITLAB_RUNNER_SLOT_CGROUP"
    - cgexec -g cpu,memory:$GITLAB_RUNNER_SLOT_CGROUP ./my-process

cgroup制限の設定

ジョブプロセスを実行する前に、cgroupのリソース制限を設定できます:

job:
  script:
    - echo "Configuring cgroup limits"
    - echo "100M" > /sys/fs/cgroup/$GITLAB_RUNNER_SLOT_CGROUP/memory.max
    - echo "50000" > /sys/fs/cgroup/$GITLAB_RUNNER_SLOT_CGROUP/cpu.max
    - ./my-process

トラブルシューティング

コンテナがcgroupエラーで起動に失敗する

cgroupパスが/sys/fs/cgroup/の下に存在することを確認します:
```
ls -la /sys/fs/cgroup/gitlab-runner/
```
GitLab Runnerユーザーにcgroupディレクトリへの書き込みアクセス権があることを確認します:
```
ls -la /sys/fs/cgroup/gitlab-runner/slot-0/
```
slot_cgroup_templateが${slot}プレースホルダーで正しい形式を使用していることを確認します:
特定のcgroup作成エラーについてGitLab Runnerログを確認してください:

手動でテストします:

Docker Autoscaler executorの場合:

docker run --rm --cgroup-parent=gitlab-runner/slot-0 alpine echo "test"

インスタンスexecutorの場合:

job:
  script:
    - echo "Slot cgroup: $GITLAB_RUNNER_SLOT_CGROUP"

ジョブが同じcgroupを使用する

テンプレートに${slot}プレースホルダーが含まれていないという警告がログに表示された場合:

level=warning msg="Slot cgroup template does not contain ${slot} placeholder.
All jobs will use the same cgroup, defeating the purpose of slot-based isolation."

これは、slot_cgroup_templateに${slot}変数がないことを意味します。プレースホルダーを含めるように設定を更新します:

[[runners]]
  slot_cgroup_template = "gitlab-runner/slot-${slot}"

Cgroup v2が利用できません

セットアップスクリプトがcgroup v2が検出されないことをレポートする場合は、システムで有効にする必要があるかもしれません。cgroup v2を有効にするには、Linuxディストリビューションのドキュメントを確認してください。最新のディストリビューションでは、通常、デフォルトで有効になっています。