Qmonus SDK Lab

# ユーザクラウド

ユーザクラウドとして使用できるものは、以下となります。

利用できるクラウドサービス

  • GKE (Google Kubernetes Engine)
  • Amazon EKS (Elastic Kubernetes Service)

Qmonus SDK LabではKubernetesクラスタ単位ではなくKubernetesネームスペース単位での登録も可能です。
※Amazon EKSをご利用の場合は、Kubernetesネームスペース単位での登録のみ利用可能です。

※以降の手順は、GKEでの利用を前提として記載しています。



# 対応バージョン

# Kubernetes v1.35 - v1.36

GKEのリリースチャンネルRegular/Stableにおける最新2バージョンをサポート予定となります。


GKEのversion up

通常の環境作成機能を使用して環境を構築している場合、GKEのversion upを行う際はversion up前に既存の環境を削除し、version up後に再度環境を作成し直すようお願いいたします。
version upの際にQmonusを構成するコンポーネント (Pod) が順不同に削除および再作成されることでQmonusコンポーネント間の同期がとれなくなる可能性があります。
※ VS連携（マルチクラウドデプロイ機能）をご利用の場合は、環境の削除・再作成は不要です。



# テンプレートを使用してクラスタを準備する

テンプレートをご利用いただくことでスムーズに作成することができます。

すでにご用意いただいているクラスタ、ネームスペースを使用したい場合は以下へお進みください。
→ 既存のKubernetesクラスタを使用する場合
→ 既存のKubernetesネームスペースを使用する場合


GCP(GKE) 向け手順

ここでは、Qmonus SDK Labチームの用意したファイル、コマンドを使用し必要なGCPクラウド設定を行うまでを説明します。

前提条件



# 1. ファイルをダウンロードする

Qmonus SDK Labチームが作成した以下の2つのファイルをダウンロードします。



# 2. フォルダの作成、ファイルの再配置

PCに以下のようなツリー構造のフォルダを作成し、ダウンロードしたファイルを下図のように配置してください。
※[project name]は作成いただいたGCPプロジェクトのものを選んでください。

(ユーザディレクトリなど)
└── [project name]
    └── gcp
        └── environments
            ├── dev01
            │   ├── template.tf
            │   └── project-setup.sh
            ├── stg01
            │   ├── ...
            │   ├── ...
            │   └── ...
            └── prod01
                ├── ...
                ├── ...
                └── ...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15


# 3. テンプレートへの入力 ( project-setup.sh )

project-setup.sh を開き、以下の値を設定します。

#!/usr/bin/env bash
PJ_ID="qmonus-hoge-project-12345678"                # GKEのプロジェクトID
QMONUS_SRE_MAINTENANCE_GROUP="hoge@example.com"      # Google グループのグループメールアドレス
TERRAFORM_BUCKET_NAME="sample-qmonus-cloud-bucket"   # GCS bucket名
1
2
3
4
変数 例 説明
PJ_ID qmonus-hoge-project-12345678 GKEのプロジェクトID (opens new window)
QMONUS_SRE_MAINTENANCE_GROUP hoge@example.com Google グループのグループメールアドレス (opens new window)。GKEプロジェクトをメンテナンスするメンバーを所属させます。以降の手順で実施するTerraform操作の実行権限が付与されます
TERRAFORM_BUCKET_NAME sample-qmonus-cloud-bucket GCS bucket名。以降の手順でproject-setup.shを実行した際、ここに記載した名前で作成されます


# 4. テンプレートへの入力 ( template.tf )

template.tf を開き、以下の default 値を設定します。

variable "dev01_project" {
  default = "qmonus-hoge-project-12345678"
}

variable "region" {
  default = "asia-northeast1"
}

variable "maintenance_group" {
  ## google group which contains SRE member's mailaddress
  ## or your email address and so on
  default = "hoge@example.com"
}

variable "allowed_networks" {
  ## GIP of qmonus user's house / VPN Server
  default = [
    "127.0.0.1/32"
  ]
}

variable "cluster_version" {
  ## Version of master and node pool
  default = "1.23.11-gke.300"
}

variable "node_count" {
  ## The number of nodes per instance group.
  default = "3"
}

