【GitLab 公式 を訳してみた】Dockerイメージを使う

法律: IT 解説記事 GitLab CI コンテナ WordPress フノス(訳者)

GitLab Documentation>GitLab Continuous Integration (GitLab CI)>Dockerをインテグレーションに活用する>Dockerイメージを使う

>Docker Runnerを登録する
>「image」とは
>「service」とは
  >サービスをjobと連携させる方法
  >サービス・コンテナへのアクセス
>「.gitlab-ci.yml」から「image」と「services」を決定する
>Docker拡張設定オプション(原:Extended Docker configuration options)
  >「image」で使える設定オプション
  >「services」で使える設定オプション
  >同じイメージ内で様々なサービスコンテナを展開する
  >サービスコンテナ向けにコマンドを設定する
  >イメージのエントリーポイントを優先させる
>「config.toml」ファイルで「image」と「services」を定義する方法
>プライベート・コンテナレジストリから「image」を定義する
>サービスをより細かく設定する
  >PostgreSQLサービス設定例
  >MySQLサービス設定例
>Dockerインテグレーションの作動順序
>jobをローカル環境でデバッグする方法
 

  GitLab CIは、GitLab ランナーと連携して、Dockerエンジンをアプリケーションのテストやビルドの道具に変身させます。また、様々なアプリケーションに対応できる実用性も兼ね備えています。

  Dockerとは、オープンソースのコンテナ作成ツールです。
 「コンテナ」という、単一のLinuxとほぼ同じ動きを取る隔離環境を作ることができます。アプリケーションを運営する上でとても便利なアイテムです。
  Docker Hubというページには、既にビルドが完了しているイメージが大量に掲載されています。これらをアプリケーションのテストやビルドに使うことができます。

  DockerをGitLab CIと併用した場合、CIが抱えるそれぞれのjobは、コードを記述するときに使用しているものとはまた別の定義済みコンテナによって実行されます。
 

  CIは「.gitlab-ci.yml」というファイルで設定します。セットアップ自体は簡単です。
 これにより設定されたCIコンテナは、10年ほど前なら我々が手作業で構築していたはずの「ビルド環境」というものを、ほとんど完璧に再現します。
 設定によっては、ビルドを終えたアプリケーションを、そのままワークステーションに提出することが可能です。

 皆さんは全てのコマンドを試験するときなどに、あらかじめ細工しておいたシェルを用いて、その合否を確かめていたことでしょう。ですが、そこを専用のCIサーバーに集約することで、様々な工程を一本化できます。

 

  Docker Runnerを登録する

  GitLabランナーをDockerで運用する場合、dockerエグゼキューターにランナーを登録する必要があります。

  たとえば、簡単な例でいけば以下のような設定をします。

======================
sudo gitlab-runner register \
  --url "https://gitlab.example.com/" \
  --registration-token "PROJECT_REGISTRATION_TOKEN" \
  --description "docker-ruby-2.1" \
  --executor "docker" \
  --docker-image ruby:2.1 \
  --docker-postgres latest \
  --docker-mysql latest
======================
 (訳者より:¥はバックスラッシュの誤変換です。)
 

  この設定で登録できるランナーは、「ruby:2.1」Dockerイメージです。
 このDockerでは2つのサービスを抱えております。1つめは、「postgres:latest」もう1つが「mysql:latest」で、ここに書かれたということは、どちらもビルドプロセスでアクセス可能な状態になり、プロセスを完成させるのに欠かせない役割を担っているということです。

 

  「image」とは

  Dockerを使っていく上で欠かせないキーワードが「image」です。これはどのような種類のDockerコンテナを使っていくかを定義するパラメータです。
 とりわけ今回は、CIの設定をしていますので、定義されたイメージは、CIタスクを実行するのに使われます。

  デフォルトでは、Docker Hubから引いてきたイメージ以外は使われないように設定されていますが、
