Kubernetesモードインストール

1. サポート環境​

2. 重要な制約条件​

exemone-apiとexemone-receiver Podは、必ず同一のNodeで実行される必要があります。​

これを実現するため、Worker Nodeにラベルを設定し、DeploymentのnodeSelectorで制御します。

ラベル設定:

kubectl label nodes worker-node1 workload=exemone-k8s

Deployment nodeSelectorの設定(ファイル: {SET_NAME}/deployment.yaml):

...
spec:
  selector:
    matchLabels:
      app: exemone-receiver
  replicas: 1
  template:
...
    spec:
      nodeSelector:
        workload: exemone-k8s  # または kubernetes.io/hostname: worker-node1
...

3. Kubernetesモード新規インストール手順(ステップ別)​

[Phase 1] 事前設定​

手順1. Storage Classの作成​

exemONEサービスのデータを保存するStorage Classが事前に作成されている必要があります。

StorageClassマニフェスト例:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: local-storage-exemone-k8s
provisioner: rancher.io/local-path
volumeBindingMode: WaitForFirstConsumer
reclaimPolicy: Delete

kubectl apply -f storageclass.yaml

手順2. Namespaceの作成​

exemONEサービスを実行するNamespaceを作成します。

kubectl create namespace exemone-k8s

手順3. Worker Nodeラベルの設定(制約条件の適用)​

apiとreceiverが同一ノードで実行されるようにラベルを設定します。

kubectl label nodes worker-node1 workload=exemone-k8s

[Phase 2] パッケージの解凍​

手順1. パッケージファイルの解凍​

tar xvzf exemone-kubernetes-pkg-v3.0.1.0.tar.gz

手順2. installerフォルダへ移動後、内部パッケージを解凍​

cd exemone-kubernetes/installer
tar xvzf exemone-kubernetes.tar.gz

手順3. exemone-kubernetesフォルダへ移動​

cd exemone-kubernetes

[Phase 3] イメージのロード​

exemONEサービスを使用するすべてのNodeにイメージをロードする必要があります。

• イメージフォルダの位置: exemone-kubernetes/image/

Docker使用時:​

docker load -i <이미지>.tar.gz
# 例) docker load -i bitnami-kafka-3.3.2-debian-11-r5.tar.gz

# イメージロード検証
docker images | grep exemone

containerd使用時:​

namespaceについては、k8s.io が一般的ですが、環境によって異なる場合があります。

ctr -n k8s.io images import <이미지>.tar.gz
# 例) ctr -n k8s.io images import bitnami-kafka-3.3.2-debian-11-r5.tar.gz

# イメージロード検証
ctr -n k8s.io images ls | grep exemone

containerdで invalid tar header エラーが発生した場合:​

gunzip -k <이미지>.tar.gz    # gzip解凍
ctr -n k8s.io images import <이미지>.tar

# 例
gunzip -k bitnami-kafka-3.3.2-debian-11-r5.tar.gz
ctr -n k8s.io images import bitnami-kafka-3.3.2-debian-11-r5.tar

[Phase 4] 収集モジュールのインストール​

スクリプト実行位置: exemone-kubernetes/installer/exemone-kubernetes

手順1. generate.shの実行(yamlファイルの生成)​

generate.sh は、templatesフォルダ内のyamlファイルを使用して、exemONE収集モジュール生成用のyamlファイルを新規作成します。

sh generate.sh

実行時に入力する設定オプション:

Please enter set name: exemone
Please enter namespace: exemone-k8s
Please enter cluster domain: cluster.local
Please enter storage class name: local-storage-exemone-k8s

create yaml files
Directory exemone created
Files copied
replace variables in yaml files
done!

generate.sh 実行後、SET_NAMEで指定したフォルダ内に次のようなyamlファイルが生成されます: deployment.yaml、statefulset.yaml、pvc.yaml、service.yaml、configmap.yaml など

手順2. apply.shの実行(インストール)​

SET_NAMEフォルダにあるyamlファイルをKubernetesクラスターにapplyします。

sh apply.sh

Please enter set name: exemone

persistentvolumeclaim/exemone-db-agent-configs created
persistentvolumeclaim/exemone-db-agent-logs created
persistentvolumeclaim/exemone-db-agent-queries created
persistentvolumeclaim/exemone-cloud-agent-configs created
persistentvolumeclaim/exemone-cloud-agent-logs created
persistentvolumeclaim/exemone-cloud-agent-queries created
persistentvolumeclaim/exemone-receiver-logs created
persistentvolumeclaim/exemone-core-logs created
persistentvolumeclaim/exemone-core-db created
persistentvolumeclaim/exemone-alerter-logs created
persistentvolumeclaim/exemone-ingester-logs created

[Phase 5] インストールの確認​

手順1. PodおよびPVCのデプロイ確認​

kubectl get pods -n exemone-k8s
kubectl get pvc -n exemone-k8s

