Appearance
Getting Started
本章では、Qmonus Value Streamを使って、シンプルなAPIサーバを検証環境(e.g. Staging)にデプロイするまでの手順を解説します。
本チュートリアルを実施するまえに、 事前準備が完了していることをご確認ください。 事前準備以外に作成が必要なリソースは以下の通りです。
- デプロイ先環境: Google Kubernetes Engine (GKE)
本手順でデプロイするアプリケーションは、以下の図に示すように、Kubernetes DeploymentリソースとService (type: LoadBalancer) リソースで構成されるシンプルなHTTP APIサーバです。
以降のステップでは、以下の図で示すように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コンテナアプリケーションをデプロイします。
本チュートリアルでは、GUIおよびCLIでのAPI操作を組み合わせてCI/CDパイプラインを構築していきます。作成するQmonus Value StreamのAPIリソースについてはリソース説明を参照してください。
0. 事前準備
事前準備として、以下の図に示すように、再利用可能なCI/CDパイプラインを含んでいるOfficial Cloud Native Adapterをアプリケーションリポジトリにダウンロードします。公式のモジュールを利用することで、クラスタへコンテナをデプロイするための処理を一から作成する必要がありません。
また、持ち込みのKubernetesクラスタへコンテナをデプロイするための認証ファイルを作成します。作成したKubeconfigは、後のステップでDeployment Parametersに登録します。
0-1. Official Cloud Native Adapterのダウンロード
プライベートリポジトリの作成と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
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
を登録します。
1-1. Applicationの登録 (GUI)
今回利用するサンプルアプリケーションを登録します。本手順では、Repositoryの登録も併せて行います。 アプリケーションに必要なリソースを作成し、手順2-2で保存する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
を選択し、手順1-1aに従いRepositoryを作成 - QVS Config File Path: .valuestream/qvs.yaml
以下は、必要な値を入力した状態のApplicationの登録画面になります。
1-1a. 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を入力))
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の登録画面になります。
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を特定できるエイリアス名を付与してください。
- Kind:
2. Infrastructure as Codeの準備
以下の図に示すように、アプリケーションリポジトリにInfrastructure as Code (Cloud Native Adapter)とQmonus Value Streamの設定ファイルを準備します。
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パイプラインリソース説明を参照してください。
3-1. Pipeline Manifestの生成および登録 (CLI)
手順2-2で作成した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のプレフィックスには、手順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
設定を確認します。
- 左メニューより、AssemblyLineを選択します。
- 画面中央に表示される
staging-deploy
を選択します。 - AssemblyLineと構成するPipeline Stagesが表示されることを確認します。
- Pipeline Stagesに表示されている
deploy
カードを選択します。 - 利用されるパラメータ一覧が表示されることを確認します。
- 未設定のパラメータ
k8sNamespace
が赤く表示されることを確認します。
- 未設定のパラメータ
3-4. Deployment Configの登録 (GUI)
手順3-3で表示したAssemblyLine詳細画面より、不足しているパラメータを設定します。今回のチュートリアルだとnamespace
(デプロイ先のKubernetes Namespace)を設定します。
ここで設定するNamespaceは、手順0-2でKubeconfigを作成したときに指定したNamespaceと同じものを指定してください。 Kubeconfigが指定するNamespace以外は権限がないためデプロイできません。Kubeconfigの生成を他のクラスタ管理者が実施した場合、利用すべきNamespaceをクラスタ管理者に問い合わせてください。
- 画面右に表示される
Edit Deployment Config
リンクを選択します。 - YAMLモードのEditorが表示されますので、デプロイ先のKubernetes Namespace情報をYAML形式で入力します。
- Key: k8sNamespace
- Value: (利用するNamespace名)yaml
k8sNamespace: <利用するNamespace名>
Save
ボタンを押下し、更新後のパラメータ一覧全てが緑で表示されていることを確認します。- 赤く表示されているパラメータがある場合、足りないパラメータがあるため、AssemblyLineを実行できません。
4. CI/CD パイプラインの実行
以下の図に示すように、Qmonus Value Streamに登録したCI/CDパイプラインを実行し、アプリケーションをデプロイします。
4-1. AssemblyLineの実行 (GUI)
登録したAssemblyLineを実行し、Nginx demoアプリケーションをKubernetesにデプロイします。
- 左メニューより、AssemblyLineを選択します。
- 画面中央に表示される
staging-deploy
を選択します。 - Pipelines (Stages) に表示されている
deploy
カードを選択し、全てのパラメータが埋まっていることを確認します。 - 以下の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から、本番環境へ同アプリケーションをデプロイする