マシンランナーの Windows へのインストール

1+ year ago1 min read
Last updated • Read time
クラウド
This document is applicable to CircleCI クラウド
Server v4.x
This document is applicable to CircleCI Server v4.x
Server v3.x
This document is applicable to CircleCI Server v3.x

このページでは、CircleCI のマシンランナーを Windows にインストールする方法を説明します。 以下のインストール方法は、Windows Server 2019 と Windows Server 2016 の両方について、Datacenter エディションでテスト済みです。 デスクトップエクスペリエンスとリモートデスクトップサービスを備えたその他のサーバー SKU でも動作するはずです。

以下のページでは、マシンランナーと、その依存関係 (Chocolatey、Git、Gzip など) を Windows サーバーにインストールする手順を説明します。

セットアップ中、CircleCI ジョブを実行する新しいローカル管理者ユーザーを作成します。 そのため、Windows サーバーで、ローカルユーザーを作成し、そのユーザーのリモートログオンを許可できる必要があります。

また、このセットアップをドメイン環境で行う際には、Windows サーバーがドメインメンバーである必要があります。 セルフホストランナーインスタンスは、ドメインコントローラーとして動作している Windows サーバーでは実行できません。

前提条件

マシンランナーをインストールし、ジョブを実行するには、root 権限があり、以下のユーティリティとツールがシステムにインストールされている必要があります:

  • coreutils (Linux のみ)

  • curl (macOS ではデフォルトでインストール済み)

  • sha256sum (プリインストールされていない場合):

    • macOS の場合は、brew install coreutils ( Homebrew が必要)

    • Ubuntu/Debain の場合は、`sudo apt install coreutils

    • Red Hat の場合は、sudo yum install coreutils

  • tar

  • gzip

  • sepolicy ( RHEL 8 のみ)

  • rpmbuild ( RHEL 8 のみ)

  • コマンドラインからランナーをインストールする場合は、 CircleCI CLIを使用します。

セルフホストランナーの利用条件

Web アプリを介してマシンランナーをインストールする前に、 CircleCI ランナー規約 に同意する必要があります。 CircleCI Web アプリセルフホストランナー のセクションにアクセスするには、組織の管理者が Organization Settings > Self-Hosted Runners に行き、規約に同意する必要があります。

Runner terms and conditions

規約に同意すると、Self-Hosted Runners はサイドナビゲーションバーに常に表示されるようになります。

CircleCI は、組織の VCS 権限をミラーリングします。 組織の VCS の管理者が、CircleCI の管理者です。 不明な場合は、VCS の 管理者の権限を確認してください。

1. ネームスペースとリソースクラスの作成

セルフホストランナーをインストールするには、名前空間とリソースクラストークンを作成する必要があります。 リソース クラスとトークンを作成するには、VCS プロバイダーの組織管理者権限を持っている必要があります。 名前空間やリソースクラスについては、 コンセプト のページを参照してください。

お客様のランナーは、インベントリのページの左にあるナビゲーションバーで Self-Hosted Runners をクリックするとご覧いただけます。

  1. CircleCI Web アプリ で、Self-Hostd Runners に移動します。

    Runner set up
  2. 組織でセルフホストランナーを初めて使用する場合、ファーストステップとしてまず名前空間を作成する必要があります。 作成できる名前空間は、各組織につき 1 つのみです。 必須ではありませんが、 CircleCI のアカウント名を小文字で使用することを推奨します。 CircleCI は UI でデフォルトで推奨される名前空間として組織名を入力します。

    もし、お客様の組織が既に Orb を使用しているのであれば、新しい名前空間を作らないでください。 その代わりに、お客様の組織が Orb に使用している名前空間を入力してください。

  3. 2つ目の入力フィールドには、セルフホスト・ランナー・リソース・クラスの名前を入力します。

    Runner set up
  4. リソースクラストークンをコピーし保存します。 セルフホストランナーはこのトークンを使って関連するリソースクラスの作業を要求します。

    Runner set up
  5. Linux、macOS、または Windows 上でのセルフホスト型ランナーのセットアップに特化したインストール手順については、「Machine」タブを選択してください。 これらのプラットフォーム固有の手順は、このインストールガイドの次のセクションにも含まれています。

    Machine runner in the web app
    Figure 1. Web アプリによるマシンランナーのインストール
  6. 新しいリソースクラスの設定コードが提供されます。 既存の .circleci/config.yml がある場合は、既存の jobs セクションの下に新しいリソースクラスを追加してください。既存のファイルがない場合は、 jobs セクション全体を追加します。 既存の .circleci/config.yml ファイルがない場合は、ファイルを作成し、すべてのコードをコピーします。

    Runner set up

2. 起動エージェントのバージョンを設定する(サーバーのみ)

  • For server v3.1.0 and up, use the table below to find the compatible machine runner launch-agent version for the version of server you are running:

    Server versionLaunch agent version

    3.0

    Runner not supported

    3.1

    1.0.11147-881b608

    3.2

    1.0.19813-e9e1cd9

    3.3

    1.0.29477-605777e

    3.4

    1.1.73695-40bf772

    4.0

    1.1.73695-40bf772

    4.1

    1.1.73695-40bf772

    4.2

    1.1.73695-40bf772

    4.3

    1.1.73189-8792751

    Substitute <launch-agent-version> with your launch-agent version for server and run the following:

    $Env:agentVer = "<launch-agent-version>"

3. Windows におけるマシンランナーのインストール

  1. GitHub から Install-CircleCIRunner.ps1 スクリプト をダウンロードし、アクセスしやすい場所に配置します。

  2. PowerShell を管理者として開き、スクリプトファイルを配置したディレクトリに移動します。

  3. 以下を PowerShell で実行します。

    Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072;
    ./Install-CircleCIRunner.ps1

    PowerShell インターフェイスにインストール結果が出力されます。

  4. インストール中、マシンランナー (launch-agent-config.yaml) の設定ファイルが Notepad で開かれます。 必要な情報をファイルに記入してください ( セルフホストランナーの設定ファイルのリファレンスを参照)。 設定ファイルはインストールディレクトリ (デフォルトは C:\Program Files\CircleCI) にあります。

セットアップが完了すると、マシンランナーが自動的に起動し、処理対象のジョブの検索を開始します。

マシンランナーの設定例

セルフホストランナーを使って実行する特定のジョブについて、以下のフィールドを設定する必要があります。

  • machine: true

  • resource_class: <namespace>/<resource-class>

以下は、ジョブ設定のシンプルなコード例です。

version: 2.1

workflows:
  build-workflow:
    jobs:
      - runner
jobs:
  runner:
    machine: true
    resource_class: <namespace>/<resource-class>
    steps:
      - run: echo "Hi I'm on Runners!"

アンインストール・再インストール手順

マシンランナーをアンインストールすると、システムの再インストールの準備をします。

  1. GitHub から Uninstall-CircleCIRunner.ps1 script をダウンロードし、アクセスしやすい場所に配置します。

  2. PowerShell を管理者として開き、スクリプトファイルを配置したディレクトリに移動します。

  3. 以下を PowerShell で実行します。

    ./Uninstall-CircleCIRunner.ps1

Windows セルフホストランナーの Continuous モードと Single task モード

Windows マシンランナーは、デフォルトでは、セルフホストランナーがジョブの実行に使用する基盤テクノロジーの信頼性を高めるために、 Single task モード で実行されます。 Windows マシンランナーの場合、これが 推奨モード です。

Windows マシンランナーは、continuous モードで実行することも 可能 ですが、その場合、クリーンなジョブ環境が保証されません。 ジョブが期待どおりに実行されず、失敗する可能性があります。

トラブルシューティング

Windows へのマシンランナーのインストールや実行において問題が生じた場合は、セルフホストランナーのトラブルシューティングガイドの マシンランナーのトラブルシューティングのセクション を参照してください。