Self-Hosted Bare Metal Runner

Self-Hosted Runner는 Bencher가 관리하는 On-Demand 또는 Dedicated Runner를 사용하는 대신 직접 실행하고 관리하는 Bare Metal Runner입니다. runner 바이너리를 Bencher API 서버로 향하게 하면, 자체 하드웨어에서 Job을 청구(claim)하고 실행합니다.

Runner를 셀프 호스팅하는 것은 다음과 같은 경우에 적합합니다:

  • Bencher Cloud가 제공하지 않는 특정 하드웨어에서 벤치마크를 실행하려는 경우
  • 벤치마크 워크로드를 자체 네트워크나 에어 갭(air-gapped) 환경 안에 유지하려는 경우
  • Bencher Self-Hosted를 처음부터 끝까지 실행하려는 경우

이 가이드는 Runner를 등록하고, Spec으로 그 하드웨어를 설명하고, 둘을 함께 연결한 다음, runner 바이너리를 시작하는 과정을 안내합니다. Runner, Spec, Sandbox, Job이 어떻게 맞물리는지에 대한 개념적 개요는 Bare Metal 개요를 참고하세요.

🐰 Firecracker 샌드박싱에는 KVM이 활성화된 Linux가 필요합니다. 샌드박스가 없는 Spec만 제공하는 Runner는 지원되는 모든 호스트에서 실행할 수 있습니다.

Runner 생성

Runner는 runner 바이너리를 Bencher API 서버에 인증하는 리소스입니다. bencher CLI, Runners REST API, 또는 Bencher Console로 하나를 생성하세요.

Terminal window
bencher runner create \
  --host https://api.bencher.example.com \
  --name "My Runner"

Bencher는 새 Runner와 그 키를 함께 반환합니다:

{
  "uuid": "...",
  "key": "bencher_runner_..."
}

키는 한 번만 표시되므로 안전하게 보관하세요. Runner를 시작할 때 runner 바이너리에 이 키를 전달하게 됩니다. 키를 분실하거나 유출한 경우, POST /v0/runners/{runner}/key API로 키를 교체하세요. 그러면 이전 키가 즉시 무효화됩니다.

Spec 생성

Spec은 Runner가 제공하는 하드웨어를 설명합니다: 운영 체제, CPU 아키텍처, Sandbox 유형, CPU 개수, 메모리, 디스크, 네트워크 액세스. Job은 필요한 Spec을 선언하고, Runner는 자신이 지원하는 Spec의 Job만 청구(claim)합니다.

bencher CLI, Specs REST API, 또는 Bencher Console로 Spec을 생성하세요:

Terminal window
bencher spec create \
  --host https://api.bencher.example.com \
  --name "Intel v1" \
  --os linux \
  --architecture x86_64 \
  --sandbox firecracker \
  --cpu 4 \
  --memory 51539607552 \
  --disk 137438953472

샌드박스가 없는 Spec을 정의하려면 --sandbox를 생략하고, 이 Spec의 Job에 네트워크 액세스를 허용하려면 --network를 전달하세요. 메모리와 디스크는 바이트 단위로 지정합니다. Spec에 대한 자세한 내용과 Testbed가 각 Report에 사용된 Spec을 어떻게 기록하는지는 Testbed & Spec을 참고하세요.

Runner에 Spec 할당

Runner Spec은 Spec을 Runner에 연결합니다. 하나의 Runner는 여러 Spec을 지원할 수 있고, 하나의 Spec은 여러 Runner가 지원할 수 있습니다. Runner는 자신에게 할당된 Spec의 Job만 청구(claim)합니다.

bencher CLI 또는 Runner Specs REST API로 Runner에 Spec을 추가하세요:

Terminal window
bencher runner spec add my-runner \
  --host https://api.bencher.example.com \
  --spec intel-v1

나중에 DELETE /v0/runners/{runner}/specs/{spec} API로 연결을 제거할 수 있습니다.

Runner 시작

Runner를 생성하고 Spec을 하나 이상 할당했다면, runner up으로 자체 하드웨어에서 runner 바이너리를 시작하세요. API 서버 호스트, Runner UUID 또는 슬러그, 그리고 Runner 키를 플래그나 환경 변수로 제공합니다:

Terminal window
runner up \
  --host https://api.bencher.example.com \
  --runner my-runner \
  --key bencher_runner_...
Terminal window
export BENCHER_HOST=https://api.bencher.example.com
export BENCHER_RUNNER=my-runner
export BENCHER_RUNNER_KEY=bencher_runner_...
runner up

runner 바이너리는 API 서버로 단일 WebSocket 연결을 열고, 자신의 Spec과 일치하는 Job을 폴링하고, 각 Job을 실행한 후, 결과를 다시 보고합니다. 연결은 여러 Job에 걸쳐 열린 상태로 유지되며, 새 버전이 있을 때 바이너리는 Job 사이에 스스로 업데이트합니다.

