マシンランナーの Windows へのインストール
このページでは、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
-
-
sepolicy ( RHEL 8 のみ)
-
rpmbuild ( RHEL 8 のみ)
-
コマンドラインからランナーをインストールする場合は、 CircleCI CLIを使用します。
セルフホストランナーの利用条件
Web アプリを介してマシンランナーをインストールする前に、 CircleCI ランナー規約 に同意する必要があります。 CircleCI Web アプリ の セルフホストランナー のセクションにアクセスするには、組織の管理者が Organization Settings > Self-Hosted Runners に行き、規約に同意する必要があります。
規約に同意すると、Self-Hosted Runners はサイドナビゲーションバーに常に表示されるようになります。
CircleCI は、組織の VCS 権限をミラーリングします。 組織の VCS の管理者が、CircleCI の管理者です。 不明な場合は、VCS の 管理者の権限を確認してください。
1. ネームスペースとリソースクラスの作成
セルフホストランナーをインストールするには、名前空間とリソースクラストークンを作成する必要があります。 リソース クラスとトークンを作成するには、VCS プロバイダーの組織管理者権限を持っている必要があります。 名前空間やリソースクラスについては、 コンセプト のページを参照してください。
お客様のランナーは、インベントリのページの左にあるナビゲーションバーで Self-Hosted Runners をクリックするとご覧いただけます。
-
CircleCI Web アプリ で、Self-Hostd Runners に移動します。
-
組織でセルフホストランナーを初めて使用する場合、ファーストステップとしてまず名前空間を作成する必要があります。 作成できる名前空間は、各組織につき 1 つのみです。 必須ではありませんが、 CircleCI のアカウント名を小文字で使用することを推奨します。 CircleCI は UI でデフォルトで推奨される名前空間として組織名を入力します。
もし、お客様の組織が既に Orb を使用しているのであれば、新しい名前空間を作らないでください。 その代わりに、お客様の組織が Orb に使用している名前空間を入力してください。
-
2つ目の入力フィールドには、セルフホスト・ランナー・リソース・クラスの名前を入力します。
-
リソースクラストークンをコピーし保存します。 セルフホストランナーはこのトークンを使って関連するリソースクラスの作業を要求します。
トークンは再取得できないので、必ず安全な場所に保管してください。 -
Linux、macOS、または Windows 上でのセルフホスト型ランナーのセットアップに特化したインストール手順については、「Machine」タブを選択してください。 これらのプラットフォーム固有の手順は、このインストールガイドの次のセクションにも含まれています。
Figure 1. Web アプリによるマシンランナーのインストール -
新しいリソースクラスの設定コードが提供されます。 既存の
.circleci/config.yml
がある場合は、既存のjobs
セクションの下に新しいリソースクラスを追加してください。既存のファイルがない場合は、jobs
セクション全体を追加します。 既存の.circleci/config.yml
ファイルがない場合は、ファイルを作成し、すべてのコードをコピーします。
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 version Launch 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 におけるマシンランナーのインストール
-
GitHub から
Install-CircleCIRunner.ps1
スクリプト をダウンロードし、アクセスしやすい場所に配置します。 -
PowerShell を管理者として開き、スクリプトファイルを配置したディレクトリに移動します。
-
以下を PowerShell で実行します。
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; ./Install-CircleCIRunner.ps1
PowerShell インターフェイスにインストール結果が出力されます。
-
インストール中、マシンランナー (
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!"
アンインストール・再インストール手順
マシンランナーをアンインストールすると、システムの再インストールの準備をします。
-
GitHub から
Uninstall-CircleCIRunner.ps1
script をダウンロードし、アクセスしやすい場所に配置します。 -
PowerShell を管理者として開き、スクリプトファイルを配置したディレクトリに移動します。
-
以下を PowerShell で実行します。
./Uninstall-CircleCIRunner.ps1
Windows セルフホストランナーの Continuous モードと Single task モード
Windows マシンランナーは、デフォルトでは、セルフホストランナーがジョブの実行に使用する基盤テクノロジーの信頼性を高めるために、 Single task モード で実行されます。 Windows マシンランナーの場合、これが 推奨モード です。
Windows マシンランナーは、continuous
モードで実行することも 可能 ですが、その場合、クリーンなジョブ環境が保証されません。 ジョブが期待どおりに実行されず、失敗する可能性があります。
トラブルシューティング
Windows へのマシンランナーのインストールや実行において問題が生じた場合は、セルフホストランナーのトラブルシューティングガイドの マシンランナーのトラブルシューティングのセクション を参照してください。