Qmonus Value Stream Docs

Appearance

解説 ​

こちらではチュートリアルでは詳細に説明できなかった事項を解説します。

デプロイに必要なリソース ​

今回のチュートリアルでは、手順2-1 にて AssemblyLine を実行するために、以下 4 つのリソースを作成しました。

  • Application
  • Repository
  • Environment
  • Deployment

この章ではこの4つのリソースについて解説します。

Application ​

Qmonus Value Stream によってデプロイするアプリケーションの情報を管理するリソースです。 Application は、1 つの Repository の情報を持ちます。 今回のチュートリアルでは、Nginx を用いたサンプルアプリケーションの情報を登録しています。

Repository ​

アプリケーションのソースコードが格納されているGitリポジトリの情報を管理するリソースです。 Application の作成に必要となります。 Gitリポジトリは GitHub ・ GitLab ・ Bitbucket ・ Backlog から選択できます。

Environment ​

Application のデプロイ先となる環境を定義したリソースです。 Kubernetes クラスタやクラウドプロバイダ（Google Cloud, Azure, AWS）といった Provisioning Target を指定することで、デプロイ先の環境情報を Qmonus Value Stream に連携します。 今回のチュートリアルでは、Provisioning Target として、持ち込みの Kubernetes クラスタを指定しました。

Deployment ​

「どのアプリケーションを、どのEnvironmentにデプロイするのか」というアプリケーションとEnvironmentの紐づきを定義するリソースです。 1 つの Application と 1 つの Environment から構成され、Qmonus Value Stream がアプリケーションをデプロイする際の単位となります。 今回のチュートリアルでは、「Nginx を用いたサンプルアプリケーションを、持ち込みの Kubernetes クラスタにデプロイする」という情報を持ちます。

Deployment Config ​

Deployment Config は、Deploymentに対して定義可能なKey-Valueストアです。 Deployment（ApplicationとEnvironmentの組み合わせ）ごとに設定したい環境変数を定義できます。

リソースの関係性 ​

リソース同士の関係をまとめると、以下のようになります。

Project
  └── Deployment
       ├── Application
       │     └── Repository
       └── Environment

このモデルでは、アプリケーションのソースコード（Application）は環境が異なっても変化せず、デプロイ先の環境（Environment）によって異なる部分（環境変数やインフラストラクチャ構成の可変値など）は、Deploymentと紐づくDeployment Configという機能によって設定できます。これにより、アプリケーションと環境を分離しつつ、柔軟かつ一貫性のあるデプロイプロセスを実現します。

QVS Config ​

QVS Config とは ​

チュートリアルリポジトリの紹介 で、QVS Config について「Qmonus Value Stream によって実行したい CI/CD 処理（Pipeline）を宣言するファイル」と説明しました。 簡単化のためにこのように説明したため、こちらで詳しく説明します。

より正確に説明すると、QVS Config とは、「Cloud Native Adapter」とそのパラメータを指定する Qmonus Value Stream の設定ファイルです。Application 毎に作成し、各 Application の Repository に配置して、Qmonus Value Stream から読み込んで使用します。

Qmonus Value Stream は、QVS Config を読み込むことで、QVS Config で宣言されている Cloud Native Adapter に基づいた CI/CD 処理を実現します。 また Application のデプロイ先の環境ごとの設定差異を Deployment Config で定義することで、QVS Configの CI/CD 処理を複数の環境で共通化でき、設定の重複を排除し、管理の複雑さを軽減できます。

Cloud Native Adapter とは ​

Cloud Native Adapter とは、アプリケーションをクラウド基盤上で動作させるためのシステム構成や CI/CD パイプラインを再利用可能な形でパッケージした、Qmonus Value Stream 独自の仕組みです。

本来、アプリケーションをクラウド基盤上にデプロイするための CI/CD パイプラインを構築するには、クラウドインフラストラクチャをデプロイするパイプライン、アプリケーションをビルド・デプロイするパイプラインといった複数のパイプラインが必要になりますが、Qmonus Value Stream では、ユーザが CI/CD パイプラインを構築するための探索・検証コストを軽減できるように、最適な CI/CD パイプラインをまとめたパッケージを Official Cloud Native Adapter として提供しています。

これを利用することで、ユーザは自分で複雑な CI/CD パイプラインを構築するためのコストを負担しなくとも、Cloud Native Adapter を指定して必要なパラメータを設定するだけで、クラウドインフラストラクチャやアプリケーションをデプロイする CI/CD パイプラインを構築できます。

