1 - Concourse簡介

Concourse是由Pivotal贊助的開源CICD工具，以pipeline機制運行任務並保留執行的狀態。
一般情況下，用來配合PCF(Pivotal Cloud Foundry)使用。

pipeline：通過作業實現的資源流變化的結果可視化展現
能夠對pipeline配置進行版本控制，方便移植和恢復。
構建在容器中運行，隔離各個環境，避免不同環境之間相互污染情況發生。
在一個部署過程中可定義多個管道，管道之間相互隔離，並且可在yaml文件中完成所有配置。

1.1 Wiki

1.2 Samples

https://github.com/pivotalservices/concourse-pipeline-samples

2 - 核心概念

Concourse獨立抽象出Resource、Job以及Task模型。
Concourse的pipeline將Task、Job、Resource三者有機地結合起來，用yaml文件將Job和Resource集中配置，在容器中build（構建）。

Resource：帶版本的實體（外部依賴），比如git倉庫
Job：定義pipeline的行爲，對Resource進行get或put操作
Task：執行的基本單元，定義腳本的執行（Input/Output），可以被Job執行或者通過fly命令（concourse的cli）手動執行

2.1 任務（Task）

執行的基本單元，表現爲在一個全新啓動的容器中所運行的腳本。
容器已經經過了預處理，因此其中包含了一個輸入與輸出目錄，任務腳本可在這些目錄中運行。

任務在一個獨立的環境（比如容器）中執行腳本，該環境包含依賴的資源
任務由Job執行或由fly手動執行
可以認爲任務是一個函數，具有input和output
任務可能成功（0），也可能失敗

2.2 資源（Resource）

版本化資源的抽象位置，例如某個repository
也可以表示更抽象的概念，例如時間觸發器
資源的變更可被檢測（check）、獲取（pull down）以及發佈（push up）
不同的資源類型（例如Git、AWS S3或觸發器）可封裝用於pipeline的各種樣板代碼，爲Concourse的擴展提供了一個可適配的接口
在Job構建計劃的get或put步驟中使用資源

2.3 作業（Job）

作業(Jobs)是要執行的獲取 (get)、放置(put)和任務(task)步驟序列，確定作業的輸入和輸出。
一個作業計劃的執行實例被稱爲一次構建（Build），Concourse中的構建是可重複使用的，因爲其中的任務在新的容器中也將重新運行。
因此，構建的工作線程不會受到之前運行結果的變更所影響。
此外，如果某次構建失敗了，也可以通過一個名爲Fly的Concourse命令行工具在某個容器中再一次在本地運行，通過這種方式實現更快的開發週期。

由資源與任務構成，通過構建計劃（build plan）實現
可以由資源的變更所觸發，也可以選擇手動觸發（實現人工批准流程）
可以被認爲是一個具有input和output的函數，當新的input可用時，該函數會自動運行
一個作業可以依賴於上游作業的輸出，由此構成pipeline的功能
一個作業計劃的執行實例被稱爲一次構建（Build），構建是可以重複使用的
作業構建計劃中的所有任務都成功執行，構建才能成功，任一任務失敗，構建就失敗

2.4 管道(pipeline)

管道(pipeline)圍繞代表所有外部狀態的"資源"(resources)和"與它們交互的作業job"構建。
資源(Resources)用於表示源代碼(source code)、依賴項(dependenceis)、部署(deployments)和任何其他外部狀態。
資源類型(Resource Types)被定義爲管道本身的一部分，使管道更加自包含，並保持 Concourse 本身較小和通用，而無需求助於複雜的插件系統。

通過作業實現的資源流變化的可視化展現
在一個部署過程中可以定義多個管道，這些管道是相互隔離的

3 - 參數解釋

3.1 Resource

resources是在pipeline的job會使用到的對象，被列在pipeline配置文件的resoureces鍵上，會在job的get、put等地方被使用。
每一個resource的配置屬性包括name、type、source、check_every、tags。

- name 指明使用的resource名稱，必填項。
- type 表明resource的類型，必填項。
- source 選填項，指定resource 的的多個屬性。對於Concourse來說是一個黑盒，隨着resource不同的類型而決定。常用項
- check_every 選填項，指定檢測新版本的間隔。默認值是1分鐘。
- tags 指定workers池中帶tag的workers進行這一步操作。

3.2 Jobs

Jobs用來指定pipeline的行爲、resources怎麼加入處理流程。
每個job的配置屬性包括name、serial、buildlogstoretain、serialgroups、maxinflight、public、disablemanualtrigger、interruptible、onsuccess、onfailure、ensure、plan。

- name 指明使用的job名稱，必填項。
- serial 指明build執行時是串行還是並行，默認值爲false。常用項
- build_logs_to_retain 賦予整數值，指定最新幾次的build日誌是否保留。
- serial_groups 設置所屬的tag，同一tag會按序執行。
- max_in_flight 指定同時執行的build數。
- public 指定build的日誌十分能被公開查詢，也就是不用用戶認證就能在UI上看到，默認是false。常用項
- disable_manual_trigger 默認設置爲false，當設置爲true就不能手動觸發job的執行。
- interruptible 默認爲false，如果設置爲true，worker會不等待build的完畢直接退出。
- on_success 當job執行成功時的處理步驟。
- on_failure 當job執行失敗時的處理步驟。
- ensure 設置時會不管job是否執行成功或者失敗。 
- plan 必填項，Build Plan執行的計劃任務。每個job都有一個單獨的build plan。

