OASE Agent on Kubernetes - Online

目的

本書では、Exastro IT AutomationにおいてOASEを利用する際に、外部との連携に必要となる、Exastro OASE Agentを導入する手順について説明します。

特徴

OASEを利用するための絶対条件である、Exastro OASE Agentの高い可用性やサービスレベルを必要とされる際の、Exastro IT Automation の導入方法となります。
評価や一時的な利用など、簡単に利用を開始したい場合には、Docker Compose 版 OASE Agent の利用を推奨します。
Exastro OASE Agentの設定や運用については、エージェント概要 をご参照ください。

前提条件

  • Exastro IT Automationについて

    Exastro OASE Agentの運用には、Exastro OASE AgentとExastro IT Automationのバージョンが一致している必要があります。

  • クライアント要件

    動作確認が取れているクライアントアプリケーションのバージョンは下記のとおりです。
    表 33 クライアント要件

    アプリケーション

    バージョン

    Helm

    v3.9.x

    kubectl

    1.23

  • デプロイ環境

    動作確認が取れているコンテナ環境の最小要求リソースとバージョンは下記のとおりです。
    表 34 ハードウェア要件(最小構成)

    リソース種別

    要求リソース

    CPU

    2 Cores (3.0 GHz, x86_64)

    Memory

    4GB

    Storage (Container image size)

    10GB

    Kubernetes (Container image size)

    1.23 以上

  • 通信要件

    • OASE Agentから収集対象サーバにアクセスできる必要があります。

    • コンテナ環境からコンテナイメージの取得のために、Docker Hub に接続できる必要があります。

警告

Helm chart (Kubernetes) 版 で構築した環境にデプロイする場合、
OASE Agentに対応する最小要件を追加で容易する必要があります。

インストールの準備

Helm リポジトリの登録

Exastro OASE AgentはExastro システムと同一の Helm リポジトリ上に存在しています。

  • Exastro OASE Agent

リポジトリ

https://exastro-suite.github.io/exastro-helm/
リスト 124 コマンド
1# Exastro システムの Helm リポジトリを登録
2helm repo add exastro https://exastro-suite.github.io/exastro-helm/ --namespace exastro
3# リポジトリ情報の更新
4helm repo update

デフォルト設定値の取得

投入するパラメータを管理しやすくするために、下記のコマンドから共通基盤 values.yaml のデフォルト値を出力します。
リスト 125 コマンド
helm show values exastro/exastro-agent > exastro-agent.yaml
exastro-agent.yaml
  1# Default values for exastro-agent.
  2# This is a YAML-formatted file.
  3# Declare variables to be passed into your templates.
  4global:
  5  agentGlobalDefinition:
  6    name: agent-global
  7    enabled: true
  8    image:
  9      registry: "docker.io"
 10      organization: exastro
 11      package: exastro-it-automation
 12
 13ita-ag-oase:
 14  agents:
 15    - image:
 16        repository: ""
 17        # Overrides the image tag whose default is the chart appVersion.
 18        tag: ""
 19        pullPolicy: IfNotPresent
 20      extraEnv:
 21        TZ: Asia/Tokyo
 22        DEFAULT_LANGUAGE: ja
 23        LANGUAGE: "en"
 24        ITERATION: "500"
 25        EXECUTE_INTERVAL: "10"
 26        LOG_LEVEL: INFO
 27        AGENT_NAME: "oase-agent"
 28        EXASTRO_URL: "http://platform-auth:8000"
 29        EXASTRO_ORGANIZATION_ID: "org001"
 30        EXASTRO_WORKSPACE_ID: "ws01"
 31        # ROLES: "_ws_admin"
 32        EVENT_COLLECTION_SETTINGS_NAMES: "id0001"
 33      secret:
 34        EXASTRO_USERNAME: "admin"
 35        EXASTRO_PASSWORD: "sample-password"
 36        # USER_ID: "user01"
 37      resources: {}
 38        # requests:
 39        #   memory: "64Mi"
 40        #   cpu: "250m"
 41        # limits:
 42        #   memory: "64Mi"
 43        #   cpu: "250m"
 44
 45  imagePullSecrets: []
 46  nameOverride: ""
 47  fullnameOverride: ""
 48
 49  initContainerImage:
 50    repository: "registry.access.redhat.com/ubi8/ubi-init"
 51    pullPolicy: IfNotPresent
 52    # Overrides the image tag whose default is the chart appVersion.
 53    tag: ""
 54
 55  serviceAccount:
 56    # Specifies whether a service account should be created
 57    create: false
 58    # Annotations to add to the service account
 59    annotations: {}
 60    # The name of the service account to use.
 61    # If not set and create is true, a name is generated using the fullname template
 62    name: ""
 63
 64  persistence:
 65    enabled: true
 66    reinstall: false
 67    accessMode: ReadWriteMany
 68    size: 10Gi
 69    volumeType: hostPath # e.g.) hostPath or AKS
 70    storageClass: "-" # e.g.) azurefile or - (None)
 71    # matchLabels:
 72    #   release: "stable"
 73    # matchExpressions:
 74    #   - {key: environment, operator: In, values: [dev]}
 75    mountPath:
 76      storage: /storage
 77      homeDir: /home/app_user
 78      pid:
 79        path: /var/run_app_user/httpd/pid
 80        subPath: httpd-pid
 81      socket:
 82        path: /var/run_app_user/httpd/socket
 83        subPath: httpd-socket
 84      tmp: /tmp
 85
 86  podAnnotations: {}
 87
 88  podSecurityContext: {}
 89    # fsGroup: 2000
 90
 91  securityContext:
 92    allowPrivilegeEscalation: false
 93    readOnlyRootFilesystem: true
 94    runAsUser: 1000
 95    runAsGroup: 1000
 96    runAsNonRoot: true
 97
 98  service: {}
 99