想定される結果:

[root@localhost ~]# kubectl get pods -n exemone-k8s
NAME                                READY   STATUS        RESTARTS   AGE
exem-container-agent-2hktr          1/1     Running       0          119m
exem-container-agent-72948          1/1     Running       0          119m
...

[root@localhost ~]# kubectl get pvc -n exemone-k8s
NAME                          STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS                AGE
exemone-alerter-logs          Bound    pvc-92108ca2-test-test-test-6ec352b7abb8   512Mi      RWO            local-storage-exemone-k8s   4h1m
exemone-api-class             Bound    pvc-c54d63b2-test-test-test-e4959366a59a   512Mi      RWO            
...

手順2. exemone-apiとexemone-receiverの同一ノードデプロイ検証​

kubectl get pods -n exemone-k8s -o wide | grep -E 'exemone-api|exemone-receiver'

想定される結果(同一Nodeの確認):

exemone-api-6d66444566-trzdp        1/1     Running       0          4h2m   10.20.30.40    worker-node1            <none>           <none>
exemone-receiver-95d99f5bb-g9wfz    1/1     Running       0          4h2m   10.20.30.41    worker-node1            <none>           <none>

2つのPodが同一のworker-node1で実行されていれば正常です。

4. マニフェスト(YAML)設定の詳細​

4-1. 生成される主要YAMLファイル​

generate.sh 実行時、templatesフォルダのyamlファイルを基に、入力した変数値が置換されて {SET_NAME} フォルダにyamlファイルが生成されます。

置換される変数一覧:

4-2. StorageClassマニフェスト例​

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: local-storage-exemone-k8s
provisioner: rancher.io/local-path
volumeBindingMode: WaitForFirstConsumer
reclaimPolicy: Delete

4-3. StatefulSetマニフェスト例(PostgreSQL)​

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: exemone-postgresql
  namespace: ${namespace}
  labels:
    io.exem: "true"
    io.exem.prod: exemone
    io.exem.one.type: middleware
    io.exem.one.app: postgresql
spec:
  selector:
    matchLabels:
      app: exemone-postgresql
  serviceName: "exemone-postgresql"
  replicas: 1
  template:
    metadata:
      labels:
        app: exemone-postgresql
    spec:
      volumes:
        - name: exemone-postgresql-initdbd
          configMap:
            name: exemone-postgresql-initdbd
            defaultMode: 420
        - name: exemone-postgresql-data
          persistentVolumeClaim:
            claimName: exemone-postgresql-data
      containers:
        - name: exemone-postgresql
          image: maxgauge/exemone-postgres:${postgresqlVersion}
          ports:
            - name: postgres
              containerPort: 5432
              protocol: TCP
          env:
            - name: PGDATA
              value: /var/lib/postgresql/data/pgdata
            - name: POSTGRES_USER
              value: postgres
            - name: POSTGRES_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: exemone-postgresql-password
                  key: password
          volumeMounts:
            - name: exemone-postgresql-initdbd
              mountPath: /docker-entrypoint-initdb.d
            - name: exemone-postgresql-data
              mountPath: /var/lib/postgresql/data/pgdata
          resources:
            requests:
              cpu: "1"
              memory: "1Gi"
            limits:
              cpu: "4"
              memory: "10Gi"
      imagePullSecrets:
        - name: regcred

4-4. Deployment nodeSelectorの設定(api/receiver同一ノード配置)​

spec:
  selector:
    matchLabels:
      app: exemone-receiver
  replicas: 1
  template:
    spec:
      nodeSelector:
        workload: exemone-k8s  # または kubernetes.io/hostname: worker-node1

4-5. .envファイル(モジュールバージョン管理)​

ファイルの位置: exemone-kubernetes/installer/exemone-kubernetes/.env

.env ファイルで各モジュールのイメージバージョンを管理し、モジュールパッチ時はこのファイルのバージョンを変更した後 apply.sh を再実行します。

5. bashスクリプトを実行できない環境​

generate.sh / apply.sh を実行できない場合、templates/ フォルダ配下のyamlファイルで上記の変数文字列を手動で置換し、各オブジェクトを kubectl apply -f で直接適用することができます。

6. 収集モジュールの削除​

スクリプト実行位置: exemone-kubernetes/installer/exemone-kubernetes

sh delete.sh

• apply.sh で適用したすべてのexemONEサービスモジュールおよびデータが削除されます。
• SET_NAMEで作成したフォルダ内のYAMLファイルも併せて削除されます。

データ(PVC)の保持が必要な場合​

delete.sh ファイルで以下の行をコメントアウトする必要があります:

# kubectl delete -f ./$SET_NAME/pvc.yaml

7. PostgreSQL 13→17 アップデート(任意)​

exemONEのPostgreSQLを13から17へアップデートする場合、以下の手順に従います。

注意事項:​