gitlab-runner/config.toml」というファイルのDocker pull policyを変更することで、ローカル環境にあるDockerイメージなどが使えるようになります。

  Docker Hubの詳しい利用方法については、Docker Fundamentalsというガイダンスに従ってください。

 

  「service」とは

  「service」は、Dockerイメージを定義するもう1つのキーワードです。ここで定義されたサービスには、「image」で定義されたDockerイメージとランナーで実行されるjobとの間をリンクする役割があります。
 ここで定義されたサービス用Dockerイメージは、ビルドの際になって初めてアクセスが開始されます。

  「service」イメージはどのアプリケーションでも運用可能ですが、たいてい、ビルドにデータベースコンテナ(mysqlなど)が必要とされる時に使われます。
 CIでjobを達成するために、どうしてもすぐさま動かせるコンテナイメージが必要なことがあります。プロジェクトをビルドするたびにインストールしていた「mysql」などの追加コンテナは、ここに定義しましょう。

  よく誤解されがちですが、ここに定義できるのはデータベースだけではありあません。他にも様々なサービスを追加することができます。
 設定は「.gitlab-ci.yml」あるいは「config.toml」にしてください。 Docker Hub /ローカル環境のコンテナイメージを指定するだけで、サービスコンテナが利用できるようになります。

  こちらの 『CIサービス設定例』というページでは、ビルド環境にサービスコンテナを設置する具体的な方法が紹介されています。

 

  サービスをjobと連携させる方法

  コンテナをリンクさせる方法については、Docker公式によるLinking containers togetherをお読みいただいた方が良ろしいでしょう。

  かいつまんでいえば、「mysql」をサービスとして追加した場合、Dockerイメージはjobとリンクしたサービスコンテナを使うようになるという話です。

  この場合「MySQL」コンテナがjobとリンクするようになります。デフォルトでのホスト名は「mysql」となっており、これがイメージによるサービスコンテナアクセス時に使われます。
 ホスト名は「musql」の他にも「socket」「localhost」という名前に変更できます。詳しくは、『サービス・コンテナへのアクセス』をご覧ください。


 

  サービス・コンテナへのアクセス

  サービスコンテナとして扱えるものは、データベースをだけではないと、先ほども述べました。
 サービスコンテナをもっと柔軟に活用することで、みなさんのAPIを手軽に拡張することができます。

 たとえば、Wordpressの拡張機能を作っており、テストをする必要があるとします。
 すると、サービスコンテナにwordpressを指定しておくという使い方が想定されます。

  まず、「.gitlab-ci.yml」に以下の設定を記述して、 tutum/wordpressイメージを立ち上げます。

======================
services:
 - tutum/wordpress:latest
======================

 

  tutum/wordpressにアクセスする時に使われるホストネームは以下の2つです。どちらかを選んでください。(サービスコンテナにエイリアスを設けてjobを実行したい場合は、別の設定が必要です。)

 注:アンダースコア_を使ったホストネームは、RFCで認識されません。外部アプリケーションと連携する際に支障をきたす可能性があります。

  サービスコンテナのホスト名には、以下のルールに則って、なるべくコンテナの名前を連想しやすいエイリアスが設定されています。

  以上はあくまでデフォルトの設定です。このほかにも、サービスコンテナに特定のエイリアスを設けることもできます。それにつきましては、同文「「services」で使える設定オプション」にて説明します。


 

  .gitlab-ci.yml」から「image」と「services」を決定する

  実際にアプリケーションをビルドする時に、「images」と「services」を指定する時には、「.gitlab-ci.yml」ファイルから設定します。

 すべてのjobで同じイメージとサービスを使うときには、以下のような設定を加えます。

======================
image: ruby:2.2

services:

  - postgres:9.3 

before_script

  - bundle install

test

  script:

  - bundle exec rake spec
======================

  また、jobごとに異なるイメージとサービスを設けることも可能です。

======================
before_script:

  - bundle install

 

test:2.1

  image: ruby:2.1

 services

  - postgres:9.3

 script

  - bundle exec rake spec

 

