「みんなの翻訳」は、世界中の文書をみんなで協力して翻訳するサイトです。

みんなの翻訳ロゴ
ブクタブ
翻訳サイト

カテゴリ一覧

このサイトについて 新規登録はこちら お試し翻訳

一覧

2017/07/28

メンテナンス終了のお知らせ

2017/7/25-2017/7/28に実施したメンテナンスは、2017/7/28/14:20に終了いたしました。 ご協力をいただき、ありが…

List

Hnoss

English⇒Japanese

acai

English⇒Japanese

jhoo0509

English⇒Japanese

yoko

English⇒Japanese

ホーム > 翻訳記事

翻訳記事

【GitLab 公式 を訳してみた】GitLab Runner を設定する

 GitLab Documentation>GitLab Continuous Integration (GitLab CI)>GitLab Runnerを設定する

 

  GitLab CIにおいて、Runner(ランナー)とは「.gitlab-ci.yml」で定義したjobを実行する機関です。ランナーは独立した(仮想)マシンにインストールされます。これがjobを検出し、何が必要とされているかを抜き出してくれるのです。

  ランナーは、1つのプロジェクト専用にしたり、複数のプロジェクトを処理するものにすることもできます。全てのプロジェクトを処理するランナーのことを、共有ランナーをいいます。

  セキュリティの心配さえなければ、GitLabランナーはGitLabとは別のマシンに入れた方が良いでしょう。
 GitLabランナーは機械のリソースを大きく消費します。
 詳しくは、GitLab稼働条件ページの『GitLab Runner』の章をご覧ください。

 

  共有ランナー VS プロジェクト専用 ランナー

  ランナーをインストールしたら、その次に”登録”する工程があります。ここで、そのランナーを共有ランナーにするか、プロジェクト専用にするかを選択します。共有ランナーとして登録する場合は、GitLabインスタンスに管理者権限でアクセスしている必要があります。

 それでは、共有ランナーとプロジェクト専用ランナー の違いを確認しましょう。

  • 共有ランナーには、どのプロジェクトにも共通して必要なjobが入っている。逆に言うなら特徴がない。ビルド工程に変わり映えのないプロジェクトをいくつも所有していて、そこに沢山のランナーを用意していても、ほとんど使いどころがない。このような場合、共有ランナーを用意して、ランナーを統合するとよいだろう。ランナーそのもののメンテナンスやアップデートも簡単になる。共有ランナーは複数のjobを、fair usage queue(後述)という仕組みで処理するため、大量のjob処理に適している。それに比べて、プロジェクト専用ランナーはFIFOキューを使っているため、jobが立て込むと、共有ランナーよりも多くのリソースを消費してしまう。
  • プロジェクト専用ランナーは、どうしてもそのプロジェクトでしか使わないjobを処理する際に効果的である。共有ランナーには入れたくないjob、滅多に使われないjobなどを、このランナーに任せるとよい。たとえば、似たようなビルド方法をとるアプリでも、デプロイ先には違いがあることだろう。プロジェクトをデプロイする際に、プロジェクト専用ランナーを使うと、より正しいデプロイ先に適切な方法で展開しやすくなる。「タグ」機能(後述)を使えば、アプリケーションごとに必要な処理を自動振り分けすることができるので、有効に使っていこう。プロジェクト専用ランナーは、jobの処理にFIFOキューを使っている。


 プロジェクト専用ランナーについては、そこでビルドさせるプロジェクトを限定した方が、効率的に扱えます。