100  ingress:
101    enabled: false
102    className: ""
103    annotations: {}
104      # kubernetes.io/ingress.class: nginx
105      # kubernetes.io/tls-acme: "true"
106    hosts:
107      - host: chart-example.local
108        paths:
109          - path: /
110            pathType: ImplementationSpecific
111    tls: []
112  #  - secretName: chart-example-tls
113    #    hosts:
114    #      - chart-example.local
115
116  nodeSelector: {}
117
118  tolerations: []
119
120  affinity: {}
以降の手順では、この exastro-agent.yaml に対してインストールに必要なパラメータを設定してきいます。

OASE Agentの設定

OASE Agentを立ち上げる際の代表的な設定方法について紹介します。
下記の例では、永続ボリュームはhostPathで設定してます。

  • シンプル構成

  • 複数エージェント（同一Pod）

  • 複数エージェント（別Pod）

パラメータ

利用可能なパラメータについては下記を参照してください。
表 35 ita-ag-oase における Values 一覧

パラメータ

説明

変更

デフォルト値・選択可能な設定値

ita-ag-oase.agents.image.repository

コンテナイメージのリポジトリ名

不可

""

ita-ag-oase.agents.image.tag

コンテナイメージのタグ

不可

""

ita-ag-oase.agents.image.pullPolicy

イメージプルポリシー

可
IfNotPresent (デフォルト): コンテナイメージが存在しない場合のみプル
Always: 毎回必ずプル
None: プルしない

ita-ag-oase.agents.extraEnv.TZ

OASE エージェント システムで使用する規定の言語

可

Asia/Tokyo

ita-ag-oase.agents.extraEnv.DEFAULT_LANGUAGE

OASE エージェント システムで使用する言語

可

ja

ita-ag-oase.agents.extraEnv.LANGUAGE

OASE エージェント のバージョン

可

en

ita-ag-oase.agents.extraEnv.ITERATION

OASE エージェント が設定を初期化するまでの、処理の繰り返し数（下限値: 10）

可

500

ita-ag-oase.agents.extraEnv.EXECUTE_INTERVAL

ita-ag-oaseがイベント取得対象に対してイベント取得の間隔（秒）（下限値: 3）

可

10

ita-ag-oase.agents.extraEnv.LOG_LEVEL

OASE エージェント のログレベル

可

INFO

ita-ag-oase.eagents.xtraEnv.AGENT_NAME

起動する OASEエージェントの名前

可

oase-agent

ita-ag-oase.agents.extraEnv.EXASTRO_URL

Exastro IT Automation の Service URL

可

http://platform-auth:8000

ita-ag-oase.agents.extraEnv.EXASTRO_ORGANIZATION_ID

Exastro IT Automation で作成した OrganizationID

必須

org001

ita-ag-oase.agents.extraEnv.EXASTRO_WORKSPACE_ID

Exastro IT Automation で作成した WorkspaceID

必須

ws01

ita-ag-oase.agents.extraEnv.EVENT_COLLECTION_SETTINGS_NAMES
Exastro IT Automation のOASE管理 エージェント で作成した イベント収集設定名
カンマ区切りで複数指定可能

