Qmonus Value Stream Docs

Appearance

AssemblyLineの登録 ​

ここでは、Qmonus Value StreamにおけるデリバリパイプラインであるAssemblyLineを作成し、登録します。

以下の3種類のリソースを登録します。

  • Task
    • Tekton にて提供されているk8s Custom Resourceを指します。
    • デリバリパイプラインで具体的に実施する処理を、Tektonの仕様に従い記述します。
    • Tektonの仕様に従い記述された任意のTaskを実行できます。
    • CLIツール qvsctlにより、Cloud Native Adapterをデリバリするために必要なTaskを自動生成できます。
  • Pipeline
    • Tekton にて提供されているk8s Custom Resourceを指します。
    • Taskを束ねた実行単位で、Taskの実行順序、実行パラメータ、実行結果のoutputと後段taskのinputとの依存関係を記述します。
    • Qmonus Value Streamでは、1つのApplicationを1つのDeploymentに対してデリバリする単位をPipelineとして構成することを推奨します。
    • Tektonの仕様に従い記述された任意のPipelineを実行できますが、推奨は上記の通りです。
    • CLIツール qvsctlにより、Cloud Native Adapterをデリバリするために必要なPipelineを自動生成できます。
  • AssemblyLine
    • Qmonus Value Stream にて提供する独自のk8s Custom Resourceを指します。
    • Pipelineを束ねた実行単位で、Qmonus Value Streamから手動もしくはWebhookで 実行できる単位です。
    • 1つのAssemblyLineを用いて、1つ以上のApplicationを1つ以上のDeploymentに対してリリースできます。
    • AssemblyLineは、利用者自身で記述します。

Pipeline/Taskの生成 ​

QVS Configにて選択したCloud Native Adapterから、デリバリするために必要な Pipeline/Taskを生成します。

CLIの入手 ​

Qmonus Value Stream CLI のインストールをご確認ください。 以降は バイナリを利用した例として説明しています。

QVS Configの作成 ​

Pipeline/Task の生成は、QVS Config に記載された Cloud Native Adapterをコンパイルすることで生成します。 Official Cloud Native Adapterを利用する場合は、CLIツール qvsctlでダウンロードし、自身のリポジトリにCommitした上で、ご利用ください(参考: qvsctl adapter get)。

以下にQVS Configの例を記載します。

yaml
params:
  - name: k8sNamespace
    type: string
  - name: imageName
    type: string

modules:
  - name: github.com/qmonus/sample
    local: 
      path: .  # relative path to qvs.yaml

designPatterns:
  - pattern: github.com/qmonus/sample/local
    params:
      k8sNamespace: $(params.k8sNamespace)
      imageName:    $(params.imageName)
  # Google Cloudの場合
  - pattern: qmonus.net/adapter/official/pipeline/build:buildkitGcp
  # Azureの場合
  - pattern: qmonus.net/adapter/official/pipeline/build:buildkitAzure
  - pattern: qmonus.net/adapter/official/pipeline/deploy:simple

備考 また、GitHub上の別のリポジトリにあるCloud Native Adapterを利用する方法もQVS Configではサポートされています。 QVS Configの modulesに以下の記載することで、GitHub上にあるリポジトリからrevision のデータを取得して、コンパイルに利用できます。

yaml
modules:
  - name: github.com/sample-org/own-adapter-repository
    revision: <revison>(e.g. cdbc8d2a40939ecb34b7b748fc89e5fa58ca14eb)

Pipeline/Taskの生成 ​

以下のコマンド実行することで、Pipeline/Taskのマニフェストファイルを生成します(参考: qvsctl pipeline compile)。

bash
$ qvsctl pipeline compile -m . -c </path/to/qvs.yaml> --prefix ${prefix}

問題がなければ、デフォルトで output/manifests.ymlに Pipeline/Task のリソースファイルが出力されます。出力先のディレクトリは -o, --outフラグにより制御可能です。

備考 また、前述の別のリポジトリにあるCloud Native Adapterを利用し、認証が必要なプライベートリポジトリの場合には GitHub のToken を環境変数として設定してください。