共有ランナーは、どのようなプロジェクトでも必要なビルド要件を満たしたランナーです。プロジェクトで利用するには、「Settings ➔ CI/CD」からAllow shared Runnersオプションに許可を出して下さい。
 

  CI設定により高い自由度を求めるのなら、プロジェクト専用ランナーを使うとよいでしょう。そのランナーが他のプロジェクトでの流用が効くかどうかについては保証しませんが、プロジェクトをより完璧に自動化するにはこのランナーが有効です。

  ”プロジェクト専用ランナー”とは言いつつも、これは設定次第で、複数のプロジェクトから利用できるようになります。
 これはあくまで、「いくつかのプロジェクトで利用できる」専用ランナーという扱いです。「全てのプロジェクトに使える」わけではないので、共有ランナーとは言えません。

  専用ランナーは、プロジェクトをフォークしたところで、自動的に引き継がれないところには注意してください。CIの設定(jobs, allow shared, etc)のコピーだけが、レポジトリと一緒に引き継がれます。

 

  共有ランナーを登録する

  共有ランナーを登録する際には、GitLabインスタンスに管理者権限でアクセスしている必要があります。

 1.「admin/runners」ページで共有ランナーのトークンを取得します。
 (写真1)共有ランナー認証エリア

 2.ランナーを登録する

  共有ランナーは、GitLab 8.2からデフォルトで使用が許可されています。これを取りやめたいときには、各プロジェクトの「Settings ➔ CI/CD」ページから、「Disable shared Runners」をクリックしてください。
 それ以前のGitLabについては、共有ランナーの使用がデフォルトで否定されています。

 

  プロジェクト専用ランナーを登録する

  専用ランナーの登録方法は、主に2つあります。

  1. プロジェクトの認証トークンから登録する 
  2. 共有ランナーを(管理者権限が必要)専用ランナーに転換させる


 

 プロジェクトの認証トークンから登録する

  GitLabのインスタンスから、権限の認証を通過せずに、特定ランナーのトークンを作成するには、

  1. プロジェクトの「Settings ➔ CI/CD」に移動
  2. ランナーを登録する


 

  共有ランナーを専用ランナーに転換させる

  GitLabインスタンスに管理者権限でアクセスできる方なら、どの共有ランナーもプロジェクト専用ランナーに変えることができます。(一般ユーザーには不可能)
 権限がない方でも、「こういう方法もある」と分かっているだけで、チームでの提案に差が出てきますよ。

  1. 管理者エリアから、「Overview ➔ Runners (/admin/runners)」に移動して、希望のランナーを探す。
  2. Restrict projects for this Runner」という項目から、どのプロジェクトにランナーを使わせるかを選択する。


 以上の方法で、共有ランナーを専用ランナーに変化させられます。

 

  ”プロジェクト専用ランナー”を複数のプロジェクトで使用可能にする設定

  プロジェクト専用ランナーは、設定次第で複数のプロジェクトでも利用できるようになります。
 この設定をしないでいると、他のプロジェクトでの使いまわしが一切できません。
 結果、いくつもの専用ランナーがぶちぶちと無駄に増殖していく原因になります。

 設定は、ランナーを登録する際にも受け付けられますし、あとから各ランナーの設定で変更をかけることもできます。
 

  ランナーの流用を許可する(取りやめる)方法:

  1. プロジェクトの「Settings ➔ CI/CD」に移動
  2. 設定を加えたいランナーを選択する
  3. 鉛筆マークをクリックする
  4. Lock to current projects」にチェックを入れる
  5. Save changes」をクリックして変更を適用


 専用ランナーが使えるプロジェクトを追加する

  上の操作で作成したランナーに、こんどはプロジェクトを追加していきます。
 ただし、この操作をするには、プロジェクトのマスターであることが必要です。

  プロジェクトで専用ランナーが使えるようにする手順:

  1. プロジェクトの「Settings ➔ CI/CD」に移動
  2. 利用可能な専用ランナーの中から、使いたいものを選ぶ
  3. Enable for this project」「Disable for this project」の2択がある。どちらか正しい方を選ぶこと。

 

