Qmonus Value Stream Docs

Appearance

解説 ​

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

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

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

  • Application
  • Repository
  • Environment
  • Deployment

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

Application ​

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

Repository ​

アプリケーションのソースコードが格納されているGitリポジトリの情報を管理するリソースです。

Environment ​

Application のデプロイ先となる環境を定義したリソースです。 Provisioning Target を指定することで、デプロイ先の環境を定義します。 今回のチュートリアルでは、Provisioning Target として、AWS を指定しました。

Deployment ​

「どのアプリケーションを、どの環境にデプロイするのか」を定義するリソースです。 1 つの Application と 1 つの Environment から構成されます。 今回のチュートリアルでは、「Nginx を用いたサンプルアプリケーションを、AWS 環境にデプロイする」という情報を持ちます。

リソースの関係性 ​

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

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

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 処理を実現します。

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: imageUri
    type: string
  - name: awsRegion
    type: string

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

designPatterns:
  - pattern: qmonus.net/adapter/official/adapters/aws/appRunner
    params:
      serviceName: nginx-demo
      imageUri: $(params.imageUri)
      port: "80"
      awsRegion: $(params.awsRegion)

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

params ​

params フィールドでは、Cloud Native Adapter の引数として設定するパラメータの一覧を宣言します。宣言する内容は、パラメータ名とパラメータの型になります。 今回は、パラメータとして imageUri と awsRegion を宣言し、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 を実行する際に、パラメータの値を柔軟に変更して実行できるようになります。

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

  • qmonus.net/adapter/official/adapters/aws/sample/appRunner
    • App Runner サービスを作成して指定されたイメージをデプロイし、作成された App Runner サービスの URL を取得する Cloud Native Adapter。
    • パラメータ:
      • serviceName: nginx-demo #固定値
      • imageUri: $(params.imageUri)
      • port: "80" #固定値
      • awsRegion: $(params.awsRegion)

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

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

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

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

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

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

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

AssemblyLine ​

AssemblyLine とは ​

AssemblyLine とは、Pipeline を直列・並列に組み合わせた CI/CD 処理のワークフローです。 今回のチュートリアルで説明したように、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 は、手順2-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: imageUri
      type: string
  stages:
    - name: deploy
      spec:
        pipeline: nginx-demo-deploy
        deployment:
          app: nginx-demo
          name: staging
        params:
          - name: gitRevision
            value: $(inputs.gitRevision)
          - name: imageUri
            value: $(inputs.imageUri)
    - name: get-url
      spec:
        pipeline: nginx-demo-get-url
        deployment:
          app: nginx-demo
          name: staging
        params:
          - name: serviceName
            value: nginx-demo
      runAfter:
        - deploy
  results:
    - name: serviceUrl
      value: $(stages.get-url.results.serviceUrl)

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 と get-url という名称の Pipeline を記述しています。 また、各 Pipeline には、以下のフィールドを設定できます。

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

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

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

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

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

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

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

    • Pipeline の実行順序を制御するために指定します。どの Pipeline の後に処理をするかを記述します。
    • 今回は、get-url Pipeline よりも先に deploy Pipeline が実行され、App Runner にアプリケーションがデプロイ済みの状態になっている必要があるため、get-url Pipeline の runAfter に deploy を指定します。

実行結果の定義 ​

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

今回は、get-url Pipeline が App Runner サービスの URL を serviceUrl というパラメータ名で取得・出力できるため、get-url Pipeline の実行結果から取得した serviceUrl の値を AssemblyLine Results として出力するように設定しています。

Results について

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

AssemblyLine の実行時の動き ​

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

markdown
AssemblyLine
    ├── Pipeline(deploy)
    └── Pipeline(get-url)

AssemblyLine に渡すパラメータ

  • gitRevision (アプリケーションのリポジトリにおけるコミットのハッシュ値、またはブランチ名、またはタグ名)
  • imageUri (アプリケーションとしてデプロイする、Amazon ECR Public Gallery で公開されているコンテナイメージの URI)

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

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

  • gitRevision (アプリケーションのリポジトリにおけるコミットのハッシュ値、またはブランチ名、またはタグ名)
  • imageUri (アプリケーションとしてデプロイする、Amazon ECR Public Gallery で公開されているコンテナイメージの URI)

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

Pipeline(get-url) に設定が必要なパラメータ

  • serviceName (固定値として nginx-demo を設定)

値を固定化したパラメータを Pipeline に設定するようにしています。

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

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

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

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

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

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

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

deploy Pipeline の実行が完了すると、Environment で指定した AWS に App Runner サービスが作成され、imageUri で指定したコンテナイメージに基づくアプリケーションが App Runner サービスにデプロイされます。

4. Pipeline(get-url)を実行する ​

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

get-url Pipeline の実行が完了すると、App Runner サービスの URL が取得され、AssemblyLine 上で参照できるようになります。

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

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

AssemblyLine は、get-url Pipeline によって取得された URL を AssemblyLine Results として出力します。