Getting Started

本章では、Qmonus Value Streamを使って、シンプルなAPIサーバを検証環境(e.g. Staging)にデプロイするまでの手順を解説します。

本チュートリアルを実施するまえに、事前準備が完了していることをご確認ください。事前準備以外に作成が必要なリソースは以下の通りです。

デプロイ先環境: Azure Kubernetes Service (AKS)

本手順でデプロイするアプリケーションは、以下の図に示すように、Kubernetes DeploymentリソースとService (type: LoadBalancer) リソースで構成されるシンプルなHTTP APIサーバです。

以降のステップでは、具体的にDeploy Stageからのみ構成されるCDパイプラインを構築します。Deploy Stageとは、Cloud Native Adapter(モジュール化されたソフトウェアを動かすクラウド基盤構成) をコンパイルしてApplication Manifestを生成し、そのManifestをAKSに適用する、パイプラインです。このパイプラインでは、Application Manifest中で利用するコンテナイメージ名は、パイプライン実行時にインプットとして渡します。

本チュートリアルでは、GUIでの操作とCLIでのAPI操作を組み合わせてCDパイプラインを構築していきます。作成するAPIリソースについては、リソース相関図を参照してください。

0. 事前準備

事前作業として、プライベートリポジトリの作成とOfficial Cloud Native Adapterをダウンロードし、作業環境を構築します。まずは、持ち込みのGitHubアカウントでプライベートリポジトリを作成します。

Info

本チュートリアルではリポジトリプロバイダとしてGitHubを使用しますが、Bitbucket/GitLab/Backlogも利用可能です。また、リポジトリをCloneする際のプロトコルとしてはhttps/sshから選択できます。 (BitbucketとBacklogはsshのみの対応) 詳細についてはProjectリソースの作成-Repositoryの登録を参照してください。

https://github.com/new にアクセスします。
以下のようにパラメータの選択・入力します。
- Owner：（リポジトリを置くOwnerを選択）
- リポジトリ名：applications-qvs-demo
- Description：任意
- Private にチェック
ページ下部のCreate repository を押下します。

次に、本チュートリアル用のディレクトリを作成し、Official Cloud Native Adapterをダウンロードします。

bash

# プライベートリポジトリをcloneする
git clone https://github.com/${your_organization}/applications-qvs-demo.git

# プライベートリポジトリに移動
cd applications-qvs-demo

# 本チュートリアル用のディレクトリを作成する
mkdir -p .valuestream/local
cd .valuestream

# CUEのImportパスを管理するファイルである module.cueを生成する
cue mod init github.com/qmonus/sample

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

# Official Cloud Native Adapter でダウンロードできるパッケージの確認
qvsctl adapter list

NAME                         LATEST  RELEASED DATE
qmonus.net/adapter/official  vx.x.x  YYYY-MM-DD hh:mm:ss

# Official Cloud Native Adapterをダウンロードする
qvsctl adapter get qmonus.net/adapter/official

# gitへpushする
git add --all
git commit -m "Qmonus Value Stream Official Adapter"
git push

1. Kubeconfigの作成 (CLI)

Qmonus Value Streamは、Kubeconfigと呼ばれる認証ファイルを利用してKubernetesへアプリケーションをデプロイします。ここでは、今回デプロイする対象のKubernetes Namespaceに権限を持つKubeconfigを生成します。

以下の手順にしたがって、ユーザ自身で準備いただいたKubernetesクラスタにアクセスし、Kubeconfigを生成してください。ここで、 cluster_name はKubernetesクラスタ名、 resource_group はAzure Resource Group名を指定します。k8sNamespaceは、今回デプロイするKubernetes Namespace名です。ここで指定したNamespace名は、以降の手順でCDパイプラインを実行する際に、実行パラメータとして使用されます。

bash

# 利用するKubernetesへ接続
az aks get-credentials --admin --name ${cluster_name} --resource-group ${resource_group}

# Kubeconfigの生成
qvsctl plugin gen-kubeconfig -n ${k8sNamespace}

# KubeconfigをGitリポジトリの管理から除外
echo 'output.kubeconfig.yaml' >> /path/to/your/repository/.gitignore