注:プロジェクト専用ランナーを複数プロジェクトに開放している限り、皆さんのプロジェクトのマスター権を持っているユーザーならば誰でも、あなたの同意なしに専用ランナーを使えてしまいます。十分ご注意ください。


 

  保護ランナー

  GitLab 10.0より導入

  ランナーの情報が、あまり外部に公開されたくない場合に使います。 保護されたランナーがビルドできるjobは、保護ブランチ または保護タグのプロジェクトで作成されたjobのみです。保護されていないプロジェクトについては、jobを実行しません。

  ランナーの保護/非保護を設定するには:

  1. プロジェクトの「Settings ➔ CI/CD」に移動
  2. 設定を加えたいランナーを選択する
  3. ランナー名横の鉛筆マークをクリックする
  4. Protected」にチェックを入れる。または外す。
  5. Save changes」をクリックして変更を適用


 (写真2)「Protected」の欄

 

  手動でランナーのキャッシュをクリアする

  GitLab 10.4以降に導入

  GitLab ランナーは、キャッシュをjobの処理速度向上のために使います。処理の過程で何度も使うデータについては使いまわすようにしているのです。ところが、時としてそれがランナーの誤作動の引き金になることがあります。

  キャッシュはGitLabのUIから削除することができます。何か動作不良が起きた時に試してみてください。

  1. プロジェクトの「CI/CD > Pipelines」に移動
  2. Clear Runner caches」をクリック
  3. 次回のプッシュから、CI/CD jobは新しいキャッシュを使用するはずです。


 なお、キャッシュをクリアしても、「.gitlab-ci.yml」に設定したキャッシュキーが変更されることはありません。また、キャッシュキーを手動で変更することがさらに誤作動を招くことがありますので、変更しないでください。
 

  上の工程を実行すると、GitLabランナーのバックグラウンドが、データベースから必要なデータを集めて、もう一度新しいキャッシュキーを作り始めます。次のプッシュから新たなキーが使われて、以前のキーは使用不可になります。
 この段階では、まだ古いキーは残存していますが、じきにランナーのガベージコレクターによって、ファイルシステムごと除去されるでしょう。

 

  共有ランナーのjob検出方法(fair usage queue)

  共有ランナーでは処理の順位付け(キュー)に「fair usage」という仕組みを採用しています。
 これにより、ランナーに複数のプロジェクトがほぼ同時にビルドの申請があった場合は、共有ランナーはそれぞれのプロジェクトで最初にしなくてはならないjobから順番に実施していくようになっています。

 例1

  次のjobを実施することになっている場合

  • Project 1 に Job1
  • Project 1 に Job2
  • Project 1 に Job3
  • Project 2 に Job4
  • Project 2 に Job5
  • Project 3 に Job6


 共有ランナーのアルゴリズムは、このようにjobを処理します。

  1. Job 1     全てのプロジェクトの中で、最もjobの数字が小さい。最初に選ばれる。 
  2. Job 4    Project 2 の中では、最もjobの数字が小さい。Project 1 のjobは既に実施されてしまっていることから、これが次に選ばれる。
  3. Job 6    Project 3 の中では、最もjobの数字が小さい。Project 1,2 のjobは実施されていることから、これが次に選ばれる。
  4. Job 2    Project 1 の中では、次にjobの数字が小さい。
  5. Job 5    Project 2 の中では、次にjobの数字が小さい。
  6. Job 3    全てのプロジェクトのjobを均等に処理してきたため、これが最後となる。

 

 例2

  • project 1 に Job1
  • project 1 に Job2
  • project 1 に Job3
  • project 2 に Job4
  • project 2 に Job5
  • project 3 に Job6 


 この場合、共有ランナーのアルゴリズムは、次のようにjobを処理します。
 

  • Job 1    全てのプロジェクトの中で、最もjobの数字が小さい。最初に選ばれる。
  • 何らかの理由でjob1はすでに終了していた。
  • Job 2    ランナーはまだ一つもjobを処理できていない。この場合、次にjobの数字が小さいものが実施される。
  • Job 4    Project 2 の中では、最もjobの数字が小さい。Project 1 のjobは既に実施されたことから、これが次に選ばれる。
  • job 4も何らかの理由で終了していた。
  • Job 2    ランナーはまだProject 2のjobを処理できていない。この場合、同じプロジェクト内で次にjobの数字が小さいものが実施される。
  • Job 6    Project 3 の中では、最もjobの数字が小さい。Project 1,2 のjobは実施されていることから、これが次に選ばれる。
  • Job 3    全てのプロジェクトのjobを均等に処理してきたため、これが最後となる。(ワンは、なんじょうさむしい数さ~♪という古い歌があったけど、この方式でいくとそうでもない。)


 

  共有ランナーをより効果的に使う

 共有ランナーをより多くのプロジェクトに対応させるには、これから説明するいくつかのワザが欠かせません。

 

  タグを使う

  実際、プロジェクトでランナーをまともに使っていこうと考えると、ランナーは様々なタイプのjobに対応できなくてはなりません。この課題を放置すると、プロジェクトを共有する段になれば、ますます大きな問題として直面することになるでしょう。
  大量のプロジェクトを目の前に、何の分類もかけずに放置しておくことは、作業の非効率化を招きます。そこで活用するのが、tagです。

    ランナーにタグをつけることで、実行するjobに分類を設けることができます。
 これにより、jobを必要なだけものだけに絞って実施することが可能になります。中でも大量のjobを設定している、共有ランナーなどの場合は、より大幅な削減が期待できるでしょう。

  たとえば、GitLabランナーでRailsのテストが実施できるようなコードをそろえてあった状態なら、ランナーに"rails"タグを設けるだけで適切なテストが行われるようになります。

 

  タグが付いていないjobのみを実行する

  先ほど、「タグがついているjobだけを実施できる」と述べましたが、その逆はできないのかと気になったと思います。これからその設定方法をお教えしますね。
 この設定は、ランナーを登録する際にも受け付けられますし、あとから各ランナーの設定で変更をかけることもできます。
 

  タグ付き/タグなし jobを抜き出して実行させる方法:

  1. プロジェクトの「Settings ➔ CI/CD」に移動
  2. 設定を加えたいランナーを選択して、稼働を許可する
  3. 鉛筆マークをクリックする
  4. Run untagged jobs」という選択肢にチェックを入れる
  5. Save changes」をクリックして変更を適用


  ランナーの脆弱性について

  一部のランナーエクゼキュータでは、ランナーでjobを実行すると、全てのコードにアクセスが図れて、ランナーのトークンを奪い取られてしまうことがあります。
 特に共有ランナーを奪い取られると、そのランナーに通される全てのコードが読み取られてしまうので、より危険です。

  皆さんはランナーのトークンにアクセスすることができます。それゆえにランナーをクローンすることもできるし、jobの失敗なども確認できるのです。
 このアプリの基本的な機能を構成している要素が、セキュリティリスクの元にもなっていることを、きちんとご理解ください。

 この脆弱性は、機能性を追い求める過程で生じてしまった欠点です。当面直せそうにありません。

 ですが、きちんと気をつけていれば、リスクを大幅に回避することができます。
 まず、1つ目。これは皆さんがお持ちの共有ランナーにアクセス制限をかけることです。ランナーにはいくつか種類があることは先ほどもお伝えしました。その中でも共有ランナーは、デフォルトでアクセスに制限がかけられていません。これが主な弱点になります。GitLabのインスタンスから、アクセスに制御をかけてください。
 2つ目が、よりセキュリティ性が高いランナーエクゼキュータを採用することです。

