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)
- serviceName:
各 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 の名称を指定します。
- Pipeline に紐づけたい Deployment および Application の名称を指定します。
spec.stages[i].spec.params
(任意)- Pipeline に渡したいパラメータの情報を指定します。
spec.params
で宣言した Input Parameters を使用したい場合は、$(inputs.パラメータ名)
と指定します。
- Pipeline に渡したいパラメータの情報を指定します。
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
ボタンから設定できます。
- Deployment Config とは、Deployment に対して定義可能な Key-Value 形式のパラメータです。AssemblyLine 詳細画面の各 Pipeline Stages のカードを押下すると表示される
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 として出力します。