手順通りに実行するとKubeconfigはoutput.kubeconfig.yamlというファイルで生成されます。なお、azコマンドをはじめて実行する場合は、以下の手順によりazコマンドを初期化してください。ここで、tenant_idはonmicrosoft.comで終わるAzureドメイン名です。

bash

az login --tenant ${tenant_id}

2. Applicationの登録 (GUI)

今回利用するサンプルアプリケーションを登録します。本手順では、Repositoryの登録も併せて行います。アプリケーションに必要なリソースを作成し、手順5で保存するQVS Config (利用するCloud Native Adapter等を指定するQmonus Value Stream設定ファイル) のパスを指定します。 Qmonus Value Streamは本手順によって、Cloud Native Adapterの構成を定義したQVS Configを読み出します。

左メニューより、Applicationを選択します。
画面右上の NEW APPLICATION ボタンを押下します。
各フォームに以下の値を入力し、画面右下の NEXT ボタンを押下します。
- Display Name: Nginx demo
- Description: (任意の文章または空白)
- QVS Config Repository: + Create New Repositoryを選択し、手順2-aに従いRepositoryを作成
- QVS Config File Path: .valuestream/qvs.yaml

以下は、必要な値を入力した状態のApplicationの登録画面になります。

Applicationの登録

2-a. Repositoryの登録

今回利用するサンプルアプリケーションをホストしているGit Repositoryを登録します。ここで設定した情報はQmonus Value StreamがCI/CDパイプライン実行中に読み出すリポジトリ情報として利用されます。

各フォームに以下の値を入力し、画面右下のCREATEボタンを押下します。

Repository Kind: github
Git Clone Protocol: https
Repository Visibility: private
Git Clone URL: https://github.com/`{自身のOrganization}`/applications-qvs-demo.git
Description: (任意の文章または空白)
Git Token:（プライベートリポジトリへの認証に利用するTokenを入力）

3. Deploymentの登録 (GUI)

手順2を実施後、自動的にDeploymentの登録画面に遷移します。 Deploymentリソースは、指定したApplicationを指定したEnvironmentにデリバリするための定義で、Environmentを指定して作成します。本手順では、Environmentを登録します。ここでは、手順2のNginx demo Applicationを、Staging環境にデプロイするための設定を作成します。さらに、Deployment作成時に手順1で作成したKubeconfigを登録します。

各フォームに以下の値を入力し、画面右下の CREATE ボタンを押下します。

Display Name: staging
Name: (Environment選択時に自動入力)
Environment: + Create New Environmentを選択し、手順3-aに従いEnvironmentを作成
- 注) Application単位で、同一Environmentを選択できません
Credentials
- kubeconfig: 手順1で生成したKubeconfig
- 注) 生成したKubeconfigのテキストデータを、改行などを含めず全て貼り付けて登録します

以下は、必要な値を入力した状態のDeploymentの登録画面になります。

Deploymentの登録

3-a. Environmentの登録

デプロイ先となる環境を登録します。検証環境、商用環境といった、プロジェクト／プロダクトに応じて任意の環境を定義してください。今回はサンプルとして、検証環境(e.g. Staging)としてチュートリアルを進めます。また、Qmonus Value Streamが推奨する環境の考え方については、環境定義を参考にしてください。

各フォームに以下の値を入力し、画面右下のCREATEボタンを押下します。

Display Name: staging
Description: (任意の文章または空白)
Provisioning Target:
- Kind:kubernetes
- DisplayName: Provisioning Targetを一意に指定できるNameやID
- Alias:（空白）
- 同じタイプのProvisioning Targetを複数登録する際は、2つ目以降については AliasのフォームにそのProvisioning Targetを特定できるエイリアス名を付与してください。

4. Infrastructure Adapterの作成 (CLI)

今回デプロイするアプリケーションの構成ファイルとしてInfrastructure Adapterを作成します。 Infrastructure Adapterについての詳しい説明はInfrastructure Adapterへの変換のチュートリアルで行いますが、今回は下記の通り、コピーしてファイルを作成してください。まずはvim(他のエディタでも可)でlocalディレクトリ配下にmain.cueというファイルを作成します。

bash

vim local/main.cue

main.cueには下記の内容を記載します。

package local