terraform {
  required_version = "1.0.0" # specify terraform version
  backend "gcs" {
    bucket = "sample-qmonus-cloud-bucket" # Defined by manually by project-setup.sh
  }
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "3.90.1"
    }
    google-beta = {
      source  = "hashicorp/google-beta"
      version = "3.90.1"
    }
    template = {
      source  = "hashicorp/template"
      version = "2.2.0"
    }
    random = {
      source  = "hashicorp/random"
      version = "3.1.0"
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
変数 例 説明
dev01_project qmonus-hoge-project-12345678 GKEのプロジェクトID。手順3で入力したプロジェクトIDと同じ値に書き換える。
region asia-northeast1 希望するリージョン (opens new window)。ここで記載したリージョンにクラスタが配置されます（例: asia-northeast1(東京) など）
maintenance_group hoge@example.com Google グループのグループメールアドレス。手順3で入力したメールアドレスと同じ値に書き換える。
allowed_networks 127.0.0.1/32 アクセス元のGIP(個人宅やVPNサーバーのGIP等)を指定する。事前にCloud Armor (opens new window)にて通信を許可するIPアドレスレンジの定義が必要です
cluster_version 1.23.11-gke.300 クラスタのバージョン (opens new window)。適切なバージョンに書き換える。
node_count 3 クラスタを構成するインスタンスグループ単位のノード数。例としてasia-northeast1にはzoneが3つあるため、指定した数×3のノードが合計で構築されます。目安として標準的な構成であれば2~3程度の開発環境が1つのノードに収容可能です
required_version 1.0.0 Terraformのバージョン。terraform --version で確認できます
bucket sample-qmonus-cloud-bucket GCS bucket名。手順3で入力したbucket名と同じ値に書き換える。


# 5. APIの有効化

APIを有効化します。以下のコマンドを入力してください。

# 5-1. ログイン
gcloud auth login

# 5-2. 新しいコンフィグの作成（${config_name}には任意の名前を入力してください）
gcloud config configurations create ${config_name}

# 5-3. defaultのGCPプロジェクトを設定
gcloud config set project ${project_name}

# 5-4. defaultのアカウントを設定
gcloud config set account ${account}

# 5-5. 現在のプロジェクトで ID及びアクセス管理、サービスアカウントの作成を有効にする
gcloud services enable iam.googleapis.com

# 5-6. 現在のプロジェクトで Pub/Sub API サービスを有効にする
gcloud services enable serviceusage.googleapis.com
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17


# 6. terraform実行権限の追加

以下のコマンドを実行し、google groupのメンバーにterraform実行権限を与えます。

# environments/dev01/ で実行
sh project-setup.sh
1
2


# 7. クラスタの作成

以下のコマンドを実行し、クラスタの作成を開始します。

# environments/dev01/ で実行
terraform init
terraform apply
1
2
3

terraformのapply完了後は必要なリソースが作成されている状態です。
Outputsとして以下の情報が出力されますのでお控えください。

# apply完了後に出力される情報詳細

  • cluster_ip

    • 作成したクラスタにおけるコントロールプレーンのIPアドレスです。
    • Qmonus SDK Labの環境を作成する際、クラウドサービス設定にて利用します。

  • project

    • クラスタを作成したGCPプロジェクトです。
    • Qmonus SDK Labの環境を作成する際、クラウドサービス設定にて利用します。

  • security_policy

    • 作成したcloud armorのsecurity policyです。
    • Qmonus SDK Labの環境を作成する際、クラウドサービス設定にて利用します。

  • service_account_gke_internal

    • 作成した1つ目のサービスアカウントです。
      各種QmonusのImageをPullする際に利用します。
    • Qmonus SDK Lab利用申請の際に記載してください。

  • service_account_qmonus_sdk_lab



# 8. 作成後の確認

以下のページから作成されたクラスタを確認します。
Google公式ページ > Google Kubernetes Engine に移動 (opens new window)


以上で本手順「テンプレートを使用してクラスタを準備する (GCP)」は完了となります。


AWS(Amazon EKS) 向け手順

ここでは、Qmonus SDK Labチームの用意したファイル、コマンドを使用し必要なAWSクラウド設定を行うまでを説明します。

前提条件



# 1. ファイルをダウンロードする

Qmonus SDK Labチームが作成した以下のファイルをダウンロードします。

zip を展開すると以下の2つのフォルダが含まれています。

  • environments/dev01_minimum/ — EKSクラスタや周辺AWSリソースを構築するTerraform
  • crd/dev01_minimum/ — EKSクラスタ上にCRDをインストールするTerraform


# 2. フォルダの作成、ファイルの再配置

PCに以下のようなツリー構造のフォルダを作成し、展開したファイルを下図のように配置してください。
※[product name]は任意のプロダクト名としてください（後続の手順で設定する product_name と合わせます）。

(ユーザディレクトリなど)
└── [product name]
    └── aws
        ├── environments
        │   └── dev01_minimum
        │       ├── variables.tf
        │       ├── project-setup.sh
        │       └── (その他 .tf ファイル)
        └── crd
            └── dev01_minimum
                ├── variables.tf
                └── (その他 .tf ファイル)
1
2
3
4
5
6
7
8
9
10
11
12


以降の手順で共通して使用する値

手順3〜7で編集する各ファイルには、共通して使用する値があります。先に決めておくと記入がスムーズです。

値 例 説明
プロダクト名 qmonus-myapp 各ファイルの PRODUCT_NAME / product_name。AWSリソース名のプレフィックス
環境名 dev01 ENVIRONMENT。Terraform State保存先S3バケット名のサフィックス
AWSアカウントID 123456789012 AWS_ACCOUNT_ID / account_id
リージョン ap-northeast-1 AWS_REGION。デプロイ先リージョン
AWS CLIプロファイル default AWS_PROFILE / profile。Terraform実行に使用


# 3. テンプレートへの入力 ( project-setup.sh )

environments/dev01_minimum/project-setup.sh を開き、以下の値を設定します。

#!/usr/bin/env bash
PRODUCT_NAME="qmonus-myapp"      # プロダクト名
ENVIRONMENT="dev01"              # 環境名
AWS_REGION="ap-northeast-1"      # デプロイ先リージョン
AWS_ACCOUNT_ID="123456789012"    # AWSアカウントID
AWS_PROFILE="default"            # Terraform実行に使うAWS CLIプロファイル
1
2
3
4
5
6
変数 例 必須 説明
PRODUCT_NAME qmonus-myapp 必須 作成されるAWSリソース名のプレフィックス。以降のファイルの product_name と一致させます
ENVIRONMENT dev01 必須 Terraform State保存先S3バケット名のサフィックス
AWS_ACCOUNT_ID 123456789012 必須 AWSアカウントID (opens new window)
AWS_REGION ap-northeast-1 任意 デプロイ先リージョン (opens new window)
AWS_PROFILE default 任意 Terraform実行に使うAWS CLIプロファイル名。以降のファイルの profile と一致させます


# 4. テンプレートへの入力 ( environments/dev01_minimum/meta.tf )

environments/dev01_minimum/meta.tf の backend "s3" ブロックを設定します。

  backend "s3" {
    bucket  = "tf-state-YOUR_PRODUCT_NAME-dev01-minimum"  # StateバケットS3名
    profile = "terraform-YOUR_PROFILE_NAME"               # AWS CLIプロファイル
  }
1
2
3
4
項目 設定値 説明
bucket tf-state-<PRODUCT_NAME>-<ENVIRONMENT>-minimum 手順3の project-setup.sh で作成されるState保存用S3バケット名と一致させます
profile 手順3の AWS_PROFILE と同じ値 Terraform実行に使うAWS CLIプロファイル名


# 5. テンプレートへの入力 ( environments/dev01_minimum/variables.tf )

environments/dev01_minimum/variables.tf の各 default 値を設定します。

variable "account_id" {
  default = "123456789012"       # AWSアカウントID
}
variable "product_name" {
  default = "qmonus-myapp"       # プロダクト名
}
variable "profile" {
  default = "terraform-myapp-dev" # AWS CLIプロファイル
}
variable "allowed_cidr_blocks" {
  default = [
    "203.0.113.10/32"           # アクセス元のグローバルIP（CIDR形式）
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
変数 例 説明
account_id 123456789012 手順3の AWS_ACCOUNT_ID と同じ値
product_name qmonus-myapp 手順3の PRODUCT_NAME と同じ値
profile terraform-myapp-dev 手順3の AWS_PROFILE と同じ値
allowed_cidr_blocks 203.0.113.10/32 アクセス元のグローバルIP（個人宅やVPNサーバー等）をCIDR形式で指定。ALBおよびセキュリティグループのインバウンドルールに使用（複数指定可）

`eks_cluster.public_access_cidrs` について

デフォルト値としてQmonus SDK Lab / QVSのNAT IPが設定されています。
EKS APIサーバーへのパブリックアクセスを許可するCIDRブロックです。追加で許可したいIPがある場合は書き換えてください。



# 6. テンプレートへの入力 ( crd/dev01_minimum/meta.tf )

crd/dev01_minimum/meta.tf の backend "s3" ブロックを設定します。

  backend "s3" {
    bucket  = "tf-state-kubernetes-YOUR_PRODUCT_NAME-dev01-minimum"  # CRD用StateバケットS3名
    profile = "terraform-YOUR_PROFILE_NAME"                          # AWS CLIプロファイル
  }
1
2
3
4
項目 設定値 説明
bucket tf-state-kubernetes-<PRODUCT_NAME>-<ENVIRONMENT>-minimum 手順3の project-setup.sh で作成されるCRD用State保存用S3バケット名と一致させます
profile 手順3の AWS_PROFILE と同じ値 Terraform実行に使うAWS CLIプロファイル名


# 7. テンプレートへの入力 ( crd/dev01_minimum/variables.tf )

crd/dev01_minimum/variables.tf の各 default 値を設定します。値は手順5と同じです。

variable "account_id" {
  default = "123456789012"       # AWSアカウントID
}
variable "product_name" {
  default = "qmonus-myapp"       # プロダクト名
}
variable "profile" {
  default = "terraform-myapp-dev" # AWS CLIプロファイル
}
1
2
3
4
5
6
7
8
9
変数 例 説明
account_id 123456789012 手順3の AWS_ACCOUNT_ID と同じ値
product_name qmonus-myapp 手順3の PRODUCT_NAME と同じ値
profile terraform-myapp-dev 手順3の AWS_PROFILE と同じ値


# 8. セットアップスクリプトの実行

以下のコマンドを実行し、Terraform State保存用S3バケットおよびTerraform実行用IAMユーザーを作成します。

# environments/dev01_minimum/ で実行
sh project-setup.sh
1
2


# 9. EKSクラスタの作成

以下のコマンドを実行し、EKSクラスタおよび周辺リソースの作成を開始します。

# environments/dev01_minimum/ で実行
terraform init
terraform apply
1
2
3

terraformのapply完了後はEKSクラスタを含む必要なリソースが作成されている状態です。
Outputsとして以下の情報が出力されますのでお控えください。

# apply完了後に出力される情報詳細 (environments)

  • account_id

    • デプロイ先のAWSアカウントIDです。

  • eks_cluster_name

    • 作成したEKSクラスタ名です。
    • 次手順 (crd) のapply、およびQmonus SDK Labの環境を作成する際に利用します。

  • eks_cluster_endpoint

    • 作成したEKSクラスタのエンドポイントURLです。
    • Qmonus SDK Labの環境を作成する際、クラウドサービス設定にて利用します。

  • vpc_id

    • 作成したVPCのIDです。


# 10. CRDのインストール

引き続き crd/dev01_minimum/ フォルダにて以下のコマンドを実行し、EKSクラスタ上にCRDをインストールします。

# crd/dev01_minimum/ で実行
terraform init
terraform apply
1
2
3


# 11. 作成後の確認

以下のページから作成されたEKSクラスタを確認します。
AWS公式ページ > Amazon EKS コンソールへ移動 (opens new window)



# 12. 証明書発行用CNAMEレコードの確認

本テンプレートでは、Qmonus所有ドメインのTLS証明書を発行するためのACM (AWS Certificate Manager) 証明書リクエストが自動で作成されます。
この証明書はドメイン所有者認証 (DNS検証) が必要となるため、ACMに表示されるCNAMEレコードをQmonusサポートへご申請いただく必要があります。
Qmonus側でご申請いただいたCNAMEレコードをDNSに登録することで、証明書が発行されます。
※申請方法は Labを導入するまでの流れ > 申請 をご参照ください。


12-1. AWS Certificate Manager コンソールを開く
→ AWS公式ページ > AWS Certificate Manager コンソールへ移動 (opens new window)

12-2. 本テンプレートで作成された証明書を選択する
ステータスが「保留中の検証 (Pending validation)」となっている証明書が対象です。

12-3. 「ドメイン」欄に表示される以下2つの値を控える
・CNAME 名 (CNAME name)
・CNAME 値 (CNAME value)


控えた「CNAME 名」「CNAME 値」は、証明書発行用CNAMEレコードの登録申請時に使用します。


以上で本手順「テンプレートを使用してクラスタを準備する (AWS)」は完了となります。



# 既存のKubernetesクラスタを使用する場合

以下の３つを作成してください。

  • Kubernetesクラスタ
    • 下記アドレス (Qmonus SDK Lab/Value Stream) からの通信を許可してください。
      • 35.200.13.149/32
      • 35.189.158.160/32
      • 34.146.44.32/32
      • 35.200.92.31/32
  • ユーザクラスタのNodeに関連付けられたサービスアカウント１ (SA1)1)
    • 利用申請時にサポートにご提示いただきます。
      ※Qmonus提供のterraformでクラスタ作った場合は「gke-internal@~~~」というSAとなります。確認方法
  • 「Kubernetes Engine 管理者」ロールのついたサービスアカウント２ (SA2)
    • サポートに提示いただく必要はございません。
      ※「ログ閲覧者」ロールを追加することでQmonus SDK Labからログをダウンロードすることができるようになります。

お控えいただくもの
・GKEのプロジェクトID
→  確認場所 (opens new window) より対象のIDをご確認ください。
 ・Kubernetesクラスタのエンドポイント
→  確認場所 (opens new window)よりクラスタを選択、詳細をご確認ください。
 ・GKEのサービスアカウント
→  作成方法 (opens new window)または確認方法より対象のSAをご確認ください。
・GKEのサービスアカウントキーファイル
→  作成方法 (opens new window)からサービスアカウントキーを新たに作成してください3)。

TIP

サービスアカウントの用途は以下の通りです。
・コンテナイメージ（弊社のプライベートレジストリ内）のPullを許可
・Qmonus SDK LabのCloudService登録　（要Kubernetes Engine 管理者ロール）

# 既存のKubernetesネームスペースを使用する場合

以下の２つを作成してください。
※KUJIRA基盤上にデプロイする場合などはこちらを選択します。

  • Kubernetesネームスペース（作成場所となるKubernetesクラスタもご用意ください。）
  • ネームスペースのkubeconfigファイル

お控えいただくもの
・kubeconfig（KUJIRA基盤利用の場合はKUJIRAチームよりkubeconfigが払い出されます）

KUJIRA環境について

NTT DOCOMO BUSINESSの提供しているKUJIRA(labprivate/labshared)環境を利用する際は以下を参照ください。
→ NTT DOCOMO BUSINESSの提供しているKUJIRA環境を利用する際の注意事項



【注意事項】開発環境間の通信制御について

Labの仕様としては、クラスタ内のPod同士の通信を抑止する等の設定は行なっておりません。
そのため、認証情報があれば同クラスタに構築された環境間での通信や操作が可能です。 通信制御が必要な場合はユーザ側でのクラスタ設定実施をお願いいたします。

















# 注釈

  1. ^サービスアカウントは、適切に権限管理をするためにも新規作成し、クラスタに設定することを推奨しております。（ComputeEngineが使うデフォルトのサービスアカウントは推奨しておりません。

  2. ^Terraformから払い出されるgke-internalというサービスアカウントは「Kubernetes Engine 管理者」ロールが付与されておりません。そのため、Qmonus SDK LabのCloudService登録にはご利用いただけません。

  3. ^サービスアカウントキーファイルは作成時に一度だけダウンロードすることができます。紛失してしまった場合は再度新しい鍵ファイルを作成してください。

← リポジトリ →