JetBrains Space ヘルプ

セルフホスト型ワーカー

セルフホスト型ワーカーは、Windows、Linux、macOS 上の独自のマシンで実行できる軽量エージェントです。セルフホスト型ワーカーは Space Automation に接続し、ジョブとプロジェクトのソースコードを取得してジョブを実行し、結果を Space にレポートします。

セルフホスト型ワーカーを使用すると、コンテナーでは不可能な CI/CD ワークフローを実行できます。例:

  • Windows 上で完全な .NET フレームワークアプリケーションを構築します。

  • 特定のハードウェアを使用します。例: Apple ハードウェア上で iOS および macOS アプリケーションを構築する、GPU 上で ML タスクを実行するなど。

  • Space Cloud が提供するハードウェア構成よりも強力なハードウェア構成を使用します。

どのように機能するのか

  • セルフホスト型ワーカーエージェントは、.zip アーカイブとして、または特別に準備された Docker イメージの一部として配布される Java アプリケーションです。詳細

  • Space にセルフホスト型ワーカーを登録するを実行した後、ホストマシン上でエージェントを実行する必要があります。実行中のエージェントは定期的にステータスを Space に送信します。

  • エージェントは Space とのプル通信を使用します。エージェントが通信を開始し、Space は受信リクエストにのみ応答します。これは、エージェント側で特定のネットワーク構成が必要ないことを意味します。唯一の要件は、Space インスタンスへのアクセスです。

  • セルフホスト型ワーカーでジョブを実行するには、ジョブステップに host ブロックを使用する必要があります。

    job("Hello from self-hosted worker") { host("Run echo") { shellScript { content = """ echo "Hello World!" """ } } }

    重要: Space がこのジョブをセルフホスト型ワーカーにルーティングできるようにするには、このジョブをセルフホスト型ワーカーワーカープールに割り当てる必要があります。これは、デフォルトのワーカープールパラメーターを使用するか、ジョブの requirements ブロックを使用して明示的に行うことができます。例:

    job("Hello from self-hosted worker") { requirements { workerPool = WorkerPools.SELF_HOSTED } host("Run echo") { // ... } }

    ジョブ実行環境を指定する方法の詳細については、こちらを参照してください。

  • 少なくとも 1 つの host ステップを持つジョブがトリガーされると、オートメーションはそのジョブに適したワーカーをランダムに選択します。適切なワーカーが見つかると、自動化によってジョブの実行が開始されます。

  • ワーカーエージェント:

    1. ホストマシン上に一時ディレクトリを作成します。

    2. オートメーションスクリプトを含むプロジェクトのソースコードをダウンロードします。

    3. そしてジョブを実行します。

    ジョブが完了すると、エージェントは結果をオートメーションに報告し、一時ディレクトリを削除します。

  • セルフホスト型ワーカーは、Space サブスクリプションプランに基づいて作業時間ごとに請求されます。詳細

ホストマシンの要件

セルフホストワーカーとして使用するホストマシンは、次の要件を満たしている必要があります。

  1. インストール済みのソフトウェア:

    • Git: どのバージョンでも。

    • Docker、Docker Compose 1.27.0 以降 : container ステップを実行する場合のみ。

    • JRE11 以降 : kotlinScript ブロックを使用して Kotlin コードを実行する場合のみ。

    重要: Git、Docker、Java へのパスは、システム PATH で指定する必要があります。

  2. *.jetbrains.space および download.jetbrains.com へのアウトバウンド接続は、ホストマシンに対して許可されている必要があります。

ディレクトリ構造と作業ディレクトリ

オートメーションは、プロジェクトデータをこのワーカー上の一時ディレクトリ内に保存します。

/ //system temp dir, e.g. /tmp on Linux ├─── jetbrains/space/automation/worker/data // step data directory │ └─── steps-{randomId} // auto-generated directory │ └─── step-data-{randomStepId} // auto-generated directory │ ├─── share // file share │ ├─── system // non-user system files │ └─── work │ ├─── {git-repo-name} // cloned git repository (working directory) │ ├─── ... // other project repos (only if specified in the script) │ └─── ... ...

さらに詳細に:

  • {system-temp-dir}/jetbrains/space/automation/worker/data は、ステップデータのデフォルトの親ディレクトリです。

    デフォルトのパスを変更するには、 --dataDir エージェント引数を使用します。

    shellScript または kotlinScript でこのパスを取得するには、JB_SPACE_STEP_DATA_PATH 環境変数を使用します。

  • .../work/{git-repo-name} は、プロジェクトソースのデフォルトの場所です。ここで、{git-repo-name} はプロジェクトの Git リポジトリ名を表します。追加のプロジェクトリポジトリをチェックアウトする方法の詳細については、「ソースコードをチェックアウトする」を参照してください。

    shellScript または kotlinScript でこのパスを取得するには、JB_SPACE_WORK_DIR_PATH 環境変数を使用します。

  • .../share は、ファイル共有に使用される外部ストレージです。

    shellScript または kotlinScript でこのパスを取得するには、JB_SPACE_FILE_SHARE_PATH 環境変数を使用します。

  • ジョブ終了後、ステップデータディレクトリは削除されます。

セルフホスト型ワーカーでは何を実行できますか

コンテナーと同様に、セルフホスト型ワーカーを使用すると、シェルスクリプト (shellScript) および任意の Kotlin コード (kotlinScript) を実行できます。

container とは異なり、host では shellScript と kotlinScript の両方を 1 つのブロックで実行できることに注意してください。例:

job("This job works") { host("Run both kotlin and shell scripts") { kotlinScript { api -> // Do smth. } shellScript { content = """ echo Do smth. """ } requirements { type = OSType.Linux } } }

セルフホスト型ワーカーを追加する

  1. 管理で、自動化ページを開きます。

  2. ワーカーを追加をクリックします。

  3. ワーカー名前およびその他のオプションを指定します。

    • タグ : ジョブを特定のワーカーにルーティングします。自動化は、特定のタグでマークされたジョブを、同じタグを持つワーカー上でのみ実行します。詳細

    • プロジェクト :

      • すべてのプロジェクト : ワーカーは組織内のすべてのプロジェクトで利用できるようになります。このオプションを選択するには、組織の自動化ワーカーの作成権限が必要です。

      • 特定プロジェクト : ワーカーは、選択したプロジェクトでのみ使用できます。プロジェクト管理者ロールを持つプロジェクトのみを選択できます。

    ワーカーを追加をクリックすると、ワーカー設定ページに移動します。設定には、割り当てられたタグ、OS、利用可能なリソース、認証トークンに関する情報が含まれます。トークンを安全な場所にコピーします (トークンは、ワーカーの作成直後に 1 回だけ表示されます)。

  4. 次のタスクは、ホストマシン上でワーカーエージェントを実行することです。それが起こる前に、ワーカーは初期化されていない状態になります。その方法については、ワーカー設定ページのワーカーのインストール手順に記載されています。ワーカータイプを選択し、指示に従います。

    • Docker Windows/Linux/macOS 用 : ワーカーは、ホストマシン上で実行されている Docker コンテナー内で実行されます。

      例: Linux ホストマシン上のコンテナーでワーカーを実行するには:

      docker run \ --log-opt max-size=10m \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /tmp/jetbrains/space/automation/worker:/tmp/jetbrains/space/automation/worker \ -e SPACE_WORKER_SERVERURL=https://mycompany.jetbrains.space \ -e SPACE_WORKER_TOKEN=abc1234 \ public.registry.jetbrains.space/p/space/containers/space-automation-worker:139318
      コンテナー内の作業ディレクトリを変更する

      コンテナー内で実行する場合、ワーカーの作業ディレクトリは、このコンテナー内にマウントされたホストマシン上のディレクトリになります (2 番目の -v 引数を参照)。

      docker run \ --log-opt max-size=10m \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /tmp/jetbrains/space/automation/worker:/tmp/jetbrains/space/automation/worker \ -e SPACE_WORKER_SERVERURL=https://mycompany.jetbrains.space \ -e SPACE_WORKER_TOKEN=abc1234 \ public.registry.jetbrains.space/p/space/containers/space-automation-worker:139318

      コンテナー内の作業ディレクトリへのパスを変更する場合は、ホストマシン上のマウントされたディレクトリにも同じパスを使用する必要があります。SPACE_WORKER_DATADIR 環境変数を使用して新しいパスについてワーカーに通知することも必要です。例:

      docker run \ --log-opt max-size=10m \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /tmp/newdir/worker:/tmp/newdir/worker \ -e SPACE_WORKER_DATADIR=/tmp/newdir/worker \ -e SPACE_WORKER_SERVERURL=https://mycompany.jetbrains.space \ -e SPACE_WORKER_TOKEN=abc1234 \ public.registry.jetbrains.space/p/space/containers/space-automation-worker:139318

    • Windows/Linux/macOS 用バイナリ : ワーカーは仮想マシンまたはハードウェアマシン上で実行されます。

      例: Linux ホストマシンでワーカーを実行するには:

      unzip ./space-automation-worker.zip && \ chmod +x ./worker.sh && \ ./worker.sh start \ --serverUrl https://mycompany.jetbrains.space \ --token abc1234
      ワーカーバイナリを検証する

      ファイルのチェックサムとチェックサム署名をチェックすることで、ダウンロードしたバイナリの信頼性を検証できます。

      前提条件

      • gpg (バージョン 2.x) がマシンにインストールされています。ツールは https://gnupg.org/download/(英語) からダウンロードできます

      • gpg へのパスはシステム PATH 内に存在する必要があります。

      命令

      1. ワーカーのページのリンクを使用して、チェックサムファイルと署名ファイルをダウンロードします。ファイルをワーカー .zip ファイルと同じディレクトリに保存します。ディレクトリには次のファイルが含まれている必要があります。

        • space-automation-worker-windows.zip : ワーカーでアーカイブします。

        • space-automation-worker-windows.zip.sha256 : アーカイブファイルの SHA256 チェックサム。

        • space-automation-worker-windows.zip.sha256.asc : チェックサムファイルの署名。

      2. https://download.jetbrains.com/KEYS(英語) から KEYS 公開キーファイルをダウンロードし、次を実行します。

        gpg --import KEYS

        これをこれまでに行ったことがない場合、出力は次のようになります。

        gpg: key 1F7A8F87B9D8F501: 1 signature not checked due to a missing key gpg: /Users/you/.gnupg/trustdb.gpg: trustdb created gpg: key 1F7A8F87B9D8F501: public key "Download <download@jetbrains.com>" imported gpg: Total number processed: 1 gpg: imported: 1 gpg: no ultimately trusted keys found

        出力内のキー ID が 1F7A8F87B9D8F501 であることを確認してください。

      3. 以下を実行して署名を検証します。

        gpg --verify space-automation-worker-windows.zip.sha256.asc space-automation-worker-windows.zip.sha256

        出力に Good signature from "Download <download@jetbrains.com>" が含まれていることを確認してください

      4. 次のコマンドを実行して、公開キーの ID が 33FD4BFD33554634053D73C0C2148900BCD3C2AF であることを確認します。

        gpg --keyid-format long --list-keys --with-fingerprint 0x33FD4BFD33554634053D73C0C2148900BCD3C2AF

        出力内のキー ID が 1F7A8F87B9D8F501 であることを確認してください。これにより、ダウンロードされた sha256 ファイルが有効であることが保証されます。

      5. sha256 ファイルを使用して、.zip アーカイブのチェックサムを確認します。

        certUtil -hashfile space-automation-worker-windows.zip SHA256

        出力は次のようになります。

        SHA256 hash of space-automation-worker-windows.zip: cd5b12d9a8c74accade22f808e5ea18b2a018706d4112d649e1adfdd26187c7d CertUtil: -hashfile command completed successfully.

        出力内のハッシュ値が space-automation-worker-windows.zip.sha256 ファイル内の値と等しいことを確認してください。

      前提条件

      sha256sum および gpg (バージョン 2.x) がマシンにインストールされています。ツールをインストールするには、次のコマンドを実行します。

      • Debian ベースのディストリビューション: apt install coreutils gpg

      • RedHat ベースのディストリビューション: yum install coreutils gpg または dnf install coreutils gpg

      命令

      1. ワーカーのページのリンクを使用して、チェックサムファイルと署名ファイルをダウンロードします。ファイルをワーカー .zip ファイルと同じディレクトリに保存します。ディレクトリには次のファイルが含まれている必要があります。

        • space-automation-worker-linux.zip : ワーカーでアーカイブします。

        • space-automation-worker-linux.zip.sha256 : アーカイブファイルの SHA256 チェックサム。

        • space-automation-worker-linux.zip.sha256.asc : チェックサムファイルの署名。

      2. https://download.jetbrains.com/KEYS(英語) から KEYS 公開キーファイルをダウンロードし、次を実行します。

        LANG=C gpg --import KEYS

        これをこれまでに行ったことがない場合、出力は次のようになります。

        gpg: key 1F7A8F87B9D8F501: 1 signature not checked due to a missing key gpg: /Users/you/.gnupg/trustdb.gpg: trustdb created gpg: key 1F7A8F87B9D8F501: public key "Download <download@jetbrains.com>" imported gpg: Total number processed: 1 gpg: imported: 1 gpg: no ultimately trusted keys found

        出力内のキー ID が 1F7A8F87B9D8F501 であることを確認してください。

      3. 以下を実行して署名を検証します。

        LANG=C gpg --verify space-automation-worker-linux.zip.sha256.asc space-automation-worker-linux.zip.sha256

        出力に Good signature from "Download <download@jetbrains.com>" が含まれていることを確認してください

      4. 次のコマンドを実行して、公開キーの ID が 33FD4BFD33554634053D73C0C2148900BCD3C2AF であることを確認します。

        gpg --keyid-format long --list-keys --with-fingerprint 0x33FD4BFD33554634053D73C0C2148900BCD3C2AF

        出力内のキー ID が 1F7A8F87B9D8F501 であることを確認してください。これにより、ダウンロードされた sha256 ファイルが有効であることが保証されます。

      5. sha256 ファイルを使用して、.zip アーカイブのチェックサムを確認します。

        sha256sum -c space-automation-worker-linux.zip.sha256

        出力は次のようになります。

        space-automation-worker-linux.zip: OK

      前提条件

      sha256sum および gpg (バージョン 2.x) がマシンにインストールされています。たとえば、Homebrew(英語) : brew install coreutils gpg を使用してツールをインストールできます。

      命令

      1. ワーカーのページのリンクを使用して、チェックサムファイルと署名ファイルをダウンロードします。ファイルをワーカー .zip ファイルと同じディレクトリに保存します。ディレクトリには次のファイルが含まれている必要があります。

        • space-automation-worker-mac.zip : ワーカーでアーカイブします。

        • space-automation-worker-mac.zip.sha256 : アーカイブファイルの SHA256 チェックサム。

        • space-automation-worker-mac.zip.sha256.asc : チェックサムファイルの署名。

      2. https://download.jetbrains.com/KEYS(英語) から KEYS 公開キーファイルをダウンロードし、次を実行します。

        LANG=C gpg --import KEYS

        これをこれまでに行ったことがない場合、出力は次のようになります。

        gpg: key 1F7A8F87B9D8F501: 1 signature not checked due to a missing key gpg: /Users/you/.gnupg/trustdb.gpg: trustdb created gpg: key 1F7A8F87B9D8F501: public key "Download <download@jetbrains.com>" imported gpg: Total number processed: 1 gpg: imported: 1 gpg: no ultimately trusted keys found

        出力内のキー ID が 1F7A8F87B9D8F501 であることを確認してください。

      3. 以下を実行して署名を検証します。

        LANG=C gpg --verify space-automation-worker-mac.zip.sha256.asc space-automation-worker-mac.zip.sha256

        出力に Good signature from "Download <download@jetbrains.com>" が含まれていることを確認してください

      4. 次のコマンドを実行して、公開キーの ID が 33FD4BFD33554634053D73C0C2148900BCD3C2AF であることを確認します。

        gpg --keyid-format long --list-keys --with-fingerprint 0x33FD4BFD33554634053D73C0C2148900BCD3C2AF

        出力内のキー ID が 1F7A8F87B9D8F501 であることを確認してください。これにより、ダウンロードされた sha256 ファイルが有効であることが保証されます。

      5. sha256 ファイルを使用して、.zip アーカイブのチェックサムを確認します。

        sha256sum -c space-automation-worker-mac.zip.sha256

        出力は次のようになります。

        space-automation-worker-mac.zip: OK

    利用可能なワーカースクリプト引数 (環境変数としても設定 / 取得できることに注意してください):

    引数

    ENV 変数

    説明

    --serverUrl

    SPACE_WORKER_SERVERURL

    Space インスタンスの URL。

    --token

    SPACE_WORKER_TOKEN

    ワーカーに対して発行される認証トークン。トークンは、ワーカー登録中に 1 回だけ表示されます。紛失した場合は、新しいものを生成する必要があります。

    --dataDir

    SPACE_WORKER_DATADIR

    スクリプトがすべての必要なデータ (プロジェクトソース、ファイル共有、オートメーション固有のデータ) をダウンロードするディレクトリへのパスを設定します。

    --hostname

    SPACE_WORKER_HOSTNAME

    セルフホスト型ワーカーのホスト名を指定します。これは主にトラブルシューティングの目的で使用され、ホスト名でワーカーを区別しやすくなります。

    --cpu , --mem

    SPACE_WORKER_CPU , SPACE_WORKER_MEM

    ホストマシンで利用可能な CPU と RAM の量を指定します。これらのパラメーターは、エージェントが消費できるリソースの数を制限しません。これらは、オートメーションが利用可能なリソースの量に基づいてジョブに適切なワーカーを選択するのを支援するためにのみ使用されます。詳細

    ワーカーを開始すると、ステータスが Healthy に変わる必要があります。

    Healthy

セルフホスト型ワーカーを使用してステップを実行する

オートメーションがワーカーでジョブを実行するには、ジョブに少なくとも 1 つの host ステップが含まれている必要があります。

job("Build solution") { host("Run msbuild") { shellScript { interpreter = "cmd" content = """ C:\"Program Files (x86)"\MSBuild\14.0\Bin\MsBuild.exe MySolution.sln """ } requirements { type = OSType.Windows } } }

host ステップ内では、container ステップ内とほぼ同じ DSL 要素を使用できます。主な違いは、host 内で次のこともできることです。

  • requirements ブロックを使用すると、ジョブを実行する必要があるワーカーの要件を指定できます。詳細

  • 多数の shellScript 要素を使用します。各スクリプトはジョブログに個別に表示されます。

  • shellScript と kotlinScript の両方を 1 つの host ブロックで使用します。

  • ワーカー固有の環境変数の番号にアクセスします。

ジョブに特定のワーカーを選択する

特定のジョブを特定のワーカーにルーティングするには、タグ、オペレーティングシステム、および利用可能なシステムリソースなど、さまざまな方法があります。ルーティング条件を指定するには、host 内の requirements ブロックを使用します。requirements 内で 3 つの条件をすべて指定できます。

オートメーションがジョブに適したワーカーを見つけられない場合、ジョブはブロック状態に切り替わります。

No self-hosted workers

タグによるジョブのルーティング

タグ付けは、ジョブを特定のワーカーにルーティングする方法の 1 つです。ワーカーとジョブの両方に同じタグを付ける必要があります。詳細は以下を参照してください。

  1. 管理 | 自動化で、必要なワーカーを選択します。

  2. 編集をクリックします。

  3. タグには、一意のタグ名を指定します。

    Self-hosted worker settings

  4. 必要な .space.kts ファイルを開き、特定の host の requirements ブロックに同じタグを指定します。例:

    job("Hello from host") { host("Run echo") { shellScript { content = """ echo Hello World! """ } requirements { workerTags("Pool1") } } }

オペレーティングシステムごとにジョブをルーティングする

ワーカーエージェントは、ホストマシンのオペレーティングシステムを Space に自動的に報告します。オペレーティングシステムに基づいて適切なワーカーを選択するには、スクリプトで必要な OS を指定します。

requirements { os { // the possible values are // Windows, macOS, Linux type = OSType.Windows } }

利用可能なリソースに応じてジョブをルーティングする

ワーカーエージェントは、ホストマシンのシステムリソース (CPU コアと RAM) を Space に自動的に報告します。ホストマシンのリソースに基づいて適切なワーカーを選択するには、スクリプトで必要なリソースを指定します。

requirements { resources { // the job can run on any worker that // has 1 CPU core and 1GB RAM (or more) minCpu = 1.cpu minMemory = 1.gb } }

ワーカーエージェントは、これらすべてのリソースがジョブで使用できることを保証しないことに注意してください。ホストマシン上で実行されている他のプロセスによってリソースがどのように消費されるかについては何も知りません。

特定のワーカーに使用可能なシステムリソースを手動で設定できます。これは、たとえば、特定のワーカーで「重い」ジョブを実行したくない場合に役立ちます。使用可能なリソースを設定するには、--cpu (mCPU で設定) および --mem (MB で設定) 引数を指定してワーカーエージェントを実行します。例:

./worker.sh start \ --serverUrl https://mycompany.jetbrains.space \ --token abc1234 \ --cpu 2000 \ --mem 8000

上の例では、実際のシステムリソースに関係なく、ワーカーはシステムに 2 つの CPU コアと 8GB RAM が利用可能であることを Space に報告します。ジョブ内の host がより多くのリソースを必要とする場合、ワーカーはこのジョブには適していないとみなされます。これらの値は、ワーカーエージェントがマシン上でより多くのリソースを消費することを妨げるものではないことに注意してください。これらの値は、Space がジョブに最適なワーカーを選択するのに役立つだけです。

セルフホスト型ワーカーでコンテナーステップを実行する

セルフホスト型ワーカーを使用すると、host ステップだけでなく container ステップも実行できます。container ステップを実行できるようにするには、ワーカーに Docker および Docker Compose がインストールされている必要があります。

オートメーションは、次のいずれかの場合に、セルフホスト型ワーカーで container ステップを含むジョブの実行を試行します。

  • ジョブには container ステップと host ステップの両方があります。

  • container ステップには requirements セクションがあります。container ステップを特定のワーカーにルーティングできるのは、 workerTags を使用する場合のみであることに注意してください。

  • job には container ステップのみがあり ( requirements はありません)、デフォルトのワーカープールパラメーターはセルフホスト型ワーカーに設定されます。

例:

job("Example") { container(image = "amazoncorretto:17-alpine") { // ... requirements { workerTags("Pool 1") } } }

詳細

ワーカーを一時停止する

ワーカーを一時的に中断できます。ワーカーエージェントはホストマシン上で実行を続けますが、オートメーションは中断されたワーカーにジョブをルーティングしません。ワーカーに実行中のジョブがまだある場合は、まずジョブを終了してから一時停止状態に切り替えます。

ワーカーを一時停止するには

  1. 管理 | 自動化で必要なワーカーを見つけます。

  2. ワーカー設定で、中断をクリックします。

ワーカーをアクティブにするには

  1. 管理 | 自動化で必要なワーカーを見つけます。

  2. ワーカー設定で、アクティブにするをクリックします。

ワーカーを削除する

  1. 管理 | 自動化で必要なワーカーを見つけます。

  2. ワーカー設定で、削除をクリックします。

ワーカーの削除は即時操作であることに注意してください。ワーカーにまだ実行中のジョブがある場合、ジョブは終了されます。

実行されたステップの履歴を表示する

特定の自己ホスト型ワーカーによって実行されたすべてのステップは、ワーカー履歴に保存されます。

  1. 管理 | 自動化で必要なワーカーを見つけます。

  2. ワーカー設定で、アクティビティタブを開きます。

ワーカー状態

状態

説明

初期化されていません

ワーカーはこれまで Space に接続したことがありません。これは、Space に登録した後のワーカーの初期状態です。

ヘルス

ワーカーは稼働中です

不ヘルス

ワーカーのディスク容量が不足しています: 自動化はジョブをこのワーカーにルーティングしません

中断した

ワーカーは手動で一時停止されました

正常なシャットダウン

ワーカーが現在実行中のジョブを終了すると、ワーカーエージェントプロセスが終了します。これは、SIGTERM を使用してエージェントプロセスを終了すると発生します。(たとえば、プロセスを kill する場合)

切断されました

自動化はワーカーとは関係ありません。これは、たとえば、ワーカーエージェントがホストマシン上で実行されていない場合、マシンの電源がオフになっているか、インターネット接続がない場合に発生する可能性があります。

サービスコンテナー Space クラウドワーカー