Qmonus Value Stream Docs

Appearance

What is AssemblyLine ​

AssemblyLineとは、CI/CD Pipelinesに示す通り、Deployment Parametersで与えられた、ユーザのアプリケーションの環境に関する情報をTekton Pipelineに注入し、Qmonus Value StreamでCI/CDプロセスを管理・実行する役割を担います。AssemblyLineで定義するCI/CD Pipelineの単位はAssemblyLine Stage(以下、Stage)と呼ばれます。 ここでは、AssemblyLineの推奨配置場所、およびAssemblyLineの仕様について説明します。

AssemblyLineの推奨配置場所 ​

AssemblyLineは、アプリケーションのGitリポジトリに配置することを推奨します。配置した場合の例は以下の通りで、アプリケーションを管理する環境ごとにディレクトリを作成して配置することを推奨します。

Application Repository
└── .valuestream/
    └── assemblylines
        ├── dev/
        │   └──assemblyline-{用途}.yaml
        ├── stg/
        │   └──assemblyline-{用途}.yaml
        └── prod/
            └──assemblyline-{用途}.yaml

AssemblyLineの仕様 ​

AssemblyLineはYAML形式のManifestで記述され、ManifestをQmonus Value StreamへApplyすることで、実行可能なAssemblyLineをQmonus Value Streamに登録できます。

AssemblyLineでは以下のフィールドを指定します。

  • apiVersion（固定）: vs.axis-dev.io/v1
  • kind（固定）: AssemblyLine
  • metadata:
    • name: AssemblyLineの名前
    • annotations（任意）:
      • vs.axis-dev.io/event-type: change-created
  • spec: AssemblyLineの定義

specについてはassemblylineで指定するspecフィールドの詳細で詳細に説明します。

Annotation として指定できるchange-createdについては、Qmonus Value StreamでCI/CDリリースプロセスに関するメトリクスを収集するために付与するものとなります。詳しくは、DevOpsメトリクスの分析を参照してください。

AssemblyLine Manifestのサンプルは以下のようになります。

yaml
apiVersion: vs.axis-dev.io/v1
kind: AssemblyLine
metadata:
  name: staging-deploy
  annotations:
    vs.axis-dev.io/event-type: change-created
spec:
  params:
    - name: gitRevision
      type: string
      description: "Revision number of the git repository"
  stages:
    - name: build
      spec:
        pipeline: nginx-demo-build
        deployment:
          app: nginx-demo
          name: staging
        params:
          - name: gitRevision
            value: $(inputs.gitRevision)
            description: "Revision number of the git repository"
          - name: cacheImageName
            value: $(params.imageRegistryPath)/$(params.imageShortName)
            description: "Name of the cache image"
    - name: deploy
      spec:
        pipeline: nginx-demo-deploy
        deployment:
          app: nginx-demo
          name: staging
        params:
          - name: gitRevision
            value: $(inputs.gitRevision)
            description: "Revision number of the git repository"
          - name: imageName
            value: $(stages.build.results.imageFullNameTag)
            description: "Name of the image"
      runAfter:
        - build
  results:
    - name: gitRevision
      value: $(inputs.gitRevision)
      description: "Revision number of the git repository"
    - name: imageName
      value: $(stages.build.results.imageFullNameTag)
      description: "Name of the image"
  artifacts:
    - path: .

AssemblyLineで指定するSpecフィールドの詳細 ​

AssemblyLineのSpecフィールドでは、以下の4つの配列形式のフィールドを定義できます。

以下では、それぞれのフィールドで定義されるパラメータを説明します。

1. params(spec.params) ​

spec.paramsをキーとするフィールドではnameとtype、descriptionをセットとして、AssemblyLine実行時に指定するパラメータ（Input Parameters）を配列形式で宣言します。ここで指定したパラメータは、params(spec.stages.spec.params)で実際に実行するPipelineに注入するパラメータへマッピングできます。

  • name（必須）: パラメータ名
  • type（任意）: パラメータの型
  • description（任意）: パラメータの使用用途など、自由記述項目

Input Parameters

Input Parameters(paramsフィールド)は手動で入力する以外に、以下の2つのパターンで自動入力できます。

例 ​

gitRevisionとimageNameをInput Parametersとして宣言します。

yaml
spec:
  params:
  - name: gitRevision
    type: string
  - name: imageName
    type: string

例のマニフェストの場合、Apply後にQmonus Value Stream上でAssemblyLineを選択すると、Input Parametersとして反映されていることが確認できます。 AssemblyLine Input Parameters

2. stages ​

spec.stagesをキーとするフィールドではnameとspec、runAfterをセットとして、AssemblyLineで実行されるCI/CD Pipelineの実行単位を配列形式で宣言します。

  • name（必須）: Stage名
  • spec（必須）: PipelineとDeployment Parametersを指定するフィールド
  • runAfter（任意）: Stageの実行順序を制御するために、前段に実行するStageを指定する配列形式のフィールド（runAfterの指定がないStageは全て最初に並列で実行されます。）
    • runAfterの例: buildStage、deployStage、healthchekStageの順にAssemblyLineを実行します。
      yaml
      spec:
  stages:
    - name: build
      spec: [...]
    - name: deploy
      spec: [...]
      runAfter: 
        - build
    - name: healthcheck
      spec: [...]
      runAfter:
        - deploy

spec.stages直下のspecはさらに、

  • params（任意）
  • pipeline（必須）
  • deployment（必須） という３つのフィールドに分かれます。以下でそれぞれを説明します。

2-1. params(spec.stages.spec.params) ​