必須

id0001

ita-ag-oase.agents.secret.EXASTRO_USERNAME

Exastro IT Automation で作成した ユーザー名

可

admin

ita-ag-oase.agents.secret.EXASTRO_PASSWORD

Exastro IT Automation で作成した パスワード

可

sample-password

ita-ag-oase.agents.resources.requests.memory

メモリ要求

可

"64Mi"

ita-ag-oase.agents.resources.requests.cpu

CPU要求

可

"250m"

ita-ag-oase.agents.resources.limits.memory

メモリ上限

可

"64Mi"

ita-ag-oase.agents.resources.limits.cpu

CPU上限

可

"250m"

ita-ag-oase.nameOverride
Exastro OASE Agent の定義名
※同一クラスタ内に複数エージェントを構築する際は必須

可

""

ita-ag-oase.persistence.enabled

OASE エージェントコンテナのデプロイの有無

可
true (デフォルト): OASE エージェントコンテナをデプロイします。
false : OASE エージェントコンテナをデプロイしません。

ita-ag-oase.persistence.reinstall

再インストール時にデータ領域の初期化の要否

不可
true : データを初期化(削除)する
false (デフォルト): データを初期化(削除)しない

ita-ag-oase.persistence.accessMode

永続ボリュームのアクセスモードの指定。

不可

"ReadWriteMany"

ita-ag-oase.persistence.size

永続ボリュームのディスク容量

可 (データ永続化時)

"10Gi"

ita-ag-oase.persistence.volumeType

永続ボリュームのボリュームタイプ

可 (現在無効)
hostPath (デフォルト): Kubernetes クラスタのノード上にデータを保存(非推奨)
AKS: AKS のストレージクラスを利用

ita-ag-oase.persistence.storageClass

永続ボリュームにストレージクラスを利用する場合のクラスを指定

可 (データ永続化時)
- (デフォルト): ストレージクラスを指定しない。
ストレージクラス名: クラウドプロバイダなどから提供されるストレージクラス名を指定。

exastro-platform.mariadb.persistence.matchLabels.name

利用する永続ボリューム名を指定

可(データ永続化時)

""

OASE Agentのパラメータ設定例

Agentの設定例を下記に記載します。

  • 特徴

1Podに1コンテナのシンプルな構成

  • 設定例

  1. OASE Agentの設定

    OASE Agentの設定します。
    リスト 126 exastro-agent.yaml
    13ita-ag-oase:
14  agents:
15    - image:
16        repository: ""
17        # Overrides the image tag whose default is the chart appVersion.
18        tag: "alpha.4ccca4.20240124-110529"
19        pullPolicy: IfNotPresent
20      extraEnv:
21        TZ: Asia/Tokyo
22        DEFAULT_LANGUAGE: ja
23        LANGUAGE: "en"
24        ITERATION: "500"
25        EXECUTE_INTERVAL: "10"
26        LOG_LEVEL: INFO
27        AGENT_NAME: "oase-agent"
28-       EXASTRO_URL: "http://platform-auth:8000"
29+       EXASTRO_URL: "http://your-exastro-url"                                   # Exastro IT Automation の Service URL
30-       EXASTRO_ORGANIZATION_ID: "org001"
31+       EXASTRO_ORGANIZATION_ID: "your-organization-id"                          # Exastro IT Automation で作成した OrganizationID
32-       EXASTRO_WORKSPACE_ID: "ws01"
33+       EXASTRO_WORKSPACE_ID: "your-workspace-id"                                # Exastro IT Automation で作成した WorkspaceID
34        # ROLES: "_ws_admin"
35-       EVENT_COLLECTION_SETTINGS_NAMES: "id0001"
36+       EVENT_COLLECTION_SETTINGS_NAMES: "your-event-collection-settigs-names"   # OASE管理 エージェント で作成した イベント収集設定名
37      secret:
38-       EXASTRO_USERNAME: "admin"
39-       EXASTRO_PASSWORD: "sample-password"
40+       EXASTRO_USERNAME: "your-ita-user-name"                                   # Exastro IT Automation で作成した ユーザー名
41+       EXASTRO_PASSWORD: "your-ita-user-password"                               # Exastro IT Automation で作成した パスワード

永続ボリュームの設定

データベースのデータ永続化 (クラスタ内コンテナがある場合)、および、ファイルの永続化のために、永続ボリュームを設定する必要があります。
永続ボリュームの詳細については、 永続ボリューム - Kubernetes を参照してください。

  • 特徴

