CI/CD Adapter Specification

アプリケーションのデプロイ・試験を実施する「ワークフロー」を定義するCI/CD Adapterの仕様について以下に示します。

Qmonus Value Streamは、CI/CD AdapterからTekton Pipeline/Task Manifestを生成します。この処理をコンパイル、と呼びます。 CI/CD AdapterはTask定義とPipeline定義に分かれます。それぞれ仕様が異なるため、内容を分けて説明します。

Task定義

以下のように、CI/CD AdapterのTask定義のフィールドの大部分はTekton Taskに依存する要素で構成されます。 Tekton TaskにはないCI/CD Adapter Task定義の固有のパラメータとして、大きく分けて以下の5種類に分類できます。

• prefix：Tekton Task名のパラメータのプレフィックスを指定します。
• prefixAllParams：prefixによって指定したプレフィックスをPipelineのパラメータにも伝播させることを指定します。
• params : Tekton Taskのパラメータをオブジェクト型で与えます。
• approvalRequired：Value Streamで承認行為をすることを指定します。
• input : Pipeline定義により決定されるパラメータの型を指定します。

#TaskBuilder: {

	// Tekton steps
	steps: [...tekton.#Step]

	// Tekton Task volumes
	volumes: [...corev1.#Volume]

	// Tekton Task Workspaces
	workspaces: [...tekton.#WorkspaceDeclaration]

	// Tekton Result Definition
	results: {
		description: string | *""
	}

	id: string

	// name is Task name
	name: string

	prefix: string | *""

	// If flag is true, add prefix to parameter name
	prefixAllParams: bool | *false

	// This parameter is currently the same as Tekton's runAfter
	runAfter: [...string]

	// This parameter is the same as Tekton's when expressions
	when: [...{
		input:    string | #TaskParam | #TaskResult
		operator: selection.#Operator
		values: [...string]
	}]

	// Tekton Param Definition
	#TaskParam: {
		desc:    string
		default: string
		prefix: bool | *false
	}

	params: [string]: #TaskParam

	// value stream approval task
	approvalRequired: bool | *false

	namespace: string | *""

	// input given by user
	input: {
		// constant parameters passed from pipeline.
		constParams: {[string]: !~"\\$\\(params\\..*\\)" | #TaskResult}

		// When env is specified, Task is executed only in the environment
		// If env is empty, Task is executed in all environments.
		env: string | *""
		...
	}
}

Prefix

prefixフィールドは、Task名であるmetadata.nameフィールドに対してプレフィックスを付与することが出来ます。

例

Task名にappというプレフィックスを付与します。

prefix: "app"

PrefixAllParams

prefixAllParamsフィールドは、prefixフィールドの入力を前提としています。trueにすることでprefixフィールドで指定したプレフィックスをPipeline側のspec.params.nameフィールドにも反映できます。この時、Task側のspec.params.nameフィールドにはプレフィックスは付与されません。

例

Task名およびPipelineのパラメータ名にappというプレフィックスを付与します。

prefix: "app"
prefixAllParams: true

Params

paramsフィールドは、Tekton Taskのspec.params[]フィールドに相当するパラメータをオブジェクト形式で宣言します。 さらに、params.[string].prefixをtrueにすることで、prefixで与えたプレフィックスをTaskのパラメータごとに指定して付与できます。また、prefixAllParamsがtrueのときは、params.[string].prefixの値に関わらず、全てのPipelineパラメータにプレフィックスが付与されます。

例

二つのパラメータオブジェクトを作成し、pathToDockerFileのパラメータのみ、prefixで指定しているプレフィックスappを付与する。

prefix: "app"

params: {
	pathToDockerFile: {
		desc: "The path to the dockerfile to build (relative to the context)"
		default: "Dockerfile"
		prefix: true
	}
	imageTag: {
		desc:	"The tag name of container"
		default: "latest"
	}
}

Input

Inputフィールドは、CI/CD AdapterのPipeline定義から渡されるパラメータのリストを宣言します。

例

string型のパラメータであるphaseと、boolean型のパラメータであるuseDebugを、CI/CD AdapterのPipeline定義から受け取る事を宣言しています。

input: {
	phase:    string
	useDebug: bool
}

ApprovalRequired

approvalRequiredフィールドは、Qmonus Value Streamで実行されるTaskに承認行為を要求するパラメータです。 こちらを指定することで、approvalというTaskが追加で生成され、Pipelineの中で該当Taskの後に指定されます。このPipelineを指定したAssemblyLineをQmonus Value Streamで実行すると、approval Taskの後のTaskを実行するかどうか、GUI上で判断することを要求します。 このTaskを使用したQmonus Value Streamでの動作イメージは、商用環境のPromotionを参考にしてください。

例

Taskの実行後にQmonus Value Streamで承認行為を要求します。

approvalRequired: true

Pipeline定義

以下のように、CI/CD AdapterのPipeline定義の固有のフィールドは、主に初期化時に利用するpipelineParameters、出力するTekton Pipeline/Task Manifestを宣言するpipelines、および組み合わせるInfrastructure Adapterのリストcompositesから構成されます。

#DesignPattern: {
	name:        string
	description: string | *""

	// input parameters for pipeline
	pipelineParameters?: {[string]: _}

	// enumerates design pattern
	composites?: [...#CompositeDef]

	// pipeline declaration
	pipelines?: {[string]: _}
}

Pipelineの基本要素

nameおよびdescriptionフィールドは、CI/CD Adapterについての説明を記述します。現在、これらのフィールドがコンパイル時に利用されることはありません。

ここで、nameは必須フィールドです。

例

name:        "pattern01"
description: "a sample ci/cd adapter"

PipelineParameters

pipelineParametersフィールドは、CI/CD Adapterの初期化時に、外から受け取るパラメータのリストを宣言します。コンパイル時にQVS ConfigのpipelineParamsフィールドで渡されたパラメータの値は、ここで宣言したpipelineParametersにバインドされます。

例

stringのパラメータを２つ、booleanのパラメータを１つ受け取ります。

pipelineParameters: {
	image:  string
	version: string
    useDebug: true
}

Pipelines

pipelinesフィールドは、CI/CD Adapterが出力するPipeline Manifestについて、Pipeline名をkeyとしたObjectの形で宣言します。

[string]にPipeline名を記載し、[task=string]にはPipelineのspec.tasks[].nameフィールドに相当するTask名を入力し、#TaskBuilderとして記述したTask定義がspec.tasks[].taskRef.nameフィールドのTask名としてBindされ、Pipeline/Taskとして一度に出力される構造になっています。 [string].resultsでは、Task定義でresultsフィールドを指定した際にのみ、TaskからPipelineへ伝搬されるspec.resultsフィールドに追従して、Task定義で記載されているDescriptionが自動で付与されます。

#PipelineBuilder: {
	[string]: {
		tasks: [task=string]: #TaskBuilder
		results: [string]: description: string
		...
	}
}

例

compileApp, deployAppTask定義を importして#BuilderスキーマからPipeline/Taskを生成します。 Inputに対応するように、compile Task定義のinput フィールドに、stringのパラメータを1つ、booleanのパラメータを1つ渡します。

import (
		"module-to-load/tasks:compileApp"
		"module-to-load/tasks:deployApp"
)

[...]

pipelines: {
	"deploy": {
			tasks: {
				"compile": compileApp.#Builder
				input: {
						phase: "app"
						usedebug: "true"
				}
				"deploy": deployApp.#Builder
			}
		}
}

出力されるPipeline Manifestは以下になります。

kind: Pipeline
apiVersion: tekton.dev/v1beta1
metadata: 
  name: deploy
spec:
  tasks:
    - name: compile # Pipeline定義でtasks以下に指定したTask名
      taskRef:
        name: compile-app-name # Task定義で指定されるTask名
    [...]
    - name: deploy # Pipeline定義でtasks以下に指定したTask名
      taskRef:
        name: deploy-app-name # Task定義で指定されるTask名
    [...]

Composites

Infrastructure Adapterと同様に、CI/CD Adapter同士を組み合わせて新しいCI/CD Adapterを定義するために、compositesフィールドを使用することが出来ます。 詳細は、Infrastructure AdapterのCompositeの説明を参照してください。 CI/CD Adapterで解決したManifestは、pipelinesフィールドに全て結合されます。

例

compile Task -> deploy Task の順で実行されるdeploy Pipeline定義をCompositeし、解決したPipeline/Task定義に対して、compile Taskの後（deployTaskの前）に承認行為を要求するTaskを追加します。

import (
		"module-to-load:deploy"
)

composites: [
		{
			pattern: deploy.DesignPattern
			pipelineParams: {
				useDebug:    pipelineParameters.useDebug
				deployPhase: "app"
			}
		},
	]

pipelines: {
	"deploy": {
		tasks: {
			"compile": {
				approvalRequired: true
			}
		}
	}
}