• delete.sh 実行時に既存データが削除されるため、推奨しません
• Pod再作成時は既存のPVCと同一のNodeで実行される必要があります
• 収集モジュールのパッチと併せて進める場合、収集モジュールのパッチ後にPostgreSQLのアップデートを進めます
• 必ず最新のパッケージファイルで実施する必要があります

アップデート手順の要約:​

1. exemone-postgresqlのPod、StatefulSet名を確認
2. exemone-apiのPod、Deployment名を確認
3. exemone-api Podの停止(replicas 0):

kubectl -n <namespace> scale deploy <deploy 이름> --replicas 0

4. PostgreSQLデータのバックアップ:

kubectl -n <namespace> exec <postgres 파드> -- pg_dumpall -U postgres > pg13_dump.sql

5. PGの既存PVCを保持(削除しない)
6. exemone-postgresql StatefulSetの削除:

kubectl -n <namespace> delete statefulset <statefulset 이름>

7. PVC名を変更して追加(exemone-postgresql-data-17)
8. StatefulSetの修正(volume、volumeMountsの名前を変更)
9. generate.sh → PVC作成 → StatefulSet作成
10. データの復元:

kubectl cp ./pg13_dump.sql <namespace>/<postgres 파드>:/tmp/pg13_dump.sql
kubectl -n <namespace> exec -it <postgres 파드> -- psql -U postgres -f /tmp/pg13_dump.sql

11. exemone-apiの再起動:

kubectl -n <namespace> scale deploy exemone-api --replicas 1

詳細ガイド: Kubernetes PostgreSQL 13→17アップデートガイド

8. インストール後の正常動作確認リスト​

8-1. Podの状態確認​

kubectl get pods -n exemone-k8s

• すべてのPodがRunning状態か確認
• RESTARTSの回数が増加し続けていないか確認

8-2. api/receiverの同一ノード確認​

kubectl get pods -n exemone-k8s -o wide | grep -E 'exemone-api|exemone-receiver'

8-3. 異常Podのログ確認​

PodがCrashLoopBackOffなど異常状態の場合:

kubectl logs -n exemone-k8s <Pod 이름>

8-4. Web画面接続確認​

• ブラウザで https://[Gateway 서비스 IP]:8443 または http://[Gateway 서비스 IP]:8080 へ接続
• ログインが正常に行えるか確認
• ログイン失敗時は exemone-api Podのログ確認が必要

8-5. エージェント状態確認​

• HOST基本ビュー: Active / Inactive 状態を確認

• Database基本ビュー: Active / No Signal 状態を確認

• Kubernetes Podビュー: Running 状態を確認

• WAS基本ビュー: Active 状態を確認

inactiveまたはnosignalの場合、収集サーバー ↔ ターゲットサーバー間のネットワークおよびポート(9009/9010)のファイアウォール確認が必要です。

9. Helm Chartについて​

参考ドキュメントで確認した内容によると、exemONE KubernetesインストールはHelm Chart方式ではなく、独自のスクリプトベース(generate.sh + apply.sh)でYAMLマニフェストを生成・デプロイする方式を使用しています。generate.sh がtemplatesフォルダのYAMLファイルに変数を置換してデプロイ用YAMLを生成する役割を担うため、Helmのテンプレートレンダリングと類似した機能を果たします。

10. 注意事項​

1. 制約条件は必須: exemone-apiとexemone-receiver Podは、必ず同一Nodeにデプロイする必要があります。nodeSelectorまたは kubernetes.io/hostname ラベルで制御してください。
2. すべてのNodeにイメージをロード: イメージはサービスを使用するすべてのWorker Nodeにロードする必要があります。
3. Storage Classの事前作成: generate.sh 実行前に、Storage Classが必ず存在している必要があります。
4. Namespaceの事前作成: apply.sh 実行前に、Namespaceが必ず存在している必要があります。
5. パッケージファイルの準備: インストールファイル(exemone-kubernetes-pkg-{version}.tar.gz)は品質技術チームに問い合わせて準備します。
6. delete.sh使用時の注意: PVCデータを保持したい場合は、必ず kubectl delete -f ./$SET_NAME/pvc.yaml の行をコメントアウトしてから実行してください。
7. PostgreSQLアップデートの順序: 収集モジュールのパッチと併せて進める場合、収集モジュールのパッチを先に進めてからPostgreSQLのアップデートを進める必要があります。
8. containerd環境: containerd使用時はイメージimportに ctr -n k8s.io images import コマンドを使用しますが、invalid tar header エラーが発生した場合は gunzip で解凍した後 .tar ファイルとしてimportしてください。

参考ドキュメント:

• Kubernetes新規インストールガイド
• Kubernetesモジュールパッチガイド
• Kubernetesパッケージパッチガイド
• Kubernetes PostgreSQL 13→17アップデートガイド
• 収集サーバーOS仕様
• モジュール別使用Port
• 収集モジュールの説明
• exemONE正常動作確認リスト