Qmonus Value Stream が提供している Official Cloud Native Adapter とその機能の詳細については、Official Cloud Native Adapter 公式ドキュメント を参照してください。

QVS Config の内容 ​

今回のチュートリアルで使用した QVS Config（ qvs.yaml ）の記載内容を確認してみましょう。 QVS Config の内容は以下になります。

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

modules:
  - name: github.com/qmonus/official-cloud-native-adapters
    revision: v0.20.0

designPatterns:
  - pattern: qmonus.net/adapter/official/kubernetes/deployment/simple
    params:
      k8sNamespace: $(params.k8sNamespace)
      imageName:    $(params.imageName)
      appName: nginx-demo
      port: "80"
      replicas: "1"
  - pattern: qmonus.net/adapter/official/kubernetes/sample:loadbalancer
    params:
      k8sNamespace: $(params.k8sNamespace)
      appName: nginx-demo
      port: "80"
  - pattern: qmonus.net/adapter/official/pipeline/deploy:simple
  - pattern: qmonus.net/adapter/official/pipeline/sample:resolveIPAddress

QVS Config は、以下の 3 つのフィールドに分かれています。

params ​

params フィールドでは、Cloud Native Adapter の引数として設定するパラメータの一覧を宣言します。宣言する内容は、パラメータ名とパラメータの型になります。 今回は、パラメータとして k8sNamespace と imageName を宣言し、Cloud Native Adapter の引数として渡せるように設定しています。

modules ​

modules フィールドでは、利用したい Cloud Native Adapter が存在するリモートリポジトリの情報を指定します。 具体的には、利用したいリポジトリの URL とバージョンを指定します。

今回は、Qmonus Value Stream が提供する Official Cloud Native Adapter を利用するため、Official Cloud Native Adapter のリポジトリの情報を設定しています。

designPatterns ​

designPatterns フィールドでは、modules で指定したリポジトリで使用したい Cloud Native Adapter と、その Cloud Native Adapter に渡すパラメータを指定します。

Cloud Native Adapter に渡すパラメータには、固定値だけでなく params で宣言したパラメータも設定できます。 params で宣言したパラメータを指定する場合は $(params.パラメータ名) のように記述します。 params で宣言したパラメータを利用することで、AssemblyLine を実行する際に、パラメータの値を柔軟に変更して実行できるようになります。

今回は、以下の 4 つの Official Cloud Native Adapter と、それぞれに必要なパラメータを指定しています。

  • qmonus.net/adapter/official/kubernetes/deployment/simple

    • Kubernetes の Deployment リソースを作成する Cloud Native Adapter。
    • パラメータ:
      • k8sNamespace: $(params.k8sNamespace)
      • imageName: $(params.imageName)
      • appName: nginx-demo #固定値
      • port: "80" #固定値
      • replicas: "1" #固定値

  • qmonus.net/adapter/official/kubernetes/sample:loadbalancer

    • Kubernetes の Service リソースを作成して、クラウドプロバイダのロードバランサを用いて外部公開する Cloud Native Adapter。
    • パラメータ:
      • k8sNamespace: $(params.k8sNamespace)
      • appName: nginx-demo #固定値
      • port: "80" #固定値

  • qmonus.net/adapter/official/pipeline/deploy:simple

    • アプリケーションをデプロイする CI/CD パイプライン（Pipeline/Task）を作成する Cloud Native Adapter。
    • 今回は、上述の Cloud Native Adapter によって作成される Kubernetes の Deployment リソースと Service リソースを Kubernetes クラスタにデプロイします。

  • qmonus.net/adapter/official/pipeline/sample:resolveIPAddress

    • デプロイされた Service リソースのグローバル IP アドレスを取得して、AssemblyLine 上で参照できるようにする CI/CD パイプライン（Pipeline/Task）を作成する Cloud Native Adapter。

各 Official Cloud Native Adapter において設定できるパラメータについては、Official Cloud Native Adapter 公式ドキュメント を参照してください。

QVS Config のコンパイルと Pipeline/Task の登録 ​

QVS Config で宣言した Cloud Native Adapter に基づく CI/CD パイプラインを Qmonus Value Stream で使用するには、QVS Config を「コンパイル」する必要があります。

具体的には、手順3-1 における COMPILE ボタンを押下することで、QVS Config がコンパイルされます。