_const: {
	#name: "nginx-demo"
	#port: 80
}

DesignPattern: {
	name: "local"

	parameters: {
		k8sNamespace: string
		imageName:    string
	}

	resources: app: {
		deployment: _deployment
		service:    _service
	}

	let _selector = {
		app: _const.#name
	}
	let _container = {
		name:  _const.#name
		image: parameters.imageName
		ports: [{
			containerPort: _const.#port
		}]
		resources: {
			requests: {
				cpu:    "5m"
				memory: "32Mi"
			}
			limits: {
				cpu:    "10m"
				memory: "64Mi"
			}
		}
	}
	_deployment: {
		apiVersion: "apps/v1"
		kind:       "Deployment"
		metadata: name: _const.#name
		spec: {
			replicas: 1
			selector: matchLabels: _selector
			template: {
				metadata: labels: _selector
				spec: containers: [
					_container,
				]
			}
		}
	}

	_service: {
		apiVersion: "v1"
		kind:       "Service"
		metadata: name: _const.#name
		spec: {
			type: "LoadBalancer"
			ports: [{
				name: "http"
				port: 8080
				targetPort: _const.#port
			}]
			selector: _selector
		}
	}

	// apply namespace
	_deployment: metadata: namespace: parameters.k8sNamespace
	_service: metadata: namespace:    parameters.k8sNamespace
}

vimの場合wqで保存して終了します。

5. QVS Configの作成 (CLI)

Qmonus Value Streamの設定ファイルであるQVS Configを作成します。ここでは、利用するCloud Native Adapterを指定できます。 vimでqvs.yamlという名前のファイルを.valuestreamディレクトリ直下に作成します。

bash

vim qvs.yaml

qvs.yamlへ記載する内容は下記の通りです。

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

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

手順5で作成したQVS Configを用いてPipeline Manifestを生成し、Qmonus Value Streamへ登録します。

今回コンパイルして生成されるPipeline ManifestにはTekton TaskとTekton Pipelineの2つの要素を含みそれぞれ下記のような役割を持ちます。

Name	Description
Task	CI/CDパイプライン中に実行する最小単位の処理の定義
Pipeline	Taskを順序制御するための定義

Qmonus Value Streamでは、1つのPipelineを"Stage"と定義しています。今回はTekton Taskを逐次実行するDeploy用Pipelineを登録します。 Tekton Pipelineは、逐次実行に加えて、並列でTekton Taskを実行することも可能です。

まずは、qvsctlにて、Pipeline Manifestのコンパイルを行います。 --prefixで指定するPipeline/Taskのプレフィックスには、手順2で登録したApplication名:nginx-demoを指定します（ApplicationのDisplay NameはNginx demoですが、Application名は大文字と空白がそれぞ小文字とハイフンに補完されます。）。

bash

# コンパイルを行う
qvsctl pipeline compile -m . -c qvs.yaml --prefix nginx-demo

次に、生成されたPipeline ManifestをQmonus Value Streamへ登録します。ここで、projectName はQmonus Value StreamのProject Nameです。Project Nameは、qvsctl project list で取得したPROJECT NAMEを指定してください。

WARNING

以降、qvsctl pipeline applyコマンドを使って、Tekton Task、Pipeline、さらにはAssemblyLineを登録していきます。ここではQmonus Value StreamのKubernetesクラスタにアクセスしています。このクラスタは、手順1でKubeconfigを作成した、これからアプリケーションをデプロイしようとしているクラスタとは別のものです。

bash

# Project Nameを取得する
qvsctl project list
# applyを行う
qvsctl pipeline apply -p ${projectName} -f output/manifests.yml

applyを実行した際に、プレフィックスの付与された、2つのpipelinenginx-demo-deploy,nginx-demo-resolve-ip-address-after-deployと4つのtasknginx-demo-git-checkout,nginx-demo-compile-design-pattern,nginx-demo-deployment-worker,nginx-demo-resolve-ip-addressがそれぞれ登録されることを確認してください。

7. AssemblyLineの作成と登録 (CLI)

Pipelineを直列・並列に組み合わせて、ビルド・デプロイ・リリースまでのCI/CDタスクを一気通貫で行うワークフローの定義である、AssemblyLineを作成・登録します。本チュートリアルでは、KubernetesでアプリケーションをデプロイするだけのCDパイプラインを作成します。