plan必填項中的配置屬性

- aggregate， 涉及get、resource
- task， 執行用戶定義的任務，涉及file（.yml文件格式）、params（參數）屬性，file指定工作內容對應的yml文件，取自resource下相關路徑
- get，獲得指定資源
- put，

3.3 Task

### platform 
platform 必填項，表明task的執行環境。
除了linux還有windows、darwin等。

### inputs 
inputs 必填項，指定該task期望獲得的輸入項
也就是指明向task傳遞輸入的文件
每個輸入項由以name、path兩個屬性來指定輸入。
- name是必填項，表示輸入的名稱。
- path是可選的，表示路徑。如果沒有指明path，輸入項的路徑就是input名。

### run
run 必填項，指定在容器內執行的命令。
run當中有path、args、dir、user。
- path 表示相應的命令的執行路徑，是必填項。其他三項都是選填。
- args 數組類型，每個通過 Fly 執行的pipeline時指定的參數都會添加到這個數組內。
- dir 用來設置執行腳本的工作目錄。
- user 顯現地設置執行命令的用戶，如果未指明，則取決於後臺Garden的設置。一般在linux下都是root來執行。

### output
output 選填項。命令執行產生的內容可以通過這個屬性來指定。
每一個輸出都有和輸入一樣的屬性類型。

4 - Fly命令

fly是Concourse的命令行工具（cli），可以從命令行管理Concourse實例

4.1 安裝

安裝fly在Local PC（win7 64bit）
下載安裝包： https://github.com/concourse/concourse/releases/download/
解壓後，將fly.exe加入到系統環境變量PATH

安裝配置完成後，運行fly -v命令查看版本是否與Concourse平臺版本一致。

如果不一致，在使用fly命令時，會出現告警信息，可能會影響命令執行結果。

4.2 縮寫與別名

運行fly -h或者fly -help獲得幫助信息。
從幫助信息中可以看到命令的別名，便於命令的書寫。

# abbreviation
-t    --target 
-p    --pipeline
-c    --config
-l    --load-vars-from
-v    --var
-p    --pipeline 
-j    --job
-b    --build

# aliases
up    unpause-pipeline     
dp    destroy-pipeline
gp    get-pipeline
sp    set-pipeline
ps    pipelines
js    jobs
tj    trigger-job
ab    abort-build 
bs    builds
w     watch

4.3 一些命令

# Login
fly --target <targetName> login --team-name <teamName> --concourse-url <concourseUrl>


# Set/update pipeline
fly --target <targetName> set-pipeline --pipeline <pipelineName> --config pipeline.yml --load-vars-from config.yml --load-vars-from credentials.yml --var test_var=test-value
fly -t <targetName> sp -p <pipelineName> -c pipeline.yml -l config.yml -l credentials.yml -v test_var=test-value
# Unpause pipeline
fly --target <targetName> up -p <pipelineName>
fly -t <targetName> up -p <pipelineName>
# Unpause job
fly --target <targetName> up -j <pipelineName>/<jobName>
fly -t <targetName> up -j <pipelineName>/<jobName>


# Trigger job
fly -t <targetName> tj -j <pipelineName>/<jobName>
# Trigger job and start watching the log
fly -t <targetName> tj -j <pipelineName>/<jobName> -w


# Abort the job build
fly -t <targetName> ab -j <pipelineName>/<jobName> -b <buildNumber>
# Destory pipeline
fly -t <targetName> dp -p <pipelineName>


# List pipelines
fly -t <targetName> ps
# List jobs
fly -t <targetName> js -p <pipelineName>
# List all the job building history 
fly -t <targetName> bs -p <pipelineName>
# List job building history 
fly -t <targetName> bs -j <pipelineName>/<jobName>


# check pipeline resource
fly -t <targetName> resources -p <pipelineName>
# check resources log
fly -t <targetName> check-resource -r <pipelineName>/<resourceName> --watch


# Show the job build logs
fly -t <targetName> w -j <pipelineName>/<jobName> -b <buildNumber>
# List jobs detail  ???js???
fly -t <targetName> gp -p <pipelineName> js

4.4 Cheat-Sheet

4.5 Check pipeline

### How to check the pipeline 

Step-1:  ` fly  -t <target Name> up -p  <pipeline Name> `

Step-2 Checking Current builds under job:  
 `fly  -t <target name> builds –j <concourse pipeline name>/<concourse job name>`

Step-3 abort the previous pending builds then re-run job:  
`fly –t <target name> ab –j <pipeline name>/<concourse job> -b <build number>`

Step-4 checking pipeline Resource if Step3 has no any pending builds:           
 ` fly  -t <target Name>  resources -p <pipeline Name>`

Step-5 check resources log :
fly -t <target name> check-resource -r <concourse pipeline name>/<concourse resource name> --watch `

Step-6 fix the error at step3 if need. If step 5 has no error,  please wait it.