Linux Shell 用のランナーをセットアップする

Linux Shell ランナーによって Docker なしで Bitbucket Pipelines ビルドを独自の Linux インフラストラクチャ上で実行できるようになるので、セルフホスト ランナーが使用したビルド時間に対して課金されなくなります。

前提条件

  • OpenJDK 11 (11.0.15 以上) をインストール済み

  • Git 2.35.0 以上

  • Bash 3.2 以降

  • ランナー用のホストとして少なくとも 8GB の RAM を持つ 64 ビット Linux インスタンス。

ランナーの使用

現在、ホスト マシンごとに 1 つのランナーの実行のみがサポートされています。

  1. ランナー ページに移動します。

    • ワークスペース ランナーについては、[ワークスペース設定] > [ワークスペース ランナー] の順に移動してご確認ください。

    • リポジトリ ランナーについては、[リポジトリ設定] > [ランナー] の順に移動してご確認ください。

  2. [ランナーを追加] を選択します。

  3. [ランナー インストール] ダイアログの [システムとアーキテクチャ] で [Linux Shell (x86_64)] を選択します。

  4. [ランナー インストール] ダイアログの [Run] ステップに表示された tar.gz ファイルをダウンロードします。

  5. ファイルを任意のディレクトリに解凍します。次に例を示します。

    1 2 3 tar -xv \ -f atlassian-bitbucket-pipelines-runner-x.y.tar.gz \ -C /home/<your_user_name>/atlassian-bitbucket-pipelines-runner/
  6. Runner フォルダーの bin ディレクトリに移動して、[ランナー インストール] ダイアログの [Run] ステップに表示されたコマンドを実行します。

Linux Shell ランナーは Bash によって、パイプライン ステップを Linux マシン (ホスト デバイス) で実行します。これによってランナーはアプリをホストで実行できますが、クリーンなビルド環境が全ステップで提供されるわけではありません。ステップによって発生する副作用 (アプリのインストール、データベース サービスの開始、ビルド ディレクトリ外部におけるファイルの編集など) は、(新しいパイプラインの実行を含む) 次に実行するステップに影響を与える可能性があります。これを補うために、ランナーは各ステップの後にビルド ディレクトリを空にしようとします。各ステップで実行するスクリプトが他のステップに大きな影響を与えないようにするのは、ユーザーの責任です。


Linux Shell ランナーの制限事項

ランナーが使用したメモリ

スワップ メモリがホスト マシンで有効にされている際は、ランナーで実行されるステップによって作成されたプロセスがスワップ メモリを使用する可能性があります。これによって、メモリ使用量エラーと OOM (メモリ不足) エラーに関する暫定的なビルド結果が生じる可能性があります。これは、利用可能なスワップ メモリが十分にあってビルドが成功する場合もあれば、十分なスワップができずに同じビルドがメモリ不足になる場合があります。この制限によるメモリの問題がないかを必ずご確認ください。

共有ビルド環境

ランナーはシェルによってステップ スクリプトを実行するので、ホスト マシンはランナーで実行するようにスケジュールされた複数のステップによって共有されます。スクリプトのインストール、または新しいライブラリのインストールなど、システム全体の変更がステップ内のランナーに加えられた場合、その変更はホスト マシンで実行される後続のすべてのステップに影響します。

サポートされない機能

次の機能は実装方法に制限があってセキュリティが複雑なため、セルフホスト ランナーではサポート対象外です。

その他の制限と回避策

キャッシュ

  • 事前定義された Docker キャッシュはサポート対象外 - Docker と Pipelines の事前定義済み Docker キャッシュは、Linux Shell ランナーでサポートされていません。

  • キャッシュを異なる OS 間で共有する - Linux ランナーや MacOS ランナーなど、異なるキャッシュ名をランナー タイプごとに指定することをお勧めします。次に例を示します。

    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 pipelines: custom: customPipelineWithRunnerAndCache: - step: name: Step 1 runs-on: - 'linux.shell' script: - echo "This step will run on a linux shell runner."; caches: - linux_bundler - step: name: Step 2 runs-on: - 'macos' script: - echo "This step will run on a macos runner."; caches: - macos_bundler definitions: caches: linux_bundler: vendor/bundle macos_bundler: vendor/bundle

    キャッシュには、他のオペレーティング システムでは動作しないプラットフォーム固有のファイルを含められます。キャッシュを異なるオペレーティング システム間で共有すると、MacOS ランナーが Linux 専用に生成されたファイルを使用しようとした際など、エラーが発生する可能性があります。

  • 肥大化したキャッシュ フォルダー - パフォーマンスに影響することから、キャッシュ フォルダーをステップ実行の最後にクリーン アップしません。このため、特にワークスペース ランナーでキャッシュ ディレクトリのサイズが急速に増加する可能性があります。そうなった場合は、cron ジョブを作成してキャッシュ フォルダーを定期的にクリーン アップすることをお勧めします。

  • キャッシュ フォルダーの場所は制限されていないため、キャッシュはデバイスにある任意のディレクトリに保存できます。キャッシュを定義する場所の技術的な影響にご留意のうえ、ホスト マシンが復旧可能であることをご確認ください。