bash
// e.g.
export GITHUB_TOKEN=<リポジトリへアクセス可能なGitHub Token>

環境変数の設定後、以下のコマンドを実行します。

bash
$ qvsctl pipeline compile -c </path/to/qvs.yaml> --prefix ${prefix}

AssemblyLineの作成 ​

前項で定義したPipeline/Taskを用いて、AssemblyLineのマニフェストを作成します。 AssemblyLineでは、複数のPipelineをステージとして登録でき、各ステージごとにデリバリするApplicationとデリバリ先のDeploymentをそれぞれ1つ指定できます。これにより、複数のApplicationを複数のDeploymentにデリバリする処理を1つにまとめたデリバリパイプラインを構成できます。

AssemblyLine マニフェスト ​

AssemblyLineは、k8sのCustom Resourceとして登録するため、k8s Resourceの記法に従いYAMLで記述します。

AssemblyLineの具体例を以下に記します。

yaml
apiVersion: vs.axis-dev.io/v1
kind: AssemblyLine
metadata:
  name: staging-deploy
spec:
  params:
    - name: gitRevision
      type: string
  stages:
    - name: build
      spec:
        pipeline: nginx-demo-build
        deployment:
          app: nginx-demo
          name: staging
        params:
          - name: gitRevision
            value: $(inputs.gitRevision)
          - name: cacheImageName
            value: $(params.imageRegistryPath)/$(params.imageShortName)
    - name: deploy
      spec:
        pipeline: nginx-demo-deploy
        deployment:
          app: nginx-demo
          name: staging
        params:
          - name: gitRevision
            value: $(inputs.gitRevision)
          - name: imageName
            value: $(stages.build.results.imageFullNameTag)
      runAfter:
        - build
  results:
    - name: imageName
      value: $(stages.build.results.imageFullNameTag)
    - name: gitRevision
      value: $(inputs.gitRevision)

AssemblyLineの各フィールドでは、以下内容を記述します。

  • 必須フィールド
    • apiVerison: AssemblyLineのAPI Versionを記述します。現在は vs.axis-dev.io/v1 固定です。
    • kind: Resourceの種類を記述します。 AssemblyLine と記述します。
    • metadata: AssemblyLineを一意に特定できる情報を記述します。
      • namespace: このAssemblyLineを利用する Project のNameを記述します。
      • name: AssemblyLineを namespace 内で一意に参照できる名前を記述します。
    • spec: AssemblyLineで実行するデリバリパイプラインの具体的な内容を記述します。
    • spec.stages: 1つ以上のパイプラインステージを定義します。
  • 任意フィールド
    • spec.params: AssemblyLine実行時に引数として外部から渡したいパラメータを記述します。
    • spec.results: AssemblyLine実行後に、実行結果として保存したいパラメータを記述します。

AssemblyLineの各パイプラインステージでは、以下内容を記述します。 パイプラインステージとはAssemblyLine内で指定されるPipelineを指します。 1つのパイプラインステージを1つのPipelineと結びつけ、Pipelineを処理する環境などを入力できます。

  • 必須フィールド
    • name: パイプラインステージの名前を記述します。AssemblyLine内で一意な値を指定します。
    • spec: パイプラインステージの詳細を記述します。
    • spec.pipeline: パイプラインステージにて実行するPipelineを指定します。Pipelineの metadata.name の値を指定します。
    • spec.deployment.app: デリバリ対象の Application を指定します。 初期セットアップで登録した Application のNameを入力します。
    • spec.deployment.name: デリバリ対象の Deployment を指定します。 初期セットアップで登録した Deployment のNameを入力します。
  • 任意フィールド
    • spec.params: Pipelineに実行時引数として明示的に渡したいパラメータを記述します（以後、この操作をパラメータバインディングと呼びます）。
    • runAfter: 特定のパイプラインステージが完了するまで実行をblockしたい場合に、完了を待つパイプラインステージを記述します。配列で複数指定できます。