Kubernetes のノード上のストレージ領域を利用するため、別途ストレージを調達する必要はありませんが、この方法は非推奨のため検証や開発時のみの利用

危険

データの永続化自体は可能ですが、コンピュートノードの増減や変更によりデータが消えてしまう可能性があるため本番環境では使用しないでください。
また、Azure で構築した AKS クラスタは、クラスタを停止すると AKS クラスターの Node が解放されるため、保存していた情報は消えてしまいます。そのため、Node が停止しないように注意が必要となります。

  • 利用例

hostPath を使用した例を記載します。
リスト 134 pv-ita-ag-oase.yaml
 1# pv-ita-ag-oase.yaml
 2apiVersion: v1
 3kind: PersistentVolume
 4metadata:
 5  name: pv-ita-ag-oase
 6spec:
 7  claimRef:
 8    name: pvc-ita-ag-oase
 9    namespace: exastro
10  capacity:
11    storage: 10Gi
12  accessModes:
13    - ReadWriteMany
14  persistentVolumeReclaimPolicy: Retain
15  hostPath:
16    path: /var/data/exastro-suite/exastro-agent/ita-ag-oase
17    type: DirectoryOrCreate

インストール

永続ボリュームの作成

永続ボリュームの設定 で作成したマニフェストファイルを適用し、ボリュームを作成します。
# pv-ita-ag-oase.yaml
kubectl apply -f pv-ita-ag-oase.yaml

# 複数エージェント（別Pod）の場合は下記を実施
# pv-ita-ag-oase-1.yaml
kubectl apply -f pv-ita-ag-oase-1.yaml

# pv-ita-ag-oase-2.yaml
kubectl apply -f pv-ita-ag-oase-2.yaml

# 確認
kubectl get pv

NAME              CAPACITY   ACCESS MODES   RECLAIM POLICY    STATUS      CLAIM     STORAGECLASS   REASON   AGE
pv-ita-ag-oase     10Gi       RWX            Retain           Available                                     6s

NAME              CAPACITY   ACCESS MODES   RECLAIM POLICY    STATUS      CLAIM     STORAGECLASS   REASON   AGE
pv-ita-ag-oase-1   10Gi       RWX            Retain           Available                                     5s
pv-ita-ag-oase-2   10Gi       RWX            Retain           Available                                     6s

インストール

Helm バージョンとアプリケーションのバージョンについては exastro-helmのサイト をご確認ください。

  1. Helm コマンドを使い Kubernetes 環境にインストールを行います。

    リスト 137 コマンド
    helm install exastro-agent exastro/exastro-agent \
  --namespace exastro --create-namespace \
  --values exastro-agent.yaml
    リスト 138 出力結果
    NAME: exastro-agent
LAST DEPLOYED: Wed Feb 14 14:36:27 2024
NAMESPACE: exastro
STATUS: deployed
REVISION: 1
TEST SUITE: None

  2. インストール状況確認

    リスト 139 コマンド
    # Pod の一覧を取得
kubectl get po --namespace exastro

| 正常に起動している場合は、“Running” となります。
| ※正常に起動するまで数分かかる場合があります。
    リスト 140 出力結果
     NAME                             READY   STATUS    RESTARTS   AGE
 ita-ag-oase-66cb7669c6-m2q8c     1/1     Running   0          16m

アップグレード

OASE Agentのアップグレード方法について紹介します。

アップグレードの準備

警告

アップグレード実施前に データバックアップ・リストア の手順に従い、バックアップを取得しておくことを推奨します。
更新前のバージョンを確認します。
リスト 147 コマンド
1# リポジトリ情報の確認
2helm search repo exastro
リスト 148 実行結果
1helm search repo exastro
2NAME                            CHART VERSION   APP VERSION     DESCRIPTION
3exastro/exastro                         1.3.24          2.3.0           A Helm chart for Exastro. Exastro is an Open So...
4exastro/exastro-agent                   1.0.3           2.3.0           A Helm chart for Exastro IT Automation. Exastro...
5exastro/exastro-it-automation           1.4.22          2.3.0           A Helm chart for Exastro IT Automation. Exastro...
6exastro/exastro-platform                1.7.14          1.7.0           A Helm chart for Exastro Platform. Exastro Plat...
Helm リポジトリを更新します。
リスト 149 コマンド
1# リポジトリ情報の更新
2helm repo update
更新後のバージョンを確認します。
リスト 150 コマンド
1# リポジトリ情報の確認
2helm search repo exastro
リスト 151 実行結果
1helm search repo exastro
2NAME                            CHART VERSION   APP VERSION     DESCRIPTION
3exastro/exastro                    1.4.3           2.4.0           A Helm chart for Exastro. Exastro is an Open So...
4exastro/exastro-agent              2.4.0           2.4.0           A Helm chart for Exastro IT Automation. Exastro...
5exastro/exastro-it-automation      2.4.1           2.4.0           A Helm chart for Exastro IT Automation. Exastro...
6exastro/exastro-platform           1.8.1           1.8.0           A Helm chart for Exastro Platform. Exastro Plat...