QVS Config をコンパイルすると、Cloud Native Adapter としてパッケージされている CI/CD パイプライン（Pipeline と Task）が生成されます。この Pipeline/Task を Qmonus Value Stream に「登録」することで、Qmonus Value Stream 上で Pipeline/Task を使用できるようになります。

具体的には、手順3-1 における APPLY ボタンを押下することで、Pipeline/Task が Qmonus Value Stream に登録されます。

このようにして登録した Pipeline を組み合わせることで、さまざまな CI/CD 処理を実現する AssemblyLine を構築できるようになります。

AssemblyLine ​

AssemblyLine とは ​

AssemblyLine は、 Qmonus Value Stream におけるCI/CDワークフローの設計図です。 複数の Pipeline を直列・並列に組み合わせることで、アプリケーションのビルド、テスト、デプロイといった一連のプロセスを柔軟に定義・実行できます。 今回のチュートリアルで説明したように、AssemblyLine は複数の Pipeline から構成され、Pipeline は複数の Task から構成されています。 つまり、AssemblyLine、Pipeline、Task は、以下のような親子関係になっています。 この階層的な構造により、複雑なデプロイ戦略も管理でき、効率的な開発サイクルを実現します。

AssemblyLine
    ├── Pipeline(A)
    │    ├──Task
    │    │   ├──Step
    │    │   ├──Step
    │    └──Task
    │        ├──Step
    │        └──Step
    └── Pipeline(B)
         ├──Task
         │   ├──Step
         │   ├──Step
         └──Task
             ├──Step
             └──Step

AssemblyLine は Pipeline の処理を繋げるだけでなく、Pipeline と Task の実行パラメータを解決する役割も担います。 例えば、AssemblyLine が受け取ったパラメータを Pipeline や Task に渡したり、実行が完了したPipeline の実行結果を次の Pipeline のパラメータとして渡したりできます。

AssemblyLine の登録方法 ​

AssemblyLine は、手順3-2 でリポジトリのassemblyline-staging.yaml から登録したように、AssemblyLine の定義が記述された YAML ファイル（AssemblyLine マニフェスト）を用いて登録します。

AssemblyLine のパラメータ ​

AssemblyLine で使用したいパラメータを AssemblyLine マニフェストで定義することで、AssemblyLine 詳細画面の Input Parameters でパラメータを設定して AssemblyLine の実行時に渡すことができます。 さらに、受け取ったパラメータを Pipeline に渡すことも可能です。

AssemblyLine マニフェストの内容 ​

今回のチュートリアルで使用した AssemblyLine マニフェストの内容を確認してみましょう。 AssemblyLine マニフェストの内容は以下になります。

yaml
apiVersion: vs.axis-dev.io/v1
kind: AssemblyLine
metadata:
  name: staging-deploy
spec:
  params:
    - name: gitRevision
      type: string
    - name: imageName
      type: string
  stages:
    - name: deploy
      spec:
        pipeline: nginx-demo-deploy
        deployment:
          app: nginx-demo
          name: staging
        params:
          - name: gitRevision
            value: $(inputs.gitRevision)
          - name: imageName
            value: $(inputs.imageName)
    - name: resolve-ip-address
      spec:
        pipeline: nginx-demo-resolve-ip-address-after-deploy
        deployment:
          app: nginx-demo
          name: staging
      runAfter:
        - deploy
  results:
    - name: ipAddress
      value: $(stages.resolve-ip-address.results.ipAddress)

AssemblyLine マニフェストは、以下の 4 つのパートに分かれています。

メタデータの定義 ​

AssemblyLine マニフェストでは、ファイルの先頭で以下のように AssemblyLine のメタデータを記述します。

yaml
apiVersion: vs.axis-dev.io/v1
kind: AssemblyLine
metadata:
  name: staging-deploy

apiVersion と kindの値は固定です。

metadata.name に、登録したい AssemblyLine の名称を設定します。 今回の AssemblyLine では、AssemblyLine の名称は staging-deploy になります。

パラメータの定義 ​

spec.params で、AssemblyLine の Input Parameters として設定できるようにしたいパラメータを宣言します。 宣言する内容は、パラメータ名とパラメータの型になります。

ワークフローの定義 ​

spec.stages で、AssemblyLine を構成する Pipeline を定義します。