bash

vim assemblyline-staging.yaml

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-staging.yamlを登録します。手順6と同じディレクトリで以下を実行してください。

bash

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

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

bash

# 本チュートリアル用のブランチを作成する
git checkout -b getting-started

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

8. AssemblyLineの確認 (GUI)

CLIで登録したAssemblyLineをGUIから確認します。手順7で登録したAssemblyLine staging-deploy 設定を確認します。

左メニューより、AssemblyLineを選択します。
画面中央に表示される staging-deploy を選択します。
AssemblyLineと構成するPipeline Stagesが表示されることを確認します。
Pipeline Stagesに表示されている deploy カードを選択します。
利用されるパラメータ一覧が表示されることを確認します。
- 未設定のパラメータk8sNamespaceが赤く表示されることを確認します。

9. Deployment Configの登録 (GUI)

手順8で表示したAssemblyLine詳細画面より、不足しているパラメータ:k8sNamespace(デプロイ先のKubernetes Namespace)を設定します。

ここで設定するNamespaceは、手順1でKubeconfigを作成したときに指定したNamespaceと同じものを指定してください。 Kubeconfigが指定するNamespace以外は権限がないためデプロイできません。Kubeconfigの生成を他のクラスタ管理者が実施した場合、利用すべきNamespaceをクラスタ管理者に問い合わせてください。

画面右に表示される Edit Deployment Config リンクを選択します。
YAMLモードのEditorが表示されますので、デプロイ先のKubernetes Namespace情報をYAML形式で入力します。
- Key: k8sNamespace
- Value: (利用するNamespace名)
  yaml
```
k8sNamespace: <利用するNamespace名>
```
Saveボタンを押下し、更新後のパラメータ一覧全てが緑で表示されていることを確認します。
- 赤く表示されているパラメータがある場合、足りないパラメータがあるため、AssemblyLineを実行できません。

10. AssemblyLineの実行 (GUI)

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

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

11. AssemblyLineの確認 (GUI)

手順10実行後、自動的にAssemblyLineの進捗画面に遷移します。この画面で、AssemblyLineのステータス、ログ、イベントといったAssemblyLineの進捗を確認できます。

ステータスの確認
- Pipelines (Stages) に各Pipelineのステータスが表示されます。
- 表示されている deploy カードを選択することで、deploy stageの中で実行されるTekton Taskのステータスが確認できます。
ログの確認
- ページ下部のTimelineに各Taskの詳細画面が表示されます。
- Task名を選択すると、Taskの中で実行済みおよび実行中のStepが表示されます。
- Step名を選択すると、Step中のログが確認できます。
イベントの確認
- 画面右上のEVENTSボタンを押下することで、AssemblyLineの実行に関するイベントを確認できます。
- Pipeline、Taskそれぞれのイベントについては、それぞれのカードに表示されているルーペ (虫眼鏡) のアイコンをクリックすることで確認できます。

12. デプロイされたサンプルアプリケーションの確認 (CLI)

Kubernetesにアクセスして、デプロイに成功したアプリケーションを確認します。 AssemblyLine Resultsに表示されているIPアドレスはサンプルアプリケーションにアサインされたグローバルIPアドレスです。ブラウザから http://$:8080 にアクセスします。

アプリケーションの確認

以下のようにWEBブラウザ上からNginxのwelcomeページにアクセスできれば完了です。

アプリケーションの確認

リソースの削除

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

解説

AssemblyLineとProjectリソースの関係

以下に今回利用したAssemblyLineのYAML定義を示しています。このAssemblyLineは、Stage定義に手順5で登録したTekton Pipeline名を指定しています (14行目) 。これに加えて、15-17行目でApplication nginx-demoのDeployment stagingを指定しています。この設定によって、手順3で作成したDeploymentをこのAssemblyLineに紐づけています。Qmonus Value Streamはここで解決した紐づけを元に、手順2-3および手順9でGUIを通して設定したProjectリソース情報をAssemblyLineの実行パラメータにバインドし、CI/CDパイプラインを実行しています。

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)

Cloud Native Adapter