Git LFS

Git LFS を使用するには、Git LFS をホストされたマシンにインストールする必要があります。Git LFS のインストール方法は「Bitbucket Git チュートリアル - LFS をインストールする」をご参照ください

 

SSH キー

次のような場合、Bitbucket Pipelines で SSH キーをセットアップすることができます。

  • ビルドで Bitbucket やその他のホスティング サービスとの認証を行い、非公開の依存関係を取得する必要があります。

  • デプロイで成果物をアップロードする前にリモート ホストまたはサービスとの認証を行う必要があります。

  • SSH、SFTP、または SCP などのツールによってビルドする場合

セキュリティ上の理由から、ランナーは SSH キーをビルド環境に自動で追加しません。必要な場合は、保護された変数によって SSH キーをランナーに渡せます。

非公開キーをリポジトリ変数として受け渡す場合、次のようなセキュリティ上のリスクがあります。

  • パイプライン ビルドが子プロセスを生成する場合は、リポジトリ変数がその子プロセスにコピーされる。

  • セキュアな環境変数は、リポジトリへの書き込みアクセスを持つすべてのユーザーが取得できる。

SSH キーをリポジトリ変数として絶対に再利用しないことをお勧めします。Pipelines 用の新しい SSH キーペアを生成して、侵害された場合にキーを無効にできるようにします。デプロイ権限と併用できるデプロイ変数によって、アクセスを制御できます。詳細は「変数とシークレット - デプロイ変数」をご参照ください。

セキュアなリポジトリ変数を OpenSSH で使用して SSH キーを追加するには、次の手順に従います。

  1. ターミナルで次のような新しい SSH キーを生成します。

    1 ssh-keygen -t rsa -b 4096 -N '' -f ~/.ssh/my_ssh_key
  2. 非公開キーを base64 にエンコードします。現在、Pipelines では環境変数の改行はサポートされていません。次に例を示します。

    1 base64 -w 0 ~/.ssh/my_ssh_key
  3. エンコードされたキーを保護された変数として追加します。暗号化されたキーをターミナルからコピーして、次のようにセキュアな Bitbucket Pipelines 環境変数としてリポジトリに追加します。

    1. Bitbucket のリポジトリで、[リポジトリ設定] > [リポジトリ変数] の順に選択します。

    2. ターミナルで、base64 エンコード済みの非公開キーをコピーします。

    3. エンコード済みのキーを環境変数の値としてペーストします。[セキュア] が選択されていることを確認します。

  4. 公開キーをリモート ホストにインストールします。Pipelines がそのホストを認証できるようになる前に、リモート ホストに公開キーをインストールする必要があります。Pipelines ビルドに他の Bitbucket リポジトリに対するアクセス権を付与する場合は、公開キーをそのリポジトリに追加する必要があります。

    SSH によってリモート ホストに公開キーをコピーするには、ssh-copy-id コマンドを使用します。このコマンドは、キーをリモート ホスト上の ~/.ssh/authorized_keys ファイルに追加します。

    1 ssh-copy-id -i my_ssh_key <username>@<remote_host>

    <username> はリモート ホスト上のユーザーです。

    サーバーへの SSH アクセスをテストするには、次の手順に従います。

    1 ssh -i ~/.ssh/my_ssh_key user@host
  5. ホスト キーを取得して、ホスト VM (仮想マシン) の ~/.ssh/known_hosts ファイルに追加します。
    known_hosts ファイルには、ユーザーがアクセスする SSH サーバーの DSA ホスト キーが格納されます。適切なリモート ホストに接続していることを確認することが重要です。

    1. 任意のリモート サーバーの DSA ホスト キーを取得します。これを行うには、次のコマンドを実行します。

      1 ssh-keyscan -t rsa server.example.com
    2. これらのキーをホスト仮想マシンの ~/.ssh/known_hosts ファイルに追加します。無関係な行はすべて削除できます。

  6. SSH キーを bitbucket-pipelines.yml ファイルに追加してデコードします。次に例を示します。

    1 2 3 4 5 6 7 pipelines: default: - step: runs-on: self.hosted script: - (umask 077 ; echo $MY_SSH_KEY | base64 --decode > ./id_rsa) - ssh -i ./id_rsa <user>@<host> 'echo "connected to `host` as $USER"'

上記のスクリプトでは、~/.ssh/another_private_key ではなく ./id_rsa を代用します。これによって、ランナーはランナーのビルド フォルダーに生成されたファイルを監視して、ステップの最後にそのファイルの削除を試みます。ランナーのビルド フォルダー外に作成されたファイルは削除されず、ランナーは非公開キーを ~/.ssh に残すので、この場合はキーが悪用される可能性が高くなります。

ビルド フォルダーをクリーン アップできない可能性はまだあります。いかなるデータが侵害される可能性も減らすため、このステップで用いた SSH キーペアを定期的に更新することをお勧めします。

 

その他のヘルプ