AssemblyLineの拡張

本章では、Qmonus Value StreamのOfficial CI/CD Adapterを用いて、デプロイのみのAssemblyLineを拡張し、デプロイの前にコンテナイメージをビルドするPipelineを追加する手順を解説します。

Getting StartedでのHTTP APIサーバの構築を前提としています。事前に準備が必要なリソースは以下の通りです。

ビルドしたDockerイメージの格納する Docker Format のGoogle Artifact Registry(GAR)
Google Artifact Registryへの書き込み権限(roles/artifactregistry.writer)のあるサービスアカウント(参考: Roles and permissions)、および、そのシークレットキー(json)
Qmonus Value Stream CLIのインストール

以降のステップでは、下記の作業を通じて、AssemblyLineを拡張できることを確認します。

Qmonus Value Stream CLI(以降, qvsctl)を用いて、Official CI/CD Adapterをダウンロードする
QVS Configに、拡張したい Official CI/CD Adapterを追加し、コンパイルする
AssemblyLineを編集し、QVS Configに追加した Official CI/CD Adapterから生成されたPipelineを追記する
AssemblyLineを実行し、コンテナイメージをビルド、および、そのイメージを使ってデプロイできていることを確認する

1. Environmentの編集 (GUI)

Getting Startedで行ったのと同様にProvisioning Targetを既存のEnvironmentへ追加します。

左メニューより、Environmentを選択します。
すでに作成してある staging を選択します。
画面右上の Edit ボタンを押下します。
Provisioning Targetの欄の右側の+ボタンを押下し、Provisioning Targetの欄を追加します。追加された欄へ下記のとおり値を選択します。
- Kind: gcp
- Project ID: [Dockerイメージの格納先として使用するGARのGCP Project ID]
画面右下の SAVE ボタンを押下します。

2. Deploymentの登録 (GUI)

Getting Startedで行ったのと同様に作成してあるDeploymentを編集し、Credentialsを追加します。

Application一覧より、 nginx-demo Applicationを選択します。
すでに作成されているDeploymentの staging を選択します。
画面右上の黄色い EDIT ボタンを押下します。
用意しているサービスアカウントのシークレットキーのjsonデータを、末尾に余計な改行などを含めず全て貼り付けて登録します。
- Credentials
  - GCP credential: 事前に準備したGARへの書き込み権限のあるサービスアカウントのシークレットキー(JSON)
  - kubeconfig: 変更がない場合、入力不要
画面右下の SAVE ボタンを押下します。

3. デプロイするアプリケーションの準備(CLI)

本チュートリアルではGetting Startedで作成した持ち込みのプライベートリポジトリと、getting-started ブランチをそのまま利用します。今回は簡単なnginxサーバを作成し、指定したWEBページが出力されるようなアプリケーションをデプロイします。

まずWEBページへ出力するindex.htmlを用意します。

bash

# Dockerfileを格納するディレクトリへ移動する
cd applications-qvs-demo/.valuestream/
# index.htmlを作成し、編集する
vim index.html

html

<!DOCTYPE html>
<html>
  <head>
     <title>Hello, Qmonus Value Stream!!</title>
  </head>
  <body>
    <h1>Hello, Qmonus Value Stream!!</h1>
  </body>
</html>

次にnginxのconfファイルを用意します。

bash

# nginxのconfを作成し、編集する
vim hello.conf

conf

server {
    listen 80;
    listen [::]:80;
    root /usr/share/nginx/html;
    try_files /index.html =404;
}

そして、nginxのベースイメージを利用したDockerfileを用意します。

bash

# Dockerfileを作成し、編集する
vim Dockerfile

Dockerfile