test:2.2

  image: ruby:2.2

  services:

  - postgres:9.4  

  script:

  - bundle exec rake spec
======================

 

  あるいは、これから説明する拡張設定機能をイメージとサービスの設定に使ってみてもよいかもしれません。

======================
image:

  name: ruby:2.2

  entrypoint: ["/bin/bash"]

 

services:

 - name: my-postgres:9.4

   alias: db-postgres

   entrypoint: ["/usr/local/bin/db-postgres"]

   command: ["start"]

 

before_script:

- bundle install

 

test: 

   script:

  - bundle exec rake spec
======================


 

  Docker拡張設定オプション(原:Extended Docker configuration options)

  GitLab、GitLab Runner 9.4にて導入。

  「image」や「services」をさらに細かく具体的に指定したいときに、ストリングかマップ機能が使えます。

ストリングでコンテナを指定する時には、imageのフルネームを使わなくてはならない。(フルネーム=イメージが「どのレジストリにあるか」という情報も含む。Docker Hub以外のレジストリからイメージをダウンロードする時などに使うとよい。)
 

マップでコンテナを指定する時には、「name」でイメージを指定するのと同じように、フルネームを指定する。
 

  これから、ストリングとマップを使った設定例を1つずつ紹介します。どちらも結果的には同じ設定になっているので、どちらを好んで使うかの基準にしてください。

 ストリングで「image」「services」を指定する

======================
image: "registry.example.com/my/image:latest"

 

services:

- postgresql:9.4 

- redis:latest
======================

 

 マップで「image」「services」を指定する

======================
image:

  name: "registry.example.com/my/image:latest"

 

services:

- name: postgresql:9.4 

- name: redis:latest 
======================



  「image」で使える設定オプション

  GitLab、GitLab Runner 9.4にて導入。

  設定には上記のGitLabバージョンを満たしている必要があります。

 

設定オプション 必須か GitLab バージョン 説明
name 必須です。他のどのオプションとも併用できます。 9.4 これから使うimageのフルネーム。
必要に応じて正しいレジストリ情報を記載してください。
entrypoint no 9.4 コンテナの「entrypoint」で実行するコマンドやスクリプトを指定します。Dockerの「--entrypoint」に当たる機能を、ymlファイルの記述法に変換しました。構文としてはDockerfile's ENTRYPOINTとよく似ており、それぞれのシェルトークンは、別々のストリングとして機能するようになっています。

 

 

  「services」で使える設定オプション

  GitLab、GitLab Runner 9.4にて導入。

  設定には上記のGitLabバージョンを満たしている必要があります。

 

 

設定オプション 必須か GitLab バージョン 説明
name 必須です。他のどのオプションとも併用できます。 9.4 これから使うimageのフルネーム。
必要に応じて正しいレジストリ情報を記載してください。
 
entrypoint no 9.4 コンテナの「entrypoint」で実行するコマンドやスクリプトを指定します。
Dockerの「--entrypoint」に当たる機能を、ymlファイルの記述法に変換したので、このような設定オプションになりました。
構文としてはDockerfile's ENTRYPOINTとよく似ており、それぞれのシェルトークンは、別々のストリングとして機能するようになっています。
command no 9.4 コンテナのコマンドとして実行されるコマンド、あるいはスクリプト。

Dockerのargumentsに相当する機能。必ずimageのname指定の後に実行されます。

構文としてはDockerfile's CMD とよく似ており、それぞれのシェルトークンは、別々のストリングとして機能するようになっています。 
alias no 9.4 alias no 9.4 jobで必要とされるコンテナにアクセスする際に使われるエイリアスを追加します。
詳しくは、同文上の『サービス・コンテナへのアクセス』をご覧ください。
 

 

  同じイメージ内で様々なサービスコンテナを展開する

  GitLab、GitLab Runner 9.4にて導入。
 この機能を使いこなすには、まずは前章『Docker拡張設定オプション』を読んでおく必要があります。

  ここではDocker拡張設定オプションのさらに詳しい使い方を説明したいのですが、まずは絶対避けた方がよいコンフィグを紹介します。