今回は、deploy という名称の Pipeline と resolve-ip-address という名称の Pipeline を記述しています。 また、各 Pipeline には、以下のフィールドを設定できます。

  • spec.stages[i].spec.pipeline （必須）

    • 利用する Pipeline の名称を指定します。
    • 今回は、手順3-1 で登録した Pipeline の名称を指定します。

  • spec.stages[i].spec.deployment （必須）

    • Pipeline に紐づけたい Deployment および Application の名称を指定します。
      • この設定により、Deployment Config のパラメータを Pipeline に注入できるようになります。
    • 今回は、手順2-2 で登録した Deployment および Application の名称を指定します。

  • spec.stages[i].spec.params （任意）

    • Pipeline に渡したいパラメータの情報を指定します。
      • spec.params で宣言した Input Parameters を使用したい場合は、$(inputs.パラメータ名)と指定します。

  • spec.stages[i].runAfter （任意）

    • Pipeline の実行順序を制御するために指定します。どの Pipeline の後に処理をするかを記述します。
    • 今回は、resolve-ip-address Pipeline よりも先に deploy Pipeline が実行され、Service リソースがデプロイ済みの状態になっている必要があるため、resolve-ip-address Pipeline の runAfter に deploy を指定します。

実行結果の定義 ​

spec.results で、AssemblyLine の実行結果として出力したいパラメータを定義します。この実行結果を AssemblyLine Results と呼称します。

今回は、resolve-ip-address Pipeline が Service リソースのグローバル IP アドレスを ipAddress というパラメータ名で取得・出力できるため、resolve-ip-address Pipeline の実行結果から取得した ipAddress の値を AssemblyLine Results として出力するように設定しています。

Results について

Pipeline が出力するパラメータについては、Official Cloud Native Adapter のドキュメントに記載されているので、参考にしてください。

AssemblyLine の実行時の動き ​

ここでは、手順4-1 で実行した AssemblyLine の実行時の動きを解説します。 なお、AssemblyLine と Pipeline は以下のように設定されています。

markdown
AssemblyLine
    ├── Pipeline(deploy)
    └── Pipeline(resolve-ip-address)

AssemblyLine に渡すパラメータ

  • gitRevision (アプリケーションのリポジトリにおけるコミットのハッシュ値、またはブランチ名、またはタグ名)
  • imageName (アプリケーションとしてデプロイする Docker イメージの名前)

この 2 つのパラメータは、AssemblyLine を実行するたびに値を変えることになる可能性があるパラメータのため、値を設定しやすいように、AssemblyLine の Input Parameters から設定するようにしています。

Pipeline(deploy) に設定が必要なパラメータ

  • gitRevision (アプリケーションのリポジトリにおけるコミットのハッシュ値、またはブランチ名、またはタグ名)
  • imageName (アプリケーションとしてデプロイする Docker イメージの名前)

AssemblyLine の Input Parameters から設定したパラメータを Pipeline に渡すようにしています。

Pipeline(resolve-ip-address) に設定が必要なパラメータ

Pipeline が必要とするパラメータがないため、ここではパラメータは設定していません。

1. AssemblyLine に紐づけられた Deployment を読み込む ​

AssemblyLine を実行すると、AssemblyLine は 手順2-2 で登録した Deployment を読み込みます。

2. パラメータを読み込む ​

以下のパラメータを読み込み、Pipeline で使用できるようにします。

  • AssemblyLine の Input Parameters から設定されたパラメータ
    • ここでは、gitRevision と imageName を読み込みます。
  • Deployment Config から設定されたパラメータ
    • Deployment Config とは、Deployment に対して定義可能な Key-Value 形式のパラメータです。AssemblyLine 詳細画面の各 Pipeline Stages のカードを押下すると表示される EDIT DEPLOYMENT CONFIG ボタンから設定できます。

3. Pipeline(deploy)を実行する ​

AssemblyLine は、設定されたパラメータを渡して Pipeline を実行します。

deploy Pipeline の実行が完了すると、Environment で指定した Kubernetes クラスタに、imageNameで指定したコンテナイメージに基づく Deployment リソースと Service リソースがデプロイされます。

4. Pipeline(resolve-ip-address)を実行する ​

Pipeline の実行が完了すると、次の Pipeline が実行されます。

resolve-ip-address Pipeline の実行が完了すると、Kubernetes クラスタにデプロイされた Service リソースのグローバル IP アドレスが取得され、AssemblyLine 上で参照できるようになります。

5. AssemblyLine の実行が完了する ​

AssemblyLine を構成するすべての Pipeline の実行が完了すると、AssemblyLine の実行が完了します。

AssemblyLine は、resolve-ip-address Pipeline によって取得された IP アドレスを AssemblyLine Results として出力します。