기본적으로 Runner는 Sandbox가 없는 Spec의 Job을 거부합니다. Runner가 샌드박스 없는 Job을 호스트에서 직접 실행하도록 하려면, --danger-allow-no-sandbox 플래그로 시작하세요.

  • runner up

    runner up

    Runner를 시작하여 벤치마크 Job을 폴링하고 실행합니다. Self-Hosted Runner를 운영하는 데 사용하는 장기 실행 명령입니다. Runner는 API 서버로 단일 WebSocket 연결을 열고, 자신의 Spec과 일치하는 Job을 청구(claim)하고, 실행한 후, 결과를 다시 보고합니다.

    runner up [OPTIONS]

    옵션

    --host <HOST>

    연결할 Bencher API 서버입니다. 기본적으로 https://api.bencher.dev가 사용됩니다. BENCHER_HOST 환경 변수로도 설정할 수 있습니다.

    --runner <RUNNER>

    운영할 Runner의 UUID 또는 슬러그입니다. BENCHER_RUNNER 환경 변수로도 설정할 수 있습니다.

    --key <KEY>

    Runner를 생성할 때 반환된 Runner 인증 키(bencher_runner_...)입니다. BENCHER_RUNNER_KEY 환경 변수로도 설정할 수 있습니다.

    --poll-timeout <POLL_TIMEOUT>

    Job을 기다리는 동안의 롱 폴(long-poll) 타임아웃(초)으로, 1에서 900 사이입니다. 기본적으로 55가 사용됩니다.

    --danger-allow-no-sandbox

    Sandbox 없이 Job 실행을 허용합니다. 이 플래그가 없으면, Sandbox가 없는 Spec의 Job은 런타임에 거부됩니다. 샌드박스 없는 Job은 호스트에서 직접 실행되므로, 신뢰할 수 있는 워크로드에만 활성화하세요. BENCHER_DANGER_ALLOW_NO_SANDBOX 환경 변수로도 설정할 수 있습니다.

    --sandbox-log-level <SANDBOX_LOG_LEVEL>

    샌드박스 프로세스의 로그 레벨입니다. 기본적으로 warning이 사용됩니다.

    --no-auto-update

    서버로부터의 자동 업데이트를 비활성화합니다. 기본적으로, 서버가 새 버전을 제공하면 Runner는 Job 사이에 스스로 업데이트합니다. BENCHER_NO_AUTO_UPDATE 환경 변수로도 설정할 수 있습니다.

    --max-download-size <MAX_DOWNLOAD_SIZE>

    자체 업데이트 바이너리의 최대 다운로드 크기(바이트)입니다. 기본적으로 500 MiB가 사용됩니다. --no-auto-update와 충돌합니다.

    --max-output-size <MAX_OUTPUT_SIZE>

    수집된 stdout 및 stderr의 최대 크기(바이트)입니다. 기본적으로 25 MiB가 사용됩니다.

    --max-file-count <MAX_FILE_COUNT>

    디코딩할 출력 파일의 최대 개수입니다. 기본적으로 255가 사용됩니다.

    --max-symlinks <MAX_SYMLINKS>

    경로 확인 중 따라갈 심볼릭 링크의 최대 개수로, Linux 커널의 MAXSYMLINKS 제한과 일치합니다. 기본적으로 40이 사용됩니다. 샌드박스 없는 모드에서만 사용됩니다.

    --grace-period <GRACE_PERIOD>

    벤치마크 종료 후 최종 출력 수집 전까지의 유예 기간(초)입니다.

    호스트 튜닝

    각 벤치마크 전에, runner는 측정 노이즈를 줄이기 위해 호스트 튜닝을 적용합니다. 기본적으로 ASLR, NMI 워치독, SMT / 하이퍼스레딩, 터보 부스트를 비활성화하고, CPU 스케일링 거버너를 performance로, swappiness를 10으로, perf_event_paranoid를 -1로 설정합니다. 아래 플래그는 개별 최적화를 대신 호스트 기본값으로 유지합니다.

    --no-tuning

    모든 호스트 튜닝 최적화를 비활성화합니다.

    --aslr

    ASLR을 활성화된 상태로 유지합니다(기본값: 벤치마크에서는 비활성화).

    --nmi-watchdog

    NMI 워치독을 활성화된 상태로 유지합니다(기본값: 벤치마크에서는 비활성화).

    --smt

    SMT / 하이퍼스레딩을 활성화된 상태로 유지합니다(기본값: 벤치마크에서는 비활성화).

    --turbo

    터보 부스트를 활성화된 상태로 유지합니다(기본값: 벤치마크에서는 비활성화).

    --swappiness <SWAPPINESS>

    swappiness 값을 설정합니다. 기본적으로 10이 사용됩니다.

    --governor <GOVERNOR>

    CPU 스케일링 거버너를 설정합니다. 기본적으로 performance가 사용됩니다.

    --perf-event-paranoid <PERF_EVENT_PARANOID>

    perf_event_paranoid 값을 설정합니다. 기본적으로 -1이 사용됩니다.

    --help

    도움말을 출력합니다.

모든 옵션은 runner CLI 참조를, 서버와 주고받는 메시지는 Runner Protocol 참조를 확인하세요.

Self-Hosted Runner 워크플로

Runner가 연결되면, 다른 Bare Metal Runner와 동일한 방식으로 벤치마크를 제출합니다: Image를 빌드하고 푸시한 다음, 일치하는 Spec으로 bencher run --image를 실행합니다. 아래 다이어그램은 Runner 등록부터 Job 실행까지 전체 경로를 보여줍니다.

OCI Registryrunner binaryAPI ServerOCI Registryrunner binaryAPI ServerAdminbencher runner createRunner + keybencher spec createbencher runner spec addrunner up --host --runner --keyConnect (WebSocket) and poll for JobsAssign matching JobPull ImageImage layersRun benchmarkSubmit resultsAdmin

계속 진행하기: runner CLI 참조 ➡

🤖 이 문서는 AI에 의해 자동으로 번역되었습니다. 정확하지 않을 수도 있고 오류가 있을 수도 있습니다. 오류를 발견하면 GitHub에서 문제를 열어주세요.

Published: Fri, June 19, 2026 at 8:00:00 AM UTC