アップグレード

サービス停止

  1. Pod 起動数の確認

    作業前の Pod 起動数の確認をし、状態を記録します。
    リスト 152 コマンド
    RS_AG=`kubectl get deploy ita-ag-oase -o jsonpath='{@.spec.replicas}{"\n"}' --namespace exastro`

  2. バックヤード処理の停止

    Pod 起動数を 0 に変更し、データベースの更新を停止します。
    リスト 153 コマンド
    kubectl scale deployment ita-ag-oase --namespace exastro --replicas=0

  3. Pod 起動数の確認

    上記で停止した対象の Pod 数が 0 になっていることを確認
    リスト 154 コマンド
    kubectl get deployment --namespace exastro
    リスト 155 実行結果
    NAME                                     READY   UP-TO-DATE   AVAILABLE   AGE
ita-ag-oase                              0/1     1            1           29m

アップグレード実施

アップグレードを実施します。
リスト 156 コマンド
helm upgrade exastro-agent exastro/exastro-agent \
  --namespace exastro \
  --values exastro-agent.yaml
リスト 157 出力結果
Release "exastro-agent" has been upgraded. Happy Helming!
NAME: exastro-agent
LAST DEPLOYED: Mon Apr 22 14:42:59 2024
NAMESPACE: exastro
STATUS: deployed
REVISION: 2
TEST SUITE: None

サービス再開

  1. サービス再開

    サービス停止時に取得した各 Deployment の Pod 起動数を元に戻します。
    リスト 158 コマンド
    kubectl scale deployment ita-ag-oase --namespace exastro --replicas=${RS_AG}

  2. Pod 起動数の確認

    上記で起動した対象の Pod 数が元に戻りすべて READY になっていることを確認
    リスト 159 コマンド
    kubectl get deployment --namespace exastro
    リスト 160 実行結果
    NAME                                     READY   UP-TO-DATE   AVAILABLE   AGE
ita-ag-oase                              1/1     1            1           29m

アップグレード状況確認

コマンドラインから以下のコマンドを入力して、アップグレードが完了していることを確認します。
リスト 161 コマンド
# Pod の一覧を取得
kubectl get po --namespace exastro
正常に起動している場合は、Running” となります。
※正常に起動するまで数分かかる場合があります。
リスト 162 出力結果
NAME                                                      READY   STATUS      RESTARTS   AGE
ita-ag-oase-7ff9488b55-rrn58                              1/1     Running     0             81s

アンインストール

OASE Agentのアンインストール方法について紹介します。

アンインストールの準備

警告

アンインストール実施前に データバックアップ・リストア の手順に従い、バックアップを取得しておくことを推奨します。

アンインストール

アンインストール実施

アンインストールを実施します。
リスト 163 コマンド
helm uninstall exastro-agent --namespace exastro
リスト 164 出力結果
release "exastro-agent" uninstalled

永続ボリュームを削除

Persitent Volume（PV） を Kubernetes 上に hostPath で作成した場合の方法を記載します。
マネージドデータベースを含む外部データベースを利用している場合は、環境にあったデータ削除方法を実施してください。
エージェント用

警告

エージェント用のPVが複数存在する場合はそれらすべての削除を実施してください。
リスト 165 コマンド
kubectl delete pv pv-ita-ag-oase
リスト 166 実行結果
persistentvolume "pv-ita-ag-oase" deleted

永続データを削除

Kubernetes のコントロールノードにログインし、データを削除します。
エージェント用
下記コマンドは、Persistent Volume 作成時の hostPath に /var/data/exastro-suite/exastro-agent/ita-ag-oase を指定した場合の例です。
リスト 167 コマンド
# 永続データがあるコントロールノードにログイン
ssh user@contol.node.example

# 永続データの削除
sudo rm -rf /var/data/exastro-suite/exastro-agent/ita-ag-oase