パイプラインステージのパラメータバインディング定義 ​

AssemblyLineのパイプラインステージでは、Pipelineを実行するために必要な全てのパラメータを spec.params に記述する必要はありません。

デリバリ対象として指定したDeploymentで参照可能なパラメータ（Deployment Params） のキーと spec.params[].key の値が一致する場合には、自動でパラメータが挿入されます。

以下の条件に当てはまる場合に限り、AssemblyLineマニフェスト上で明示的にパラメータを指定（パラメータバインディング）する必要があります。

  • 環境ごとに異なる値を入力する必要がなく、AssemblyLineでハードコードしたい場合
  • AssemblyLineの実行時引数を、パイプラインステージの実行引数として指定したい場合
  • 前段のパイプラインステージの実行結果を、後段のパイプラインステージの実行引数として指定したい場合
  • Deployment Params で参照可能なパラメータではなく、 Deployment Params に登録されている別の値を使用したい場合（エイリアス名での参照）
  • Deployment Params で参照可能なパラメータそのものではなく、前後に文字列を追加したり、複数のパラメータ（上述のAssemblyLine実行時引数や前段のパイプラインステージの実行結果を含む）を組み合わせて使用したい場合

パラメータバインディングの値（ spec.params[].value ）として、以下の変数・記法が利用できます。

変数詳細
$(inputs.<AssemblyLine params key>)AssemblyLine実行時引数で置換されます。
$(stages.<stage name>.results.<pipeline result key>)各パイプラインステージで実行されたPipelineのresultの値で置換されます。
$(params.<Deployment params key>)Deployment Params で定義されている値で置換されます。

AssemblyLine および Pipeline/Task の登録 ​

前項で作成したAssemblyLine および Pipeline/Taskを、Qmonus Value Streamに登録します。

  • CLIツール qvsctl を用いて、デリバリパイプライン実行環境にアクセスするための 認証トークンを取得します(参考: qvsctl auth)。

    $ qvsctl auth
Visit to https://qmonus.us.auth0.com/authorize?audience=...

  • Webブラウザを使用して指示されたURLにアクセスし、ログインを行います。 ログインが完了し、以下のメッセージが表示されることを確認します。

    Succeeded to fetch access token

    与えられたtokenにより、ログインユーザが権限を持つProject専用のnamespaceに対してアクセスする権限が与えられます。

  • AssemblyLine および Pipeline/Taskをそれぞれ登録します。

    • 作成したAssemblyLine Custom Resourceを登録します。 （AssemblyLine manifestでnamespaceを記述している場合は、project nameの指定は不要です）
    $ qvsctl pipeline apply -f <AssemblyLine manifest YAML> -p <project name>
assemblyline.vs.axis-dev.io/staging-deploy created

  • 同様に、AssemblyLineで参照しているPipeline/Taskを登録します。

    $ qvsctl pipeline apply -f <Pipeline/Task resources YAML> -p <project name> 
pipeline.tekton.dev/nginx-demo-build created
pipeline.tekton.dev/nginx-demo-deploy created
task.tekton.dev/nginx-demo-git-checkout created
task.tekton.dev/nginx-demo-auth-google-registry created
task.tekton.dev/nginx-demo-buildkit created
task.tekton.dev/nginx-demo-compile-design-pattern created
task.tekton.dev/nginx-demo-deployment-worker created

AssemblyLine および Pipeline/Task の登録確認 ​

登録したAssemblyLineを、UIから確認します。

  • 左メニューより、AssemblyLineを選択します。
  • AssemblyLineの一覧に、作成したAssemblyLineが表示されることを確認します。
AssemblyLineの一覧
  • 作成したAssemblyLineを押下します。
  • PIPELINE MANIFESTS のtabで、AssemblyLineのStageを選択することでPipelineの詳細を、PipelineTaskを選択することでTaskの詳細をそれぞれ閲覧できることを確認します。
PipelineとTaskの詳細
  • 全てのPipeline・Taskを順に選択し、Pipeline・Taskの詳細が閲覧できることを確認します。