DevOps - Concourse

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执行的计划任务，也就是task要做的事情。每个job都有一个单独的build plan。

plan必填项中的配置属性

- aggregate    涉及get、resource
- task    执行用户定义的任务，涉及file（.yml文件格式）、params（参数）属性，file指定工作内容对应的yml文件，取自resource下相关路径
- get    获得指定资源，
- trigger    设置是否自动触发（例如，source code有变动，自动拉取新代码，并触发job启动）
- put    指定要操作的资源
- passed    设置job执行的前置条件

3.3 Task

### platform 
表明task的执行环境。
除了linux还有windows、darwin等。

### inputs 
必填项，指定该task期望获得的输入项，也就是指明向task传递输入的文件
每个输入项由以name、path两个属性来指定输入。
- name是必填项，表示输入的名称。
- path是可选的，表示路径。如果没有指明path，输入项的路径就是input名。

### 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.