spec.stages.spec.paramsフィールドでは、nameとvalue、descriptionをセットとして、Pipelineに受け渡すパラメータを宣言します。ここでPipelineに注入した値は、Qmonus Value Streamで予約されているパラメータや、Tekton Pipeline側で記述されたパラメータを上書きします。

  • name（必須）: Pipelineで宣言しているパラメータ名
  • value（必須）: Pipelineで宣言しているパラメータに注入する値
  • description（任意）: パラメータの使用用途など、自由記述項目

また、valueフィールドでは、定数値を指定する以外に、以下の3パターンによる変数値の指定が可能です。

  • $(inputs.[パラメータ名]): params(spec.params)でInput Parametersとして与えたパラメータ
  • $(params.[パラメータ名]): Deployment Configの登録で与えたパラメータ
  • $(stages.[stage名].results.[パラメータ名]): runAfterによって先に実行されたStageのTekton Pipeline Resultsのパラメータ

Pipeline Results

AssemblyLine内でPipeline Resultsを使用するには、別途Tekton PipelineでResultsの項目を定義することが必要になります。 CI/CD AdapterのPipeline定義ではこのPipeline Resultsを定義してPipeline/Task Manifestを生成できます。詳しくは、Pipelinesを参考にしてください。

さらに、valueフィールドでは以下の例のように、それぞれのパラメータの値を連結させることも可能です。

例build Stageにおいて、Input ParametersのパラメータであるgitRevisionおよびDeployment ConfigのパラメータであるimageRegistryPathとimageShortNameから、PipelineにgitRevision、cacheImageNameとしてパラメータを注入します。

yaml
spec:
  params:
    - name: gitRevision
      type: string
  stages:
    - name: build
      spec:
        params:
          - name: gitRevision
            value: $(inputs.gitRevision)
          - name: cacheImageName
            value: $(params.imageRegistryPath)/$(params.imageShortName)
        pipeline: [...]
        deployment: [...]

2-2. pipeline ​

spec.stages.spec.pipelineフィールドでは、Stageで実行するTekton Pipelineを指定します。

例buildStageにおいて、Qmonus Value StreamにApply済みのnginx-demo-buildPipelineを実行Pipelineとして指定します。

yaml
spec:
  stages:
    - name: build
      spec: 
        params: [...]
        pipeline: nginx-demo-build
        deployment: [...]

2-3. deployment ​

spec.stages.spec.deploymentフィールドではappとnameをペアとし、Qmonus Value StreamのApplicationとDeploymentを指定することで、Git RepositoryやKubernetes認証情報、クラウド認証情報などのユーザの環境の情報をPipelineに注入します。

  • app（必須）: Application名
  • name（必須）: Deployment名

例buildStageにおいて、nginx-demoApplicationとstagingDeploymentをPipeline実行時に指定します。

yaml
spec:
  stages:
    - name: build
      spec: 
        params: [...]
        pipeline: [...]
        deployment: 
          app: nginx-demo
          name: staging

3. results ​

spec.results フィールドでは、nameとvalueとdescriptionをセットとして、AssemblyLine実行時に指定したパラメータまたは実行中に取得したパラメータを、AssemblyLine実行後にAssemblyLine Resultsとして確認できます。

  • name（必須）: Resultsに出力するパラメータの名前
  • value（必須）: Resultsに出力するパラメータの値
  • description（任意）: パラメータの使用用途など、自由記述項目

valueフィールドはparams(spec.stages.spec.params)と同様に、Input Parameters、Deployment Config、Pipeline Resultsのそれぞれのパラメータを指定できます。

例 ​

Input Parametersとして入力したgitRevision、buildStageでPipeline Resultsとして出力されたimageFullNameTagを、それぞれgitRevision、imageNameというパラメータ名でAssemblyLine Resultsとして出力します。

yaml
spec:
  stages:
    - name: build
      spec:
        params:
          - name: gitRevision
            value: $(inputs.gitRevision)
        pipeline: [...]
        deployment: [...]
    - name: deploy
      spec:
        params:
          - name: gitRevision
            value: $(inputs.gitRevision)
          - name: imageName
            value: $(stages.build.results.imageFullNameTag)
        pipeline: [...]
        deployment: [...]
      runAfter:
        - build
    results:
      - name: gitRevision
        value: $(inputs.gitRevision)
      - name: imageName
        value: $(stages.build.results.imageFullNameTag)

例のマニフェストの場合、AssemblyLineを実行すると、実行後の結果画面からAssemblyLine Resultsとして出力されていることが確認できます。 AssemblyLine Results

4. artifacts ​

spec.artifactsフィールドでは、AssemblyLine実行中にTekton Workspaceに出力されたファイルなどの生成物を、Qmonus Value Streamの実行結果からダウンロードできます。Tekton PipelineのWorkspaceの名前には、sharedと指定する必要があることに注意してください。 以下のような配列形式で指定します。

  • artifacts:
    • path（必須）: workspace.shared.pathからの相対パス

Workspace

AssemblyLine内でArtifactを使用するには、別途Tekton PipelineでsharedWorkspaceの項目を定義することが必要になります。 CI/CD AdapterのTask定義では、このWorkspaceを定義してPipeline/Task Manifestを生成できます。詳しくは、Task定義を参照してください。

例 ​

shared Workspace上のファイル一式をartifactとして指定します。

yaml
spec:
  params: [...]
  stages: [...]
  results: [...]
  artifacts:
    - path: .

AssemblyLineを実行すると、実行後の結果画面からTimelineの右下のARTIFACTSボタンが活性化され、生成物をtgz圧縮ファイルとしてダウンロードすることが可能になります。 Artifactsボタン