本チュートリアルでManifestの生成に利用したCloud Native Adapterはアプリケーションリポジトリに格納しています。具体的には、 QVS ConfigでCloud Native Adapterの読み出し先としてローカルディレクトリを指定しています(qvs.yaml 10行目)。読み出されるCloud Native Adapterは local/main.cue です。このCloud Native Adapterで、Kubernetes、Deployment、ServiceリソースのManifestの生成ロジックを定義しています。なお、Cloud Native Adapterについては、ローカルディレクトリではなく、リモートGitリポジトリを指定できます。Cloud Native Adapterが複雑化してきたタイミングで、リポジトリを分けて管理することを推奨しています。

本Cloud Native Adapterでは、input parameterとして、[k8sNamespace, imageName]を定義してます(main.cue 11-14行目)。さらには、 QVS Config側で、このparametersをPipelineから受け取るよう宣言しています(qvs.yaml 1-5行目)。k8sNamespaceについては、手順11で明示的に設定しており、その値がAssemblyLine実行時に自動でバイドされます。imageName については、AssemblyLineのinputパラメータとして指定しているので、AssemblyLine実行のたびにユーザが指定します。

次のステップ

本チュートリアル後、以下のようなシナリオでQmonus Value Streamを利用いただくことで、Qmonus Value Streamの機能を理解いただけます。

Cloud Native Adapterの拡張：本チュートリアルのCloud Native Adapterを参考にManifestを拡張する
AssemblyLine の拡張：Docker imageをビルドするbuild stageを導入して、CI/CDパイプラインを拡張する
商用環境へのPromotion：ステージング環境へアプリケーションをデプロイするAssemblyLineから、本番環境へ同アプリケーションをデプロイする

API Backendのデプロイ

API Backendの拡張

Frontendのデプロイ

リソースの削除

API Backendのデプロイ

API Backendの拡張

Frontendのデプロイ

リソースの削除

Getting Started

0. 事前準備

1. Kubeconfigの作成 (CLI)

2. Applicationの登録 (GUI)

2-a. Repositoryの登録

3. Deploymentの登録 (GUI)

3-a. Environmentの登録

4. Infrastructure Adapterの作成 (CLI)

5. QVS Configの作成 (CLI)

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

7. AssemblyLineの作成と登録 (CLI)

8. AssemblyLineの確認 (GUI)

9. Deployment Configの登録 (GUI)

10. AssemblyLineの実行 (GUI)

11. AssemblyLineの確認 (GUI)

12. デプロイされたサンプルアプリケーションの確認 (CLI)

解説

AssemblyLineとProjectリソースの関係

Cloud Native Adapter

次のステップ

Getting Started ​

0. 事前準備 ​

1. Kubeconfigの作成 (CLI) ​

2. Applicationの登録 (GUI) ​

2-a. Repositoryの登録 ​

3. Deploymentの登録 (GUI) ​

3-a. Environmentの登録 ​

4. Infrastructure Adapterの作成 (CLI) ​

5. QVS Configの作成 (CLI) ​

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

7. AssemblyLineの作成と登録 (CLI) ​

8. AssemblyLineの確認 (GUI) ​

9. Deployment Configの登録 (GUI) ​

10. AssemblyLineの実行 (GUI) ​

11. AssemblyLineの確認 (GUI) ​

12. デプロイされたサンプルアプリケーションの確認 (CLI) ​

解説 ​

AssemblyLineとProjectリソースの関係 ​

Cloud Native Adapter ​

次のステップ ​

Getting Started

0. 事前準備

1. Kubeconfigの作成 (CLI)

2. Applicationの登録 (GUI)

2-a. Repositoryの登録

3. Deploymentの登録 (GUI)

3-a. Environmentの登録

4. Infrastructure Adapterの作成 (CLI)

5. QVS Configの作成 (CLI)

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

7. AssemblyLineの作成と登録 (CLI)

8. AssemblyLineの確認 (GUI)

9. Deployment Configの登録 (GUI)

10. AssemblyLineの実行 (GUI)

11. AssemblyLineの確認 (GUI)

12. デプロイされたサンプルアプリケーションの確認 (CLI)

解説

AssemblyLineとProjectリソースの関係

Cloud Native Adapter

次のステップ