このチュートリアルを用いて、https://concourse.ci の使い方とコンセプトをステップバイステップで学びましょう。
Vagrant/Virtualboxをインストールします。
このチュートリアルを取得して、さぁ始めましょう。
git clone git@github.com:nitky/concourse-tutorial.git
cd concourse-tutorial
vagrant up
ブラウザで http://192.168.100.4:8080/ を開いてください。
使用しているOSに応じたflyインターフェースをダウンロードします。
ダウンロードしたら, 実行ファイルfly を/usr/local/bin や ~/binなどの ($PATH)が通ったフォルダに入れてください。また、flyのファイルを実行可能にすることを忘れないでください。実行権限を与えるには、以下のコマンドを使用します。
sudo mkdir -p /usr/local/bin
sudo mv ~/Downloads/fly /usr/local/bin
sudo chmod 0755 /usr/local/bin/fly
いつも完全に同じ結果を得るために、fly はすべてのflyリクエストに対してAPIのターゲットを定めることを要求します。
まず、tutorialという別名を与えます。（この名前は全てのチュートリアルのラッパースクリプトとして使用されています）
fly --target tutorial login --concourse-url http://192.168.100.4:8080 sync
ここまでの操作によって、ローカルファイルの中に保存された Concourse APIのターゲットを見ることができます。
cat ~/.flyrc
APIや資格情報などの情報は以下のようなシンプルなYAMLファイルで表されます。
targets:
tutorial:
api: http://192.168.100.4:8080
username: ""
password: ""
cert: ""fly コマンドを使うとき、我々は fly -t tutorialと打つことで、このConcourse APIをターゲットにできます。
@alexsuraci: I promise you'll end up liking it more than having an implicit target state :) Makes reusing commands from shell history much less dangerous (rogue fly configure can be bad)
cd 01_task_hello_world
fly -t tutorial execute -c task_hello_world.yml
上のコマンドを皮切りに、このようなログが出力されます。
Connecting to 192.168.100.4:8080 (192.168.100.4:8080)
- 100% |*******************************| 10240 0:00:00 ETA
initializing with docker:///busybox
Concourseにある全てのタスクは(目的のプラットフォームに最善な形の)"コンテナ"で実行されます。task_hello_world.ymlコンフィグレーションは、docker:///busyboxに定義されたコンテナイメージを使用するlinuxプラットフォームの上で実行させることを示しています。
このコンテナの中でecho hello worldコマンドを実行させましょう。
---
platform: linux
image: docker:///busybox
run:
path: echo
args: [hello world]出力の前の時点では、Docker イメージ busyboxのダウンロードを行っています。
ダウンロードはただ一回実行するだけでよく、実行時にはいつも最新のbusybox イメージがあるかどうかをチェックしてくれます。
さらに続けて行きましょう。
running echo hello world
hello world
succeeded
image: と run: を 違うタスクに変えて実行してみましょう。
---
platform: linux
image: docker:///ubuntu#14.04
run:
path: uname
args: [-a]このタスクファイルは便利に使えます。
$ fly -t tutorial execute -c task_ubuntu_uname.yml
Connecting to 192.168.100.4:8080 (192.168.100.4:8080)
- 100% |*******************************| 10240 0:00:00 ETA
initializing with docker:///ubuntu#14.04
running uname -a
Linux mjgia714efl 3.13.0-49-generic #83-Ubuntu SMP Fri Apr 10 20:11:33 UTC 2015 x86_64 x86_64 x86_64 GNU/Linux
succeeded
コマンドを直接実行するよりも、Concourse タスクはシェルスクリプトのラッパーであるrun: で実行することが一般的なパターンです。
タスクとラッパースクリプトを複雑なパイプラインの中に押し込めていく際は、次のようなルールを考えてみましょう。
- タスクファイルとラッパーシェルスクリプトに同じベースネームを与える
01_task_hello_world フォルダの中にある２つのファイルをみてください。
task_show_uname.ymltask_show_uname.sh
flyによってタスクファイルが直接実行されるとき、タスクの入力としてカレントフォルダがアップロードされます。これはラッパーシェルスクリプトが実行に利用できることを意味しています。
$ fly -t tutorial execute -c task_show_uname.yml
Connecting to 192.168.100.4:8080 (192.168.100.4:8080)
- 100% |*******************************| 10240 0:00:00 ETA
initializing with docker:///busybox
running ./task_show_uname.sh
Linux mjgia714eg3 3.13.0-49-generic #83-Ubuntu SMP Fri Apr 10 20:11:33 UTC 2015 x86_64 GNU/Linux
succeeded
上記の出力であるrunning ./task_show_uname.shは、task_show_uname.ymlタスクがラッパーシェルスクリプトにタスクの仕事を任せたことを示しています。
task_show_uname.yml タスクは次のようになっています。
platform: linux
image: docker:///busybox
inputs:
- name: 01_task_hello_world
path: .
run:
path: ./task_show_uname.shここで、新たに示されたコンセプトinputs:を説明します。
タスクがラッパースクリプトを実行するためには、ラッパースクリプトへアクセス方法を与えなければいけません。 同様に、タスクがデータファイルを処理するためには、データファイルへアクセス方法を与える必要があります。
Concourseにおいて、それらはタスクのためのinputsになります。
flyによって直接タスクが実行させることで、01_task_hello_worldの中にある私たちのホストマシンから実行された後、
現在のホストマシンのフォルダがConcourseにアップロードされ、01_task_hello_worldと呼ばれる入力が利用可能になります。
そして入力に伴うジョブを見た後で、ジョブ内部のタスクへの入力を通じてタスクと出力は返されます。
上に示したinputsのスニペットについて考慮すると、
inputs:
- name: 01_task_hello_world
path: .これらは次のことを言っています。
- 私は
01_task_hello_worldと呼ばれる入力フォルダを受け取りたい。 - 私はそれを
.フォルダに置きたい。(.は実行されるとき、タスクのルートフォルダとみなされる)
デフォルトでは、path:に何もなかった場合、入力自身と同じ名前のフォルダに置き換えられます。
inputsのリストが与えられたとき、（同じフォルダの中にある）task_show_uname.shスクリプトが実行タスクのルートフォルダの中で利用可能になります。
これは、次のような実行を許可します。
run:
path: ./task_show_uname.shcd ../02_job_hello_world
fly set-pipeline -t tutorial -c pipeline.yml -p 02helloworld
fly unpause-pipeline -p 02helloworld
これらはコンコースのパイプライン（と変更点がないこと）を表示し確認を求めます。
jobs:
job job-hello-world has been added:
name: job-hello-world
public: true
plan:
- task: hello-world
config:
platform: linux
image: docker:///busybox
run:
path: echo
args:
- hello worldfly set-pipeline (もしくは fly sp)を実行するたび、なにも変更がないことの確認を承諾するプロンプトが表示されます。
apply configuration? (y/n):
yを押してください。
次のようなメッセージが表示されるはずです:
pipeline created!
you can view your pipeline here: http://192.168.100.4:8080/pipelines/02helloworld
ブラウザに戻ってジョブを手動で始めましょう。job-hello-worldをクリックした後、右上隅にある大きな+をクリックしてください。
ジョブが実行されます。
左上隅の"Home"アイコンをクリックすると、パイプラインのステータスが表示されます。
前に示したpipeline.ymlの中にあるコンフィグレーションによってジョブのタスクは簡単に繰り返すことができます。しまいには、すでに外へ出したリソースのジョブタスクを同じ場所に配置したくなるのかもしれません。
これは少し複雑な"hello world" タスクの例ですが、私たちが実行したいタスクが事前に示した"01 - Hello World task"からのものであると仮定しましょう。 それはgitリポジトリに保存されています。
pipeline.ymlの中へ、チュートリアルのgitリポジトリにリソースとして加える。
resources:
- name: resource-tutorial
type: git
source:
uri: https://github.com/starkandwayne/concourse-tutorial.git今、私たちはジョブをリソースとして消費することができます。アップデートしましょう。
jobs:
- name: job-hello-world
public: true
plan:
- get: resource-tutorial
- task: hello-world
file: resource-tutorial/01_task_hello_world/task_hello_world.yml最初のgetはresource-tutorialというリソースを得るために必要だ、と私たちのplan:で明示されています。
次に、タスクコンフィグレーションであるresource-tutorialから01_task_hello_world/task_hello_world.ymlのファイルを使用します。
fly set-pipeline -t tutorial -c pipeline.yml -p 03_resource_jobを用いてパイプラインのアップデートを承認しましょう。
脚注: fly は楽にコマンドが打てるように短いエイリアスがある。fly sp が fly set-pipelineと省略できるように。
あるいは、チュートリアルによって事前に構築されたパイプラインを実行してみましょう。
cd ../03_resource_job
fly sp -t tutorial -c pipeline.yml -p 03_resource_job
fly unpause-pipeline -t tutorial -p 03_resource_job
UIでジョブを手動実行した後、出力はこのようになります。
job-hello-world で定義されたビルドプランのジョブには二つのステップがあります。
一つ目のステップは、gitリポジトリからトレーニング教材とチュートリアルを取得することです。この"リソース"はresource-tutorialと呼ばれています。
このリソースはどんなジョブのビルドプランを含むタスクでも入力とすることができます。
二つ目のステップは、ユーザ定義のタスクを実行することです。UIの出力に表示された、タスク名hello-worldが与えられます。タスク自身は
パイプラインの中で記述されません。その代わり、resource-tutorialの入力によって01_task_hello_world/task_hello_world.ymlの中に記述されます。
パイプラインの外側に出して、YAMLファイルの中にタスクを記述することは利点と欠点がそれぞれあります。
利点は、作用するインプットリソースとマッチするようにタスクの振る舞いを修正できることが挙げられます。例えば、もし入力リソースがテスト付きのコードリポジトリであるならば、コストを実行するためにどのようなコードがリポジトリに必要なのかタスクファイルと同期を保ち続けることができます。
欠点は、pipeline.ymlがどんなコマンドを実行するのかを正確に記述しないことです。ファイルから理解できることが減るということです。
pipeline.ymlファイルが長くなればなるほど、全てのYAMLを読んで理解することは困難になるかもしれません。
これらの選択をする場合、他のチームメンバの理解を考える必要があります。「このパイプラインは実際何をするんだ！」
ひとつのアイデアはタスクファイルの名前付けをどうするか考慮することです。例えば、ラッパースクリプトの実行内容によって名前付けを行うのも良いかもしれません。
その目的と振る舞いを説明する（長い）名前を使うことを考えましょう。
大切なことはpipeline.ymlを読めるように作ることです。それはチーム/会社/プロジェクトの中で重要なオーケストレーションのツールになるでしょう。誰もがどのように、それが実際どう動作するのかを知っているベキです。
job-hello-world はgitレポジトリとタスクの実行で取って来られたリソースからのターミナル出力を持ちます。
また、ターミナルでflyを実行すると、このような出力を見ることができるでしょう。
fly -t tutorial watch -j 03_resource_job/job-hello-world
出力は次のようになるでしょう。
Cloning into '/tmp/build/get'...
e8c6632 Added trigger: true to autostart both jobs after update.
initializing with docker:///busybox
running echo hello world
hello world
succeeded
vagrant中のConcourseは http://192.168.100.4:8080で実行中のAPIがある。デフォルトでflyはこのエンドポイントをターゲットにします。
そのAPIを使って実行させることで、ジョブを起動することができる。例えば、curl:を用いて
curl http://192.168.100.4:8080/pipelines/03_resource_job/jobs/job-hello-world/builds -X POST
上のコマンドを実行するとき、fly watchを用いることで、上のコマンドターミナルの出力を見ることができる、
fly -t tutorial watch -j 03_resource_job/job-hello-world
"ソースは毎分チェックされるが、ビルドが実行されるべきとき、それを決定するための少しのインターバル（10秒）がある。時間リソースは、おおよそ周期的にビルドが実行されることを保証する必要がある。これらのことを用いて、例えば私たちはダメなところを見つけ出すために、インテグレーション／アクセプタンスのテストを継続的に実行する" - アレックス
最終的な結果は、2mのタイマーが毎度2分から3分の間に起動するということです。
https://github.com/concourse?query=resource
- bosh-deployment-resource - パイプラインの一部として構成されたboshリリースのデプロイ
- semver-resource - セマンティックバージョンの自動更新
- bosh-io-release-resource - bosh.io上のリリースバージョンの追跡
- s3-resource - AWS S3 に関するConcourseのリソース
- git-resource - gitリポジトリの中のコミットの追跡
- bosh-io-stemcell-resource - bosh.io上のstemcellのバージョンの追跡
- vagrant-cloud-resource - manages boxes in vagrant cloud, by provider providerによるvagrant cloudのボックスの管理
- docker-image-resource - dockerイメージ用リソース
- archive-resource - uriからのダウンロードとアーカイブ(今のところtgz)の展開
- github-release-resource - githubリリースのためのリソース
- tracker-resource - pivotal trackerのリソース出力
- time-resource - 定期的にトリガーを引くためのリソース
- cf-resource - Cloud Foundryに関するConcourseのリソース
コンコースでどのようなリソースが利用可能かは、APIエンドポイント /api/v1/workers:で探し出すことができる。
$ curl -s http://192.168.100.4:8080/api/v1/workers | jq -r ".[0].resource_types[].type" | sort
archive
bosh-deployment
bosh-io-release
bosh-io-stemcell
cf
docker-image
git
github-release
s3
semver
time
tracker
vagrant-cloud