======================
services:

 - mysql:latest

 - mysql:latest
======================

  なるほど「ランナーを起動したら、2つの『mysql:latest』コンテナを起動したかった」という気持ちだけならわかります。
  確かに、「mysql:latest」はデフォルトの状態での、mysqlコンテナ・ホスト名であることには違いありません。

 けれども、これは不適切な設定です。
 前の章ではかなり控えめにお伝えしましたが、ここに記述するコンテナ名は、それぞれのホスト名である必要があります。

 上のような設定をしてしまった場合、サービスコンテナのどちらか一方にしかアクセスが行き届かなくなることでしょう。

 ランナーというシステムは、コンテナをホスト名で見分けています。
 同じサービスを使っているコンテナが複数個ある場合は、それぞれにエイリアスをつけて、ランナー側がきちんと識別できるようにしておく必要があります。

  では正しい方法で、2つの「mysql:latest」を設置してみましょう。こちらです。

======================
services:

 - name: mysql:latest

   alias: mysql-1

 - name: mysql:latest

   alias: mysql-2
======================

  エイリアスは、皆さんが普段考えているDockerコンテナ名に数字を振るなど、簡単なもので構いません。ランナーが識別できさえすれば、サービスコンテナへのアクセスが正常に開始されるはずです。
 なお、この設定は「.gitlab-ci.yml」に記述します。サービスコンテナにアクセス障害が発生している場合は、このファイルに指定したコンテナ・ホスト名に重複がないかどうかを疑ってみてください。


 

  サービスコンテナ向けにコマンドを設定する 

  GitLab、GitLab Runner 9.4にて導入。
 この機能を使いこなすには、まず前章『Docker拡張設定オプション』(原:Extended Docker configuration options)を読んでおく必要があります。
 

  SQLデータベースにもいくつか種類がありますね。
 その中でも「super/sql:latest」イメージの使い方は、ちゃんとお伝えしなくてはなりません。

 このイメージは、「/usr/bin/super-sql run」というコマンドがないとデータベース業務を開始しません。そこで、サービスに対してコマンドを設置する操作が必須となります。

  ここで通常のDockerコンテナだったなら、CMDオプションを使って起動コマンドを設定します。たとえば、次のように。

======================
# my-super-sql:latest image's Dockerfile

 FROM super/sql:latest

 CMD ["/usr/bin/super-sql", "run"]
======================

  ところが、今回皆さんはGitLab CIを使っているので、「.gitlab-ci.yml」に設定をする必要があります。
 当然、表記はYAML記法です。
 CMDオプションは、「command: 」に変更になることにご注意ください。

======================
services:
 - my-super-sql:latest


services:

 - name: super/sql:latest

   command: ["/usr/bin/super-sql", "run"]
======================

   とはいえ、[ ]内の表記については、 Dockerfileの CMDと何ら変わりがありません。


 

  イメージのエントリーポイントを優先させる

  GitLab、GitLab Runner 9.4にて導入。

  この機能を使いこなすには、まずは前章『Docker拡張設定オプション』を読んでおく必要があります。
 

  jobでテストを実行する時などに、テスト用のデータベースやバイナリが必要な場合があります。そのようなときに「super/sql:experimental」というDockerイメージなどを使用することがあります。これも中にSQLデータベースが入っています。

  これから「/usr/bin/super-sql run」というコマンドを、エントリーポイントで実行する設定をご紹介します。

 これは、コンテナを開始する際に一切の追加オプションを使用せず、jobの実施にデータベースプロセスだけを実行します。
 この設定を使うには、イメージコンテナ自体にはエントリーポイントが存在しない、あるいはエントリーポイントを設置していても、シェルを開始する時点のみであることが大条件となります。その条件が守られていない場合は、ランナーが設定を読み取れません。
 
 

  まず、通常のDockerコンフィグなら、次のようになることがイメージできますか。

