OASE Agent on Kubernetes - Online

目的

本書では、Exastro IT AutomationにおいてOASEを利用する際に、外部との連携に必要となる、Exastro OASE Agentを導入する手順について説明します。
Exastro OASE Agentの設定や運用については、エージェント概要 をご参照ください。

前提条件

  • Exastro IT Automationについて

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

  • クライアント要件

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

    アプリケーション

    バージョン

    Helm

    v3.9.x

    kubectl

    1.23

  • デプロイ環境

    デプロイ環境のシステム要件については 構成・構築ガイド を参照してください。

  • 通信要件

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

推奨事項

専用ユーザーの払い出し

OASE Agent の利用には、サービスアカウントユーザー管理機能 で作成したサービスアカウントユーザーを使用することを推奨します。

インストールの準備

Helm リポジトリの登録

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

  • Exastro OASE Agent

リポジトリ

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

デフォルト設定値の取得

投入するパラメータを管理しやすくするために、下記のコマンドから共通基盤 values.yaml のデフォルト値を出力します。
リスト 132 コマンド
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_REFRESH_TOKEN: "exastro_refresh_token"
 35        # EXASTRO_USERNAME: "admin"
 36        # EXASTRO_PASSWORD: "sample-password"
 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）

パラメータ

利用可能なパラメータについては下記を参照してください。
表 29 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 エージェント が設定を初期化するまでの、処理の繰り返し数（上限値: 120、下限値: 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_REFRESH_TOKEN
サービスアカウントユーザー管理機能 で取得したリフレッシュトークン

可

無し

ita-ag-oase.agents.secret.EXASTRO_USERNAME
Exastro IT Automation で作成した ユーザー名
※ユーザーのロールが、OASE - イベント - イベント履歴メニューをメンテナンス可能である必要があります。
※EXASTRO_REFRESH_TOKENを使わない場合（非推奨）

可

admin

ita-ag-oase.agents.secret.EXASTRO_PASSWORD
Exastro IT Automation で作成した パスワード
※EXASTRO_REFRESH_TOKENを使わない場合（非推奨）

可

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の設定します。
    リスト 133 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_REFRESH_TOKEN: "exastro_refresh_token"
39+       EXASTRO_REFRESH_TOKEN: "your_exastro_refresh_token"                      # サービスアカウントユーザー管理機能から取得したリフレッシュトークン
40        # EXASTRO_USERNAME: "admin"
41        # EXASTRO_PASSWORD: "sample-password"
42+       # EXASTRO_USERNAME: "your-ita-user-name"                # Exastro IT Automation で作成した ユーザー名（こちらを使用する場合はアンコメントしてください）
43+       # EXASTRO_PASSWORD: "your-ita-user-password"            # Exastro IT Automation で作成した パスワード（こちらを使用する場合はアンコメントしてください）

永続ボリュームの設定

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

  • 特徴

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

危険

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

  • 利用例

hostPath を使用した例を記載します。
リスト 141 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 環境にインストールを行います。
リスト 144 コマンド
helm install exastro-agent exastro/exastro-agent \
  --namespace exastro --create-namespace \
  --values exastro-agent.yaml
リスト 145 出力結果
NAME: exastro-agent
LAST DEPLOYED: Wed Feb 14 14:36:27 2024
NAMESPACE: exastro
STATUS: deployed
REVISION: 1
TEST SUITE: None
2. インストール状況確認
リスト 146 コマンド
# Pod の一覧を取得
kubectl get po --namespace exastro

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

アップグレード

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

アップグレードの準備

警告

アップグレード実施前に データバックアップ・リストア の手順に従い、バックアップを取得しておくことを推奨します。
バックアップ対象は、ファイル（name: ITA_STORAGEPATH）に含まれます。
更新前のバージョンを確認します。
リスト 154 コマンド
1# リポジトリ情報の確認
2helm search repo exastro
リスト 155 実行結果
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 リポジトリを更新します。
リスト 156 コマンド
1# リポジトリ情報の更新
2helm repo update
更新後のバージョンを確認します。
リスト 157 コマンド
1# リポジトリ情報の確認
2helm search repo exastro
リスト 158 実行結果
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 起動数の確認をし、状態を記録します。
    リスト 159 コマンド
    RS_AG=`kubectl get deploy ita-ag-oase -o jsonpath='{@.spec.replicas}{"\n"}' --namespace exastro`

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

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

  3. Pod 起動数の確認

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

アップグレード実施

アップグレードを実施します。
リスト 163 コマンド
helm upgrade exastro-agent exastro/exastro-agent \
  --namespace exastro \
  --values exastro-agent.yaml
リスト 164 出力結果
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 起動数を元に戻します。
    リスト 165 コマンド
    kubectl scale deployment ita-ag-oase --namespace exastro --replicas=${RS_AG}

  2. Pod 起動数の確認

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

アップグレード状況確認

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

アンインストール

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

アンインストールの準備

警告

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

アンインストール

アンインストール実施

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

永続ボリュームを削除

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

警告

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

永続データを削除

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

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