FROM nginx:latest
RUN rm /etc/nginx/conf.d/*
ADD hello.conf /etc/nginx/conf.d/
ADD index.html /usr/share/nginx/html/

4. QVS Configの編集 (CLI)

QVS Configを編集し、コンパイルするデザインパターンを指定しています。

bash

# vim でQVS Configを編集(エディタは使いなれたもので問題ありません)
vim qvs.yaml

QVS Config

build:buildkitGcp: Buildkitを用いたコンテナイメージビルドのパイプライン

DIFFCODE

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)
+ - pattern: qmonus.net/adapter/official/pipeline/build:buildkitGcp
  - pattern: qmonus.net/adapter/official/pipeline/deploy:simple
  - pattern: qmonus.net/adapter/official/pipeline/sample:resolveIPAddress

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)
  - pattern: qmonus.net/adapter/official/pipeline/build:buildkitGcp
  - pattern: qmonus.net/adapter/official/pipeline/deploy:simple
  - pattern: qmonus.net/adapter/official/pipeline/sample:resolveIPAddress

5. Pipeline Manifestの生成および登録 (CLI)

qvsctl pipeline compileコマンドを用いてPipeline Manifestを生成し、Qmonus Value Streamへ登録します。 projectName はQmonus Value StreamのProject Nameです。Project Nameは、qvsctl project list で取得したPROJECT NAMEを指定してください。

bash

# コンパイルする
qvsctl pipeline compile -m . -c qvs.yaml --prefix nginx-demo

# qvsctl auth コマンド使用して認証する（出力されたurlへアクセスしてください）
qvsctl auth

# Project Nameを取得する
qvsctl project list

# Pipeline Manifestを登録する
qvsctl pipeline apply -p ${projectName} -f output/manifests.yml

コンパイルを実行した際に3つのpipelinenginx-demo-build,nginx-demo-deploy,nginx-demo-resolve-ip-address-after-deployと6つのtasknginx-demo-git-checkout,nginx-demo-docker-login-gcp,nginx-demo-buildkit,nginx-demo-compile-design-pattern,nginx-demo-deployment-worker,nginx-demo-resolve-ip-addressが生成されることを確認してください。

6. AssemblyLineを編集する (CLI)

プライベートGitリポジトリ内の、前チュートリアルまでで利用しているAssemblyLineを編集する。

bash

#assemblyline-staging.yamlを編集(エディタ普段使用しているもので問題ありません)
vim assemblyline-staging.yaml

assemblyline-staging.yaml

DIFFCODE

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: 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: $(inputs.imageName)
+            value: $(stages.build.results.imageFullNameTag)
+     runAfter:
+       - build
    - 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)
+   - name: imageName
+     value: $(stages.build.results.imageFullNameTag)
+   - name: gitRevision
+     value: $(inputs.gitRevision)

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
    - 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)
    - name: imageName
      value: $(stages.build.results.imageFullNameTag)
    - name: gitRevision
      value: $(inputs.gitRevision)

7. AssemblyLineの更新 (CLI)

手順6で編集したAssemblyLineを更新します。

bash

# Qmonus Value Streamから実行可能なDeploy stageを持つAssemblyLine
qvsctl pipeline apply -p ${projectName} -f assemblyline-staging.yaml

git add、 git commit、 git pushを行い、リモートリポジトリに変更を反映します。

bash

# リモートリポジトリにpushする
git add --all
git commit -m "Assemblyline Extension QVS Tutorial"
git push origin getting-started

8. Deployment Configの編集 (GUI)

AssemblyLine詳細画面より、不足している下記のパラメータを入力します。

事前に準備いただいているDockerイメージの格納先を設定します。

左メニューより、AssemblyLineを選択します。
画面中央に表示される staging-deploy を選択します。
Pipeline Stagesに表示されている build カードを選択します。
画面右に表示される Edit Deployment Config ボタンをクリックします。
YAMLモードのEditorが表示されますので、Dockerイメージの格納先をYAML形式で入力します。必要なパラメータ一覧は以下の通りです。
- imageRegistryPath : イメージ名のないコンテナレジストリのパス (例：asia-northeast1-docker.pkg.dev/gcp-project/qmonus)
- imageShortName : イメージ名 (例：nginx-demo)
- imageTag : イメージタグ (例：v0.0.1)
- containerRegistry : コンテナレジストリのエンドポイント。利用しているGARのリージョンに合わせて変更してください。(例: asia-northeast1-docker.pkg.dev)
- pathToContext : Dockerfileの場所
- k8sNamespace : デプロイ先のKubernetes namespace

以下は入力例です。

Diff 入力例CODE 入力例

yaml

+ imageRegistryPath: asia-northeast1-docker.pkg.dev/gcp-project/qmonus
+ imageShortName: nginx-demo
+ imageTag: v0.0.1
+ containerRegistry: asia-northeast1-docker.pkg.dev
+ pathToContext: .valuestream
  k8sNamespace: <過去のチュートリアルの値を利用>

yaml

imageRegistryPath: asia-northeast1-docker.pkg.dev/gcp-project/qmonus
imageShortName: nginx-demo
imageTag: v0.0.1
containerRegistry: asia-northeast1-docker.pkg.dev
pathToContext: .valuestream
k8sNamespace: <過去のチュートリアルの値を利用>

Saveボタンを押下し、build, deploy の両方のInput Parameterが全て緑で表示されていることを確認します。

9. AssemblyLineの実行 (GUI)

登録したAssemblyLineを実行し、Nginx demoアプリケーションをKubernetesにデプロイします。

左メニューより、AssemblyLineを選択します。
画面中央に表示される staging-deploy を選択します。
Pipelines (Stages) に表示されている build,deploy カードを選択し、それぞれ全てのパラメータが埋まっていることを確認します。
以下のInput Parameterを入力し、 RUN ボタンを押下してCI/CDを開始します。
- gitRevision: getting-started

10. AssemblyLineが正常に完了したかを確認する (GUI/CLI)

AssemblyLineの完了後、ビルドされたコンテナイメージが正常にコンテナレジストリへ格納されていることを確認します。また、そのコンテナイメージを使って、正常にデプロイされているかを確認します。

AssemblyLineがSucceededになっているかを確認します。
ビルドされたコンテナイメージが正常にコンテナレジストリへ格納されていることを確認します
1. AssemblyLine実行画面の AssemblyLine Results: imageNameを確認します。 (例: asia-northeast1-docker.pkg.dev/gcp-project/qmonus/nginx-demo:v0.0.1)
2. GCPコンソールへアクセスし、Google Artifact Registryの画面へ移動します。
3. AssemblyLine Results: imageNameの値と同じ場所にイメージが格納されていることを確認します。

デプロイされたKubernetes Clusterを確認し、PodのimageがAssemblyLine Results: imageNameと同じのもになっているかを確認します

bash

# アプリケーションクラスタへ切り替える
$ kubectl config use-context ${アプリケーションクラスタ名}

# デプロイしたPodの確認
$ kubectl -n ${k8sNamespace} get pods
  NAME             READY   STATUS    RESTARTS   AGE
  {pod_name}   1/1     Running   0          3d10h

# Podのイメージ名を確認
$ kubectl -n ${k8sNamespace} get pod {pod_name} -o=jsonpath='{.spec.containers[0].image}'
  asia-northeast1-docker.pkg.dev/gcp-project/qmonus/nginx-demo:v0.0.1

ブラウザからデプロイされたアプリケーションへアクセスできるかを確認します。 AssemblyLine Resultsに表示されているIPアドレスへ自身のWEBブラウザからアクセスします。 http://${ipAddress}:8080 上記のアドレスへ自身のWEBブラウザからアクセスし、Hello, Qmonus Value Stream!!と出力されたWEBページが閲覧できることを確認します。

リソースの削除

チュートリアルで作成したリソースは、Getting Startedで作成したQVS ConfigのInfrastructure Adapterの定義をコメントアウトし、リモートリポジトリに変更を反映した後に、再度AssemblyLineを実行することで削除できます。詳しくは、デプロイしたリソースの削除を参照してください。

解説

Official CI/CD Adapterを用いた、Pipeline/Taskの生成

本チュートリアルでは、Getting StartedでダウンロードしたOfficial CI/CD Adapterを手順4のQVS Configの編集と手順5のqvsctl pipeline compileコマンドでコンパイルを行うことで、Pipeline/Taskを生成できました。以下に今回編集したQVS ConfigのYAML定義を示しています。今回使用したqvsctl pipeline compileコマンドでは、アプリケーションのデリバリプロセスを定義する CI/CD AdapterをKubernetes Manifestの形で展開しており、6-7行目で定義しているOfficial CI/CD Adapterのコンパイルを行っています。

yaml

designPatterns:
  - pattern: github.com/qmonus/sample/local
    params:
      k8sNamespace: $(params.k8sNamespace)
      imageName:    $(params.imageName)
+ - pattern: qmonus.net/adapter/official/pipeline/build:buildkitGcp
  - pattern: qmonus.net/adapter/official/pipeline/deploy:simple
  - pattern: qmonus.net/adapter/official/pipeline/sample:resolveIPAddress

Stage間での値の受け渡し

以下に今回利用したAssemblyLineの定義のうち、Stages定義を抜粋したものを示しています。このAssemblyLineはbuildとdeploy,resolve-ip-addressの3つのStageを順番に動作させています。 25行目のrunAfter: 指定することで Stageの実行順を指定できます。 build StageでイメージのビルドとGARにpushしたときのイメージパスを実行結果として出力し、それをdeploy Stage でそのGARのイメージパスからイメージを取得してアプリケーションをデプロイしています。 deploy Stageからbuild Stageへの値の受け渡しについては22-23行目で $(stages.build.results.imageFullNameTag)と記載し、deploy Stageのresult値を取得しています。

yaml

  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
    - name: resolve-ip-address
      spec:
        pipeline: nginx-demo-resolve-ip-address-after-deploy
        deployment:
          app: nginx-demo
          name: staging
      runAfter:
        - deploy

AssemblyLine Resultsの設定

以下に今回利用したAssemblyLineの定義のうち、Results定義を抜粋したものを示しています。 AssemblyLineでAssemblyLine Resultsを設定することで、実行されたAssemblyLineからKey-Value形式で実行結果を出力でき、AssemblyLineのPromotion時に入力パラメータとして利用できるようになります。実際のPromotion時の利用方法については、商用環境へのPromotionにて解説します。今回はipAddressというパラメータをResolve IP Address Stageから、imageNameというパラメータをbuild Stageから、gitRevisionをInput Parameterから、それぞれ出力するように設定しています。

yaml

  results:
    - name: ipAddress
      value: $(stages.resolve-ip-address.results.ipAddress)
    - name: imageName
      value: $(stages.build.results.imageFullNameTag)
    - name: gitRevision
      value: $(inputs.gitRevision)

API Backendのデプロイ

API Backendの拡張

Frontendのデプロイ

リソースの削除

API Backendのデプロイ

API Backendの拡張

Frontendのデプロイ

リソースの削除

AssemblyLineの拡張

1. Environmentの編集 (GUI)

2. Deploymentの登録 (GUI)

3. デプロイするアプリケーションの準備(CLI)

4. QVS Configの編集 (CLI)

5. Pipeline Manifestの生成および登録 (CLI)

6. AssemblyLineを編集する (CLI)

7. AssemblyLineの更新 (CLI)

8. Deployment Configの編集 (GUI)

9. AssemblyLineの実行 (GUI)

10. AssemblyLineが正常に完了したかを確認する (GUI/CLI)

解説

Official CI/CD Adapterを用いた、Pipeline/Taskの生成

Stage間での値の受け渡し

AssemblyLine Resultsの設定

AssemblyLineの拡張 ​

1. Environmentの編集 (GUI) ​

2. Deploymentの登録 (GUI) ​

3. デプロイするアプリケーションの準備(CLI) ​

4. QVS Configの編集 (CLI) ​

5. Pipeline Manifestの生成および登録 (CLI) ​

6. AssemblyLineを編集する (CLI) ​

7. AssemblyLineの更新 (CLI) ​

8. Deployment Configの編集 (GUI) ​

9. AssemblyLineの実行 (GUI) ​

10. AssemblyLineが正常に完了したかを確認する (GUI/CLI) ​

解説 ​

Official CI/CD Adapterを用いた、Pipeline/Taskの生成 ​

Stage間での値の受け渡し ​

AssemblyLine Resultsの設定 ​

AssemblyLineの拡張

1. Environmentの編集 (GUI)

2. Deploymentの登録 (GUI)

3. デプロイするアプリケーションの準備(CLI)

4. QVS Configの編集 (CLI)

5. Pipeline Manifestの生成および登録 (CLI)

6. AssemblyLineを編集する (CLI)

7. AssemblyLineの更新 (CLI)

8. Deployment Configの編集 (GUI)

9. AssemblyLineの実行 (GUI)

10. AssemblyLineが正常に完了したかを確認する (GUI/CLI)

解説

Official CI/CD Adapterを用いた、Pipeline/Taskの生成

Stage間での値の受け渡し

AssemblyLine Resultsの設定