======================
# my-super-sql:experimental image's Dockerfile

 FROM super/sql:experimental

 ENTRYPOINT ["/bin/sh"]
======================

  これらがYAML記法に合わせた表記になります。
 「.gitlab-ci.yml」に次の設定を施します。

======================
services:
 - my-super-sql:latest

 

 services:

  - name: super/sql:experimental

    entrypoint: ["/bin/sh"]
======================

  「ENTRYPOINT」が「entrypoint:」 に変更になりましたが、 [ ]内の記法は、 Dockerfileの ENTRYPOINTと同じです。

 

  config.toml」ファイルで「image」と「services」を定義する方法

  「config.toml」に[runners.docker]という項目を設けると、ランナーに実行させるDockerコンテナを一括で定義することができます。

======================
[runners.docker]
 

  image = "ruby:2.1"

  services = ["mysql:latest", "postgres:latest"]
======================

  このファイルに定義された「image」と「services」は、全てのjobで使われることになります。


 

  プライベート・コンテナレジストリから「image」を定義する

  注: 

 

  次の例では、「registry.example.com/private/image:latest」というDockerイメージを使うように設定します。
 このイメージは、プライベートレジストリに置かれているため、ログインが必要です。

  よって、自動的にログインするための設定もしていきます。

 

必要なデータ 設定ファイルでの表記
レジストリのありか registry.example.com
ユーザ名 my_username
パスワード my_password

 

  

  「registry.example.com」にアクセスするように設定するには、次の工程を踏んでいきます。

 

  1. まずは、DOCKER_AUTH_CONFIG という環境変数を設定する。それには次の2つの方法がある。
    • 1つめ-  ローカルマシン上のDockerコンテナにログインする方法

      ======================
      docker login registry.example.com --ユーザ名 my_username --パスワード my_password 
      ======================

      この内容を 「~/.docker/config.json」というファイルに保管する。
    • 2つめ- システムのキーストアからDockerクライアントに許可を出して、Dockerへのログインができるようにする方法。この場合でも「~/.docker/config.json」ファイルの読み込みが必要とされる。その準備として${username}:${password} のbase64-encodedバージョンを手動で作成する。

      ターミナルを開いて次のコマンドを実行する。

      ======================
      echo -n "my_username:my_password" | base64


      # すると、こんなかんじのが表示される。コピーしよう
      bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=
      ======================
  2. DOCKER_AUTH_CONFIG」という秘密変数を作成し、Dockerコンフィグレーションファイルには次のように設定する。
    ======================
    {
        "auths": {
          "registry.example.com": {
            "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ="
          }
        }
     }
    ======================

  3. さすがにこの設定は任意ですが、秘密変数「DOCKER_AUTH_CONFIG」に対して次のような設定をすると、Dockerから自動的にログアウト(docker logout)がなされる。レジストリへの不要なコンピューターアクセスを防ぐことができる。
    ===================== 
    docker logout registry.example.com
    ======================

  4. 上の3つの設定で「registry.example.com」に存在するどのコンテナイメージでも、imageやservicesに設定できるようになる。「.gitlab-ci.yml」に次の設定をすると…
    ======================
    image: my.registry.tld:5000/namespace/image:tag
    ======================
    my.registry.tld:5000/namespace/image:tag」というコンテナをイメージとして使用していることになっている。このコンテナが「registry.example.com」に存在していると考えてほしい。

  もっとたくさんのレジストリを使用したい場合には、2番の"auths" にハッシュを設けて、追加のレジストリを記述してください。


 

  サービスをより細かく設定する

  データベースではあまり珍しくない機能ですが、環境変数を使って、データベース名を変更したり、状況ごとにアカウント名をセットすることなどが可能な場合があります。

  GitLab Runner 0.5.0以上では、YAML定義変数でサービスコンテナに設定を加えることができます。

  イメージで使用できる環境変数は、それぞれのDocker hubページに記載されています。

  注:設定された環境変数は、全てのサービスコンテナに片っ端から適用されていきます。
現在のところランナーやコンテナには、どの環境変数が、どのコンテナに使われるものなのかを識別する機能はありません。

 

  PostgreSQLサービス設定例

  『PostgreSQLを使う』をご覧ください。

 

  MySQLサービス設定例

  『MySQLを使う』をご覧ください。

 

  Dockerインテグレーションの作動順序

  1.  サービスコンテナ(mysql, postgresql, mongodb, redis等)の作成
  2.  「config.toml」ファイルと、ビルドイメージのDockerfileで定義された全てのボリュームを保持するために、キャッシュ・コンテナが作成される。(上の例では、ruby:2.1がビルドイメージとされていた)
  3.  ビルドコンテナを作成して、全てのサービス・コンテナをビルドコンテナにリンクさせる
  4.  ビルドコンテナが業務を開始して、jobスクリプトがコンテナに送られてくる
  5.  jobスクリプトが実行される
  6.  「/builds/group-name/project-name/」内のコードが精査される
  7.  「.gitlab-ci.yml」に記述された全工程が実行される
  8.  ビルドスクリプトが全て正常に完了したかが検査される
  9.  ビルドコンテナとそれに関わる全てのサービスコンテナが削除される
     

  jobをローカル環境でデバッグする方法

 注:これから紹介するコマンドは、ルート権がなくとも実行できるものです。
通常のユーザーアカウントであれば、Dockerの操作はできるようになっています。

  まずは「build_script」という名前のファイルを作成します。

============================================
cat <<EOF > build_script
git clone https://gitlab.com/gitlab-org/gitlab-runner.git /builds/gitlab-org/gitlab-runner
cd /builds/gitlab-org/gitlab-runner
make

EOF
============================================

  上のコマンドで、GitLab Runnerレポジトリを作っています。
 レポジトリにはMakefileを収容しておきたいので、最後から2番目の行で「make」コマンドが記述されています。

  やり方に個人差はありますが、このコマンドは適用するプロジェクトをきちんと定義することが望ましいでしょう。

  そして、この「make」コマンドで具体的に何をするかについては、各プロジェクトで決定する方針です。
 

  次に、サービスコンテナを作ります。 

======================
docker run -d --name service-mysql mysql:latest
docker run -d --name service-postgres postgres:latest
======================

  これで2つのサービスコンテナが作られたはずです。それぞれ「service-mysql」「service-postgres」という名前がついていて、最新のMySQLとPostgreSQLを使用するように指定されています。
 そして、どちらもバックグラウンドで実行(-dオプション)されることになっています。
 

  最後に「build_script」を実行して、ビルドコンテナを立ち上げます。

============================================
docker run --name build -i --link=service-mysql:mysql --link=service-postgres:postgres ruby:2.1 /bin/bash < build_script
============================================

  このコマンドで、「ruby:2.1」イメージが2つのサービスと結びついた状態で作成されます。
 「--name build」とある通り、「build」という名前の付いたコンテナです。

 「build_script」については、Bash読み取りプログラムとしてSTDINを使用して、「build」コンテナ内で実行される見通しです。
 

  jobのテストが終了したら、これらのコンテナは用済みになります。コンテナの削除には次のコマンドを使います。

======================
docker rm -f -v build service-mysql service-postgres
======================

  (-f)とは『forcefully=強制的に』の頭文字です。これで「build」コンテナを削除します。
 それから(-v)で、コンテナによって作り出された全てのボリュームを削除します。これで残り2つのサービスコンテナも削除されます。
 

  Edit this page

 

2017-12-21 22:31:14 / Hnoss
原文サイトを表示
[ 原文 ] https://docs.gitlab.com/ee/ci/docker/using_docker_images.html
原文ページプロジェクト並びにドキュメントファイルは、MIT Licenseのもと公開されています。(URL:https://gitlab.com/gitlab-com/gitlab-docs/blob/master/LICENSE) この記事の文章は、訳者の判断によりCreative Commons BY (version 3.0) を適用するものとします。