Skip to content

Getting Started

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

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

  • デプロイ先環境: Google Kubernetes Engine (GKE)

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

Qmonus Value Stream Getting Started

以降のステップでは、以下の図で示すようにDeploy Stageからのみ構成されるCI/CDパイプラインを構築します。

  • Step 1では、Qmonus Value Streamに、アプリケーションや環境情報を設定することでDeployment Parametersを準備します。
  • Step 2では、持ち込みリポジトリに、NginxコンテナアプリケーションをデプロイするためのInfrastructure as Code (Cloud Native Adapter)を準備します。
  • Step 3では、Qmonus Value StreamにCI/CDパイプラインを構築します。
  • 最後にStep 4では、Qmonus Value StreamのCI/CDパイプラインを実行することで、持ち込みクラスタにNginxコンテナアプリケーションをデプロイします。
Qmonus Value Stream CI/CDイメージ図

本チュートリアルでは、GUIおよびCLIでのAPI操作を組み合わせてCI/CDパイプラインを構築していきます。作成するQmonus Value StreamのAPIリソースについてはリソース説明を参照してください。

0. 事前準備

事前準備として、以下の図に示すように、再利用可能なCI/CDパイプラインを含んでいるOfficial Cloud Native Adapterをアプリケーションリポジトリにダウンロードします。公式のモジュールを利用することで、クラスタへコンテナをデプロイするための処理を一から作成する必要がありません。

また、持ち込みのKubernetesクラスタへコンテナをデプロイするための認証ファイルを作成します。作成したKubeconfigは、後のステップでDeployment Parametersに登録します。

Getting Started - Preparation

0-1. Official Cloud Native Adapterのダウンロード

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

Info

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

  1. https://github.com/new にアクセスします。
  2. 以下のようにパラメータの選択・入力します。
    • Owner:(リポジトリを置くOwnerを選択)
    • リポジトリ名:applications-qvs-demo
    • Description: 任意
    • Private にチェック
  3. ページ下部の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

0-2. Kubeconfigの作成 (CLI)

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

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

bash
# 利用するKubernetesへ接続
gcloud --project=${gcp_project_id} container clusters get-credentials ${cluster_name} --zone ${zone}

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

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

手順通りに実行するとKubeconfigはoutput.kubeconfig.yamlというファイルで生成されます。 なお、gcloudコマンドをはじめて実行する場合は、gcloud auth loginコマンドにより、gcloudコマンドを初期化してください。

1. Deployment Parametersの登録

以下の図に示すように、Qmonus Value Streamにアプリケーションをステージング環境相当にデプロイするための設定 Deployment を登録します。

Getting Started - Deployment Parameters

1-1. Applicationの登録 (GUI)

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

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

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

Applicationの登録

1-1a. Repositoryの登録

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

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

1-2. Deploymentの登録 (GUI)

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

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

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

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

Deploymentの登録

1-2a. 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を特定できるエイリアス名を付与してください。

2. Infrastructure as Codeの準備

以下の図に示すように、アプリケーションリポジトリにInfrastructure as Code (Cloud Native Adapter)とQmonus Value Streamの設定ファイルを準備します。

Getting Started - IaC

2-1. Infrastructure Adapterの作成 (CLI)

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

bash
vim local/main.cue

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

go
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で保存して終了します。

2-2. 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

3. CI/CDパイプラインの登録

以下の図に示すように、Qmonus Value StreamにCI/CD パイプラインを登録します。Pipeline/Taskリソースは、QVS Configを使って自動生成します。AssemblyLineリソースは直接編集して登録します。

パイプラインリソースについては、CI/CDパイプラインリソース説明を参照してください。

Getting Started - CI/CD Pipelines

3-1. Pipeline Manifestの生成および登録 (CLI)

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

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

NameDescription
TaskCI/CDパイプライン中に実行する最小単位の処理の定義
PipelineTaskを順序制御するための定義

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

まずは、qvsctlにて、Pipeline Manifestのコンパイルを行います。 --prefixによるPipeline/Taskのプレフィックスには、手順1-1で登録した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クラスタにアクセスしています。このクラスタは、手順0-2で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がそれぞれ登録されることを確認してください。

3-2. AssemblyLineの作成と登録 (CLI)

Pipelineを直列・並列に組み合わせて、ビルド・デプロイ・リリースまでのCI/CDタスクを一気通貫で行うワークフローの定義である、AssemblyLineを作成・登録します。本チュートリアルでは、KubernetesでアプリケーションをデプロイするだけのCI/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を登録します。 手順3-1と同じディレクトリで以下を実行してください。

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

3-3. AssemblyLineの確認 (GUI)

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

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

3-4. Deployment Configの登録 (GUI)

手順3-3で表示したAssemblyLine詳細画面より、不足しているパラメータを設定します。今回のチュートリアルだとnamespace(デプロイ先のKubernetes Namespace)を設定します。

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

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

4. CI/CD パイプラインの実行

以下の図に示すように、Qmonus Value Streamに登録したCI/CDパイプラインを実行し、アプリケーションをデプロイします。

Getting Started - Deploy

4-1. AssemblyLineの実行 (GUI)

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

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

4-2. AssemblyLineの確認 (GUI)

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

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

4-3. デプロイされたサンプルアプリケーションの確認 (GUI)

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

アプリケーションの確認

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

アプリケーションの確認

リソースの削除

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

解説

AssemblyLineとProjectリソースの関係

以下に今回利用したAssemblyLineのYAML定義を示しています。このAssemblyLineは、Stage定義に手順3-1で登録したTekton Pipeline名を指定しています (14行目) 。 これに加えて、15-17行目でApplication nginx-demoのDeployment stagingを指定しています。この設定によって、手順1-2で作成したDeploymentをこのAssemblyLineに紐づけています。Qmonus Value Streamはここで解決した紐づけを元に、手順1-2および手順3-4で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 9行目)。読み出される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から、本番環境へ同アプリケーションをデプロイする