(訳者より: たとえば、Shellエクゼキュータの場合は、マシンの特権を使う機会が多いことから、プロジェクトのコードが盗み出される隙をつくりやすいと言われています。
 それから拙訳の文章に、Dockerなどのコンテナ類も特権が絡むと、Dockerを展開しているマシンを危険にさらしやすいことが記されていました。)

 

  フォーク

  プロジェクトをフォークする際には、同時にプロジェクトのjob設定がコピーされます。
 これがきっかけで、皆さんが作成したランナーが第三者によって利用される場合があります。

 たとえば、とあるプロジェクトのマスターが、1つの共有ランナーを使ってビルドするように設定していたとします。
 そのプロジェクトを誰かがフォークしました。もちろん、jobの設定は完全にコピーされているため、その共有ランナーを使用する設定も消えてはいません。よって、そのままビルドが実行されれば、最初のプロジェクトと同じランナーを使用することが十分あり得ます。

 

  GitLab ランナーにおける攻撃ベクトル

  上記の他にも、現在解決策を探している案件がいくつもあります。これに取り組むことで、ランナーがさらに改良されていくことは間違いありません。
 詳しくはSecurity Considerationsをご覧ください。皆さんのコントリビューションをお待ちしております。

 Edit this page

PDF
更新日:2018-03-23 21:52:28 Hnoss 0  del.icio.usに追加   はてなブックマークに追加   twitterに投稿   facebookでshare
[ 原文 ] https://docs.gitlab.com/ee/ci/runners/README.html 原文ページプロジェクト並びにドキュメントファイルは、MIT Licenseのもと公開されています。(URL:https://gitlab.com/gitlab-com/gitlab-docs/blob/master/LICENSE) この記事の文章は、訳者の判断によりCreative Commons BY (version 3.0) を適用するものとします。
翻訳者ページをみる

この記事の翻訳者

Hnoss さんの翻訳記事

[翻訳]GitLabハンドブック>エンジニアリング

現在の位置: チームハンドブック 目次 >エンジニアリング   連絡方法 Public Issue Tracker (GitLab CEの場合) ; 不特定多数に公開しては問題が発生するような一部の題材に…2018-05-26 00:10:26

[翻訳]GitLabハンドブック>UX部門

現在の位置: チームハンドブック 目次 >UX部門   UX ガイド  GitLabの見た目は、 UXガイド を基準に構成されている。このガイドが、わが社におけるデザインの原論、表現法、…2018-05-26 00:09:10

【GitLab 公式 を訳してみた】GitLab UX ガイド

GitLab Documentation > GitLab development guides >GitLab UX ガイド  現在、UX documentationの内容を、 design.gitlab.com projectに移行しております。この説明書の更新…2018-05-26 00:06:03

[翻訳]GitLabハンドブック>インフラストラクチャ>Gitaly チーム

現在の位置: チームハンドブック 目次 > インフラストラクチャ >Gitaly チーム   関連リンク Gitaly専用 パブリックイシュー トラッカー チャットチャンネル ;チャンネル…2018-05-24 18:53:54