はじめに

これは Kompira Enterprise 2.0 (KE2.0) の管理者マニュアルです。

システム管理以外の Kompira Enterprise の一般的な使用方法などについては、システム構築後に Kompira Enterprise のオンラインマニュアルを参照してください。

仕様情報や活用事例については、Kompiraシリーズ製品情報サイト を参照してください。

最終更新日: 2024/08/02

改版履歴

v2.0.0 (20024/08/01)

• KE2.0.0 リリース

用語

本マニュアルで登場する用語について説明します。

ライセンス

Kompira Enterprise を利用される場合は、必ず Kompira Enterprise ライセンス利用規約 をよくお読みください。

Kompira Enterprise を継続して利用される場合はライセンス登録が必要になります。詳しくは license@kompira.jp までご連絡ください。

システム概要

KE2.0 のシステム概要について示します。

システム要件

KE2.0 のシステム要件について記載します。

ホストのリソース要件

動作確認済みホストOS一覧

• Rocky Linux 8.10 (x86_64)
• Rocky Linux 9.4 (x86_64)

コンテナ構成

KE2.0 のコンテナ構成を以下に示します。

コンテナ一覧

※ 実際のコンテナ名は構成によって ke2- とプレフィックスが付くなど多少異なります。

コンテナレジストリ

KE2.0 のコンテナイメージ自体は、Azure Container Registry 上で以下の名称で公開されます。

fixpoint.azurecr.io/kompira-enterprise

イメージにはバージョン（2.0.0 など）がタグ付けされます。また、最新バージョンのイメージには latest というタグが別名として付与されます。

ネットワーク構成

公開ポート一覧

Kompira システムをセットアップしたサーバ上では、以下のポートがデフォルトで外部から接続可能になります。

コンテナ間の連携に用いているポートは外部公開にならないため、ここでは省略しています。

ke2-docker

KE2.0 のデプロイに必要になるファイル一式をまとめた ke2-docker パッケージについて示します。

ke2-docker パッケージ

KE2.0 をデプロイするためには docker compose ファイルや各種設定ファイルなどが必要になります。 ke2-docker パッケージは、こうしたファイルのサンプルを含んでおり以下で公開しています。

https://github.com/fixpoint/ke2-docker

デプロイするサーバー上に上記リポジトリを git clone するか、あるいは ZIP ダウンロードして展開することで、KE 2.0 のデプロイができるようになります。

ke2-docker の内容

ke2-docker パッケージには以下のものが含まれます。

README.md
configs/             # 設定ファイル
ke2/                 # KE2 各構成ファイル
  single/            # シングル構成用のファイル一式
    basic/           #  - 標準シングル構成
    extdb/           #  - 外部DBシングル構成
  cluster/           # クラスタ構成用のファイル一式
    swarm/           #  - Swarmクラスタ構成
  cloud/             # クラウド構成用のファイル一式
    azureci/         #  - AzureCIクラウド構成
scripts/             # スクリプトファイル
ssl/                 # SSL 証明書配置ディレクトリ

本マニュアルでは、この ke2-docker パッケージを利用した手順を説明します。 ke2-docker パッケージは KE 自体のバージョンとは独立してバージョン管理されます。基本的には最新版をご利用ください。

構築ガイド

ここでは KE2.0 の標準的なシステム構成についての概要および構築手順を示します。

標準構成一覧

Docker Engine のインストール

いずれの構成でも Docker を用いますので、クラウド以外ではサーバに Docker Engine のインストールが必要になります。 以下の公式サイトを参考に構築環境に合わせて Docker Engine をインストールしてください。

• https://docs.docker.com/engine/install/

参考までに RHEL 環境では以下のような手順になります。

$ sudo yum install -y yum-utils
$ sudo yum-config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
$ sudo yum install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
$ sudo systemctl enable --now docker

Proxy の設定

プロキシ環境化における Docker イメージのプル

Docker daemon がイメージを pull する際に、以下に示す方法によってプロキシの設定が必要となります。 (/etc/systemd/system/docker.service.d/http-proxy.conf に HTTP_PROXY, HTTPS_PROXYの設定を行う)

https://docs.docker.jp/config/daemon/systemd.html#systemd-httphttps-proxy

設定が正しくなされているかどうかは、docker info コマンドで確認することができる。

さらに、DOCKER_BUILDKIT が有効だとビルドに失敗するため、以下のようにDOCKER_BUILDKIT環境変数に 0 をセットしてビルドする。

$ DOCKER_BUILDKIT=0 docker compose -f <Docker compose ファイル> build

プロキシ環境下におけるDocker クライアントの設定

Kompira 実行時にコンテナ内からプロキシ接続する場合、以下にあるように Docker クライアントの設定を行う必要がある。

https://docs.docker.jp/network/proxy.html#proxy-configure-the-docker-client

オンプレシングル構成

オンプレシングル構成では簡単に KE2.0 システムを構築することが出来ます。

本ガイドでは以下の構成について、その構築手順を紹介します。

• 標準シングル構成
• 外部DBシングル構成

標準シングル構成 (ke2/single/basic)

もっともシンプルな標準シングル構成について説明します。

以下のような場合には、この構成が便利です。

• とにかく簡単に KE2.0 環境をセットアップしたい。
• 処理負荷の分散などよりも、単純なシステム構成で使いたい。

構成図

本構成では、1 つの Docker ホストに全てのコンテナを配置して動作させます。

特徴

本構成には、以下の通り構成上の特徴があります。

• nginx, kompira, kengine, jobmngrd の各コンテナは、docker ボリューム kompira_var をコンテナ内の /var/opt/kompira ディレクトリに共有でバインドします。静的ファイルや Python ライブラリなどを共有します。
• postgresql コンテナは、docker ボリューム kompira_db をコンテナ内の /var/lib/postgresql/data ディレクトリにバインドします。postgresql コンテナを新たに作成しても、当該ボリュームが残されていればデータを引き継ぐことができます。

セットアップの流れ

本構成のセットアップの流れは以下のようになります。詳細については各ページを参照してください。

• サーバの準備
• KE2 のセットアップ

サーバーの準備

オンプレ環境に KE2.0 を動作させるサーバーを準備します。

サーバーの準備

システム要件 を参考に、Linux など対応するサーバーを1台用意してください。 以後の手順ではサーバーに対する root 権限が必要になりますのでご注意ください。

Docker Engine の準備

https://docs.docker.com/engine/install/ を参考に環境に合わせて Docker Engine をインストールして、Docker を起動してください。たとえば RHEL 環境では以下のような手順になります。

$ sudo yum install -y yum-utils
$ sudo yum-config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
$ sudo yum install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
$ sudo systemctl enable --now docker

KE2 のセットアップ

標準シングル構成 (ke2/single/basic) の基本的なセットアップ手順を説明します。

ke2-docker パッケージの準備

KE2.0 の構築に必要な docker compose ファイルなどを含む ke2-docker パッケージを用意してください。 ke2-docker リポジトリ から、以下のいずれかの方法でサーバー上に展開してください。

• 以下のコマンドを実行して git リポジトリをクローンしてください。(git コマンドが必要です)
  • $ git clone https://github.com/fixpoint/ke2-docker.git
• ZIP ファイルとしてダウンロードし、用意したサーバー上に配置して展開してください。(unzip コマンドが必要です)

ke2-docker パッケージを展開できたら、標準シングル構成用の docker-compose.yml ファイルを含むディレクトリに移動します。

$ cd ke2/single/basic

コンテナイメージの取得

以下のコマンドを実行してコンテナイメージを取得してください。

$ docker compose pull

※ インターネットに接続できない環境の場合は「オフライン環境での構築」を参考にしてください。

SSL 証明書の生成

以下のコマンドを実行して自己署名 SSL 証明書を生成してください。

$ ../../../scripts/create-cert.sh

コンテナの作成と開始

以下のコマンドを実行してコンテナを作成および開始を行なってください。

$ docker compose up -d

セットアップ後の動作確認

セットアップが完了したら、KE2.0 システムが正常に動作しているかを確認してください。 ブラウザで以下のアドレスにアクセスします。

https://<サーバーのアドレス>/.login

ログイン画面が表示されるため、以下の通り入力してログインしてください。

• ユーザ名：root
• パスワード：root

ログインが確認できたら、動作確認は完了です。

KE2 のアップデート

標準シングル構成 (ke2/single/basic) の基本的なアップデート手順を説明します。

リリースによっては特別なアップデート手順が指定される場合がありますので、アップデート作業前には必ずリリースノートを確認するようにしてください。

ke2-docker パッケージの更新

システム構築に用いた ke2-docker パッケージが改版されている場合は、基本的には事前に更新しておいてください。

• github からクローンしている場合は、git pull コマンドで更新してください。
• ZIP ファイルから展開している場合は、改めてダウンロードしなおして展開してください。

システム構築時に docker-compose.yml ファイルや各種設定ファイルなどをカスタマイズしている場合は、更新後に改めてカスタマイズしなおしてください。

ke2-docker ディレクトリへの移動

システム構築に用いた docker-compose.yml ファイルを含むディレクトリに移動してください。

$ cd ke2/single/basic

コンテナの削除

以下のコマンドを実行してコンテナを削除してください。

$ docker compose down

このときボリュームは削除しない（-v オプションは付けない）ことに注意してください。 これによりデータベースの内容などはアップデート後も引き継がれます。

コンテナイメージの更新

以下のコマンドを実行してコンテナイメージを更新してください。

$ docker compose pull

※ インターネットに接続できない環境の場合は「オフライン環境での構築」を参考にしてください。

コンテナの作成と開始

以下のコマンドを実行してコンテナを作成および開始を行なってください。

$ docker compose up -d

外部DBシングル構成 (ke2/single/extdb)

先の標準シングル構成では 1 つの Docker ホスト上にすべてのコンテナを配置して動作させていましたが、 この外部DBシングル構成はそこからデータベースのコンテナを除外したような構成になっています。 データベースについてはコンテナ外部に別途用意して、コンテナ内部の各機能からアクセスするようにセットアップします。

以下のような場合には、この構成が便利です。

• 別環境に独自にデータベースを構築したい
• 既存のデータベースと連携した構成をとりたい
• データベース処理の負荷をオフロードしたい

構成図

本構成では、1 つの Docker ホストにデータベース以外のコンテナを配置して動作させます。

前提条件

本構成を利用するには以下のような前提条件があります。

• 外部データベースとして連携できるのは PostgreSQL 12 以上となります。
• コンテナ環境から外部データベースまでネットワーク的に直接到達できる必要があります。
• 外部データベースには、ホスト名、ポート番号、ユーザ名、パスワード、データベース名の指定だけで接続できる必要があります。
• Kompira のデータベースでは拡張モジュール pgcrypto を利用しますので、外部配置の PostgreSQL に拡張モジュールを追加する機能と権限が必要になります。

セットアップの流れ

本構成のセットアップの流れは以下のようになります。詳細については各ページを参照してください。

• サーバの準備
• データベースの準備
• KE2 のセットアップ

サーバーの準備

オンプレ環境に KE2.0 を動作させるサーバーを準備します。

サーバーの準備

システム要件 を参考に、Linux など対応するサーバーを1台用意してください。 以後の手順ではサーバーに対する root 権限が必要になりますのでご注意ください。

Docker Engine の準備

https://docs.docker.com/engine/install/ を参考に環境に合わせて Docker Engine をインストールして、Docker を起動してください。たとえば RHEL 環境では以下のような手順になります。

$ sudo yum install -y yum-utils
$ sudo yum-config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
$ sudo yum install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
$ sudo systemctl enable --now docker

データベースの準備

この構成では、外部データベースとして以下の要件を満たす PostgreSQL が必要になります。

• バージョン: 12 以上
• その他: 拡張モジュール pgcrypto がインストールされていること (RHEL系 であれば、postgresql-contrib パッケージをインストールしておく必要があります)

Docker が動作しているホストサーバ、あるいは別のサーバ上に要件を満たす PostgreSQL を準備してください。

接続仕様の準備

この構成では、Docker コンテナで動作するサービスからデータベースに接続するための情報を、環境変数 DATABASE_URL で指定する必要があります。

DATABASE_URL=pgsql://<ユーザ名>:<パスワード>@<アドレス>:<ポート番号>/<データベース名>

たとえば外部データベースの接続に必要なパラメータが以下のような場合を考えます。

この場合、環境変数 DATABASE_URL は次のように指定することになります。

DATABASE_URL=pgsql://kompira:kompira@10.20.0.XXX:5432/kompira

実際に準備した、またはこれから準備する PostgreSQL サーバの構成に合わせて、DATABASE_URL に指定する値を準備しておいてください。

PostgreSQL の準備

PostgreSQL のインストールについては準備する環境に合わせて、OS のマニュアルなどを参考にして実施してください。

以下では、PostgreSQL の最低限必要になる設定手順について記述しますので、用意した PostgreSQL サーバ上で実施してください。 詳細な設定方法については PostgreSQL のホームページや公式ドキュメントを参照してください。

(1) kompira ユーザーとデータベースの作成

ユーザを作成します。ここではデフォルトの "kompira" という名前で作成します。パスワードの設定も求められるのでこれもデフォルトの "kompira" と入力してください。

$ sudo -i -u postgres createuser -d -P "kompira"

上で作成したユーザをオーナーとするデータベースを作成します。ここではデフォルトの "kompira" という名前で作成します。

$ sudo -i -u postgres createdb --owner="kompira" --encoding=utf8 "kompira"

(2) PostgreSQL サーバの接続設定

ローカルホスト以外からも PostgreSQL サーバに接続できるように設定します。 postgresql.conf (RHEL系標準パッケージをインストールした場合は /var/lib/pgsql/data/postgresql.conf) の listen_address を以下のように設定してください。

listen_address = '*'

(3) PostgreSQL のクライアント認証の設定

手順 (1) で作成したユーザからパスワード接続できるように、pg_hba.conf (RHEL系標準パッケージをインストールした場合は /var/lib/pgsql/data/pg_hba.conf) に host 設定を追加してください。 たとえば Docker が動作しているホストが PostgreSQL サーバと同じネットワークに配置している場合は、以下のような行を追加してください。

host    kompira         kompira         samenet             scram-sha-256

あるいは、Docker が異なるネットワークに配置されている場合は、"samenet" の部分を CIDR 形式などで指定するようにしてください。

host    kompira         kompira         10.10.0.0/16        scram-sha-256

(4) PostgreSQL の再起動

これらの設定を行なった後は、一度 postgresql サービスを再起動してください。

$ sudo systemctl restart postgresql-<バージョン番号>

KE2 のセットアップ

外部DBシングル構成 (ke2/single/extdb) の基本的なセットアップ手順を説明します。

ke2-docker パッケージの準備

KE2.0 の構築に必要な docker compose ファイルなどを含む ke2-docker パッケージを用意してください。 ke2-docker リポジトリ から、以下のいずれかの方法でサーバー上に展開してください。

• 以下のコマンドを実行して git リポジトリをクローンしてください。(git コマンドが必要です)
  • $ git clone https://github.com/fixpoint/ke2-docker.git
• ZIP ファイルとしてダウンロードし、用意したサーバー上に配置して展開してください。(unzip コマンドが必要です)

ke2-docker パッケージを展開できたら、外部 DB シングル構成用の docker-compose.yml ファイルを含むディレクトリに移動します。

$ cd ke2/single/extdb

コンテナイメージの取得

以下のコマンドを実行してコンテナイメージを取得してください。

$ docker compose pull

※ インターネットに接続できない環境の場合は「オフライン環境での構築」を参考にしてください。

SSL 証明書の生成

以下のコマンドを実行して自己署名 SSL 証明書を生成してください。

$ ../../../scripts/create-cert.sh

秘密鍵ファイルの準備

データベース上でのパスワード情報などの暗号化に用いる秘密鍵をファイル .secret_key に準備します。 Kompira 用データベースを新規に構築する場合は、たとえば以下のようにして空のファイルを用意してください。

$ touch .secret_key

※ 外部データベースとして既に構築されている Kompira データベースを用いる場合は、そのデータベースにおける秘密鍵を .secret_key に書き込んでおいてください。

$ echo -n 'xxxxxxxxxxxxxxxx' > .secret_key

コンテナの作成と開始

以下のコマンドを実行してコンテナを作成および開始を行なってください。 このとき先に準備した環境変数 DATABASE_URL を指定するようにしてください。

$ DATABASE_URL=pgsql://... docker compose up -d

セットアップ後の動作確認

セットアップが完了したら、KE2.0 システムが正常に動作しているかを確認してください。 ブラウザで以下のアドレスにアクセスします。

https://<サーバーのアドレス>/.login

ログイン画面が表示されるため、以下の通り入力してログインしてください。

• ユーザ名：root
• パスワード：root

ログインが確認できたら、動作確認は完了です。

KE2 のアップデート

外部DBシングル構成 (ke2/single/extdb) の基本的なアップデート手順を説明します。

リリースによっては特別なアップデート手順が指定される場合がありますので、アップデート作業前には必ずリリースノートを確認するようにしてください。

ke2-docker パッケージの更新

システム構築に用いた ke2-docker パッケージが改版されている場合は、基本的には事前に更新しておいてください。

• github からクローンしている場合は、git pull コマンドで更新してください。
• ZIP ファイルから展開している場合は、改めてダウンロードしなおして展開してください。

システム構築時に docker-compose.yml ファイルや各種設定ファイルなどをカスタマイズしている場合は、更新後に改めてカスタマイズしなおしてください。

ke2-docker ディレクトリへの移動

システム構築に用いた docker-compose.yml ファイルを含むディレクトリに移動してください。

$ cd ke2/single/extdb

コンテナの削除

以下のコマンドを実行してコンテナを削除してください。

$ docker compose down

このときボリュームは削除しない（-v オプションは付けない）ことに注意してください。 これによりデータベースの内容などはアップデート後も引き継がれます。

コンテナイメージの更新

以下のコマンドを実行してコンテナイメージを更新してください。

$ docker compose pull

※ インターネットに接続できない環境の場合は「オフライン環境での構築」を参考にしてください。

コンテナの作成と開始

以下のコマンドを実行してコンテナを作成および開始を行なってください。

$ docker compose up -d

オンプレクラスタ構成

オンプレクラスタ構成では Kompira エンジンなどのコンテナを複数のノードで動作させることで、可用性の向上やジョブフローの並列実行によるスループット向上が狙えます。

本ガイドでは以下の構成について、その構築手順を紹介します。

• Swarmクラスタ構成

Swarmクラスタ構成

この Swarm クラスタ構成では、クラスタ管理に Docker Swarm を採用しており、シングル構成同様に docker compose ファイルによってクラスタ構成を定義します。

前提条件

Swarm クラスタ構成には、以下の前提条件があります。

• 同一 LAN 上に配置するホスト（Linux サーバ）が最小で3台必要になります。
  • この 3台のホスト上にそれぞれ Docker Swarm のマネージャノードを起動してクラスタを構成します。
• 外部データベース構成を取る必要があります。
  • 外部DBシングル構成と同様に PostgreSQL データベースを準備する必要があります。
• 各ホストでディレクトリを共通出来るように、ネットワークファイルシステムを用意する必要があります。

セットアップの流れ

ここでは、以下のようなシステム構成をセットアップする手順を紹介します。

• 3台のサーバーによる Docker Swram クラスタ構成
• GlusterFS による共有ファイルシステム
• PostgreSQL/Pgpool-II によるクラスタ型外部データベース

上記条件での本構成のセットアップの流れは以下のようになります。詳細については各ページを参照してください。

• サーバーの準備
• Swarm クラスタの準備
• GlusterFS の準備
• Pgpool-II の準備
• KE2 のセットアップ

なお、以降の説明では、ホストとして RHEL 9 系 (CentOS Stream 9、AlmaLinux 9、RockyLinux 9も含む) サーバの利用を想定しています。 Ubuntu など別のディストリビューションを利用する場合は、適宜、コマンド等を読み替えてください。

コマンド実行手順表示について

本構成のセットアップ手順では、すべてのホストサーバ上でコマンドを実行する場合や、あるいは特定のホストサーバ上でだけコマンドを実行する場合などがあります。

以後の手順説明において、以下のように表示されている手順はすべてのホストサーバ上でコマンドを実行するようにしてください。とくに指定がない場合は実行順は問いません。

[全ホスト]$ command ...

以下のように表示されている手順については、[ホスト名] に記されたホストサーバ上でコマンドを実行するようにしてください。

[ホスト名]$ command ...

サーバーの準備

Docker Swarm (24.0以降) が動作する Linux サーバ 3台を準備します。

以降の構築手順では、3台のホストのホスト名と IP アドレスを以下のように想定しています。

• ke2-server1: 10.20.0.1
• ke2-server2: 10.20.0.2
• ke2-server3: 10.20.0.3

また、Pgpool-II クラスタに設定する仮想 IP アドレスとしては 10.20.0.100 を使用します。

名前解決の準備

各サーバはお互いにホスト名で名前解決できる必要があります。 DNS サーバに名前登録するか、各サーバ上の /etc/hosts に設定を追加してください。

Swarm クラスタの準備

Docker CE のインストール

Docker の公式リポジトリを追加し、Docker CE を各ホストにインストールしてください。 各ホスト上で以下のコマンドを実行します。

[全ホスト]$ sudo dnf config-manager --add-repo=https://download.docker.com/linux/centos/docker-ce.repo
[全ホスト]$ sudo dnf install docker-ce

次に、Docker サービスの有効化と起動を行います。

[全ホスト]$ sudo systemctl enable --now docker

ユーザの docker グループへの追加

現在のユーザーが sudo せずに dockerコマンドを実行できるように、現在のユーザを docker グループに所属させます。(本手順は省略してもかまいません）

[全ホスト]$ sudo usermod -aG docker $USER

なお、上記の設定を反映させるには、一度ログアウトしてから、再度ログインし直す必要があります。

ファイアウォールの設定

本構成では以下のポートを用いた通信ができるようにする必要があります。

• TCP ポートの 2377: クラスター管理における通信のため
• TCP および UDP ポートの 7946: ノード間の通信のため
• UDP ポートの 4789: オーバーレイネットワークのトラフィックのため

各ホスト上で、以下のコマンドを実行してポートを開放してください（システムによってはデフォルトで開放されている場合もあります）。

[全ホスト]$ sudo firewall-cmd --permanent --add-port=2377/tcp
[全ホスト]$ sudo firewall-cmd --permanent --add-port=7946/tcp --add-port=7946/udp
[全ホスト]$ sudo firewall-cmd --permanent --add-port=4789/udp
[全ホスト]$ sudo firewall-cmd --reload

ただし、VMWare 環境で構築する場合は、注意事項があります。

Docker Swarm クラスタの初期化

最初のマネージャノード（ここでは ke2-server1 を想定します）となる Docker ホスト上で以下を実行してください。

[ke2-server1]$ docker swarm init

ただし、VMWare 環境で構築する場合や、サーバが複数ネットワークに属する場合には、以下の注意事項があります。

VMWare 環境での注意事項

VMWare の仮想サーバでネットワークインタフェースに vmxnet3 を利用している場合、 Swarm のオーバーレイネットワークが利用する 4789 番ポートと衝突し、Swarm ノード間の TCP 通信ができない問題が報告されています。 これを回避するためには、docker swarm init に --data-path-port オプションで 4789 以外のポート番号を指定する必要があります。 合わせて、ファイアウォールの設定も、ここで指定したポートでノード間の通信を許可するように追加します。

標準の 4789 ポートではなく例えば 14789 ポートを利用する場合は、docker swarm init 時に以下のように --data-path-port オプションで指定してください。

[ke2-server1]$ docker swarm init --data-path-port=14789

標準ではないポートを --data-path-port に指定した場合は、そのポートでノード間通信が出来るようにファイアウォールの設定も加えて実施してください。

[全ホスト]$ sudo firewall-cmd --permanent --add-port=14789/udp
[全ホスト]$ sudo firewall-cmd --reload

複数ネットワーク環境での注意事項

サーバが複数の IP アドレスを持つような環境では、docker swarm init コマンド実行時に --advertise-addr オプションの指定を求められる場合があります。 クラスタ構成を組む（すべてのノードが属している）ネットワークの IP アドレスを --advertise-addr オプションで指定するようにしてください。

[ke2-server1]$ docker swarm init --advertise-addr=10.20.0.1

※ VMWare 環境では --data-path-port オプションも合わせて指定するようにしてください。

マネージャノードの追加

続いて、以下のコマンドを実行して、マネージャノードを追加するコマンドを取得します。

[ke2-server1]$ docker swarm join-token manager

このコマンドを実行すると、次のような表示があるはずです。

To add a manager to this swarm, run the following command:

    docker swarm join \
    --token <トークン> \
    <IPアドレス>:2377

ここに表示されているコマンドを次の手順で、他のホスト上で実行することになります。

マネージャノードの追加

先の手順を実行したときに表示された docker swarm join コマンドを、2つ目、3つ目の Docker ホスト上でそれぞれ実行してください。

[ke2-server{2,3}]$ docker swarm join --token <トークン> <IPアドレス>:2377

ノード一覧の確認

任意の Docker ホスト上で以下のコマンドを実行すると、Swarmクラスタに参加しているノード一覧を表示することができます。

[ke2-server1]$ docker node ls
ID                            HOSTNAME        STATUS    AVAILABILITY   MANAGER STATUS   ENGINE VERSION
ee5c0f5j5dt1m2x6vemrz7dxy *   ke2-server1     Ready     Active         Reachable        25.0.4
ypqsarfbtuwrit9hekiqac03u     ke2-server2     Ready     Active         Reachable        25.0.4
t8zhg0ez1xezj0942d7zb4u6h     ke2-server3     Ready     Active         Leader           25.0.4

3台のノードの STATUS が Ready になっていること、いずれかのノードの MANAGER STATUS が Leader になっていることを確認してください。

GlusterFS の準備

クラスタ構成では Docker Swarm 上で動作する各ホスト上の Kompira のコンテナからアクセス可能な共有ディレクトリが必要になります。 すでに、利用可能な共有ファイルサーバがある場合は、そのサーバ上のディレクトリを Docker Swarm の各ホストからマウントして利用することもできます。

ここでは、GlusterFS 分散ファイルシステムを用いて共有ディレクトリを準備します。

GlusterFS インストールと設定

各ホスト上で以下のコマンドを実行して、GlusterFS をインストールします。

[全ホスト]$ sudo dnf install centos-release-gluster10
[全ホスト]$ sudo dnf install glusterfs-server

次に、GlusterFS サービスの有効化と起動を行います。

[全ホスト]$ sudo systemctl enable --now glusterd

ファイアウォールの設定

各ホスト上で、以下のコマンドを実行してポートを開放します。

[全ホスト]$ sudo firewall-cmd --add-service=glusterfs --permanent
[全ホスト]$ sudo firewall-cmd --reload

プールの構築

どれか1つのノードで、gluster peer probe コマンドを実行し、他のサーバをプールに追加します。

ke2-server1 上で実行する場合：

[ke2-server1]$ sudo gluster peer probe ke2-server2
[ke2-server1]$ sudo gluster peer probe ke2-server3

プールを構成するサーバの一覧は、以下のコマンドで確認することができます。

[ke2-server1]$ sudo gluster pool list
UUID                                    Hostname        State
9d593742-d630-48b0-8570-066d15822c4d    ke2-server2     Connected
9b7f2c39-a0ce-498f-9939-4fcf55a36fac    ke2-server3     Connected
d47ce78a-0ffd-468f-9218-32fa2d97c431    localhost       Connected

GlusterFS ボリュームの作成

ボリューム gvol0 を作成してスタートします。 GlusterFS クラスタ内のどれか1つのノード上で（以下の例では ke2-server1 を想定）以下を実行します。 (ここでは root パーティションに作成しているため、force オプションが必要です)

[ke2-server1]$ sudo gluster vol create gvol0 replica 3 ke2-server1:/var/glustervol0 ke2-server2:/var/glustervol0 ke2-server3:/var/glustervol0 force
[ke2-server1]$ sudo gluster vol start gvol0

ボリュームの マウント

作成した gvol0 ボリュームを各ノード上でマウントします。

[全ホスト]$ sudo mkdir /mnt/gluster
[全ホスト]$ sudo mount -t glusterfs localhost:/gvol0 /mnt/gluster

再起動時に自動的にマウントされるように以下を /etc/fstab に追加しておきます。

localhost:/gvol0 /mnt/gluster glusterfs _netdev,defaults 0 0

Pgpool-II の準備

各 Swarm ノード上で実行している Kompira エンジンや Kompira アプリケーションサーバのコンテナからアクセス可能なデータベースとして、 PostgreSQL/Pgpool-II クラスタを構築する手順について説明します。

Pgpool-II を用いたデータベースクラスタには最低で 3台 のホストが必要となります。

ここでは、Docker Swarm クラスタのホスト上にデータベースクラスタを同居した形で構築していますが、Docker Swarm クラスタとは別にデータベースクラスタを構築しても構いません。

PostgreSQL/Pgpool-II のセットアップ

ここでは、ke2-docker パッケージに附属するセットアップ用のスクリプトを用いて構築する手順を示します。 このスクリプトは RHEL 9系 (CentOS Stream 9、Rocky Linux 9、AlmaLinux 9など互換 OS を含む) のサーバを対象としています。 その他の OS 上にセットアップする場合は、スクリプトの内容を参考にして構築してください。

なお、本セットアップスクリプトでは、PostgreSQL/Pgpool-II の各ユーザーとパスワードをデフォルトで以下のように設定します。

(1) 各ホストへのスクリプトファイル転送

ke2-docker パッケージの ke2/cluster/swarm ディレクトリに含まれる以下のスクリプトファイルを、クラスタを構成する各ホストに転送してください。

• setup_pgpool.sh
• setup_pgssh.sh

(2) PostgreSQL/Pgpool-II のインストール

各ホストで setup_pgpool.sh スクリプトを実行します。 このスクリプトでは、PostgreSQL 16、および、Pgpool-II のインストールと初期設定を行います。 setup_pgpool.sh 起動時には以下の環境変数を指定する必要があります。

• CLUSTER_VIP: Pgpool-II で使用する仮想IPアドレス
• CLUSTER_HOSTS: クラスタを構成するホスト名（空白区切り）

CLUSTER_HOSTS の最初のホストを「プライマリサーバ」として、残りのホストを「セカンダリサーバ」としてセットアップします。 また CLUSTER_HOSTS の順番に Pgpool-II 上でのノード ID を 0, 1, 2,... と割り当てます。 したがって、各ホスト上で setup_pgpool.sh を実行する際に、CLUSTER_HOSTS のホスト順序は同一にする必要があることに注意してください。

以下に実行例を示します。

[全ホスト]$ CLUSTER_VIP=10.20.0.100 CLUSTER_HOSTS='ke2-server1 ke2-server2 ke2-server3' ./setup_pgpool.sh

一般ユーザで実行する場合、起動後に sudo のパスワードを入力を求められます。

(3) Pgpool-II 用の SSH 接続設定

各ホストで setup_pgssh.sh スクリプトを実行します。 このスクリプトでは Pgpool-II の自動フェイルオーバおよびオンラインリカバリ機能を利用するため、各ノード間で postgres ユーザが公開鍵認証で SSH 接続できるように設定します。 先ほどの手順と同様に CLUSTER_HOSTS 環境変数を指定して setup_pgssh.sh スクリプトを実行してください。

[全ホスト]$ CLUSTER_HOSTS='ke2-server1 ke2-server2 ke2-server3' ./setup_pgssh.sh

setup_pgssh.sh は postgres ユーザーの SSH 鍵ファイルを作成し、公開鍵ファイルを CLUSTER_HOSTS で指定された各ホストの ~postgres/.ssh/authorized_keys に追加することで、パスワード無しで SSH 接続できるようにします。 一般ユーザで実行する場合、起動後に sudo のパスワードを入力、および、実行ユーザがクラスタを構成する各リモートホストにログインするためのパスワードとリモートホストでの sudo パスワードの入力を求められます。

パスワード入力を間違えるなどで公開鍵の転送に失敗していると、Pgppol-II が正常に機能しなくなるので注意してください。

Pgpool-II の起動とオンラインリカバリ

ここでは、Pgpool-II を起動して PostgreSQL のクラスタ構成を行ないます。

(1) Pgpool-II の起動

プライマリサーバ（ここでは ke2-server1 を想定）から順番に、各ホスト上で以下のコマンドを実行して Pgpool-II を起動してください。

[全ホスト]$ sudo systemctl start pgpool

(2) プライマリサーバの状態確認

プライマリサーバでは setup_pgpool.sh の実行によって、既に PostgreSQL サーバが起動しています。 いずれかのホスト上で以下のコマンドを実行して、プライマリサーバで PostgreSQL がプライマリモードで動作していることを確認してください。

[任意のホスト]$ psql -h $CLUSTER_VIP -p 9999 -U pgpool postgres -c "show pool_nodes"

$CLUSTER_VIP の部分は Pgpool-II で使用する仮想IPアドレスに置き換えるか、シェル変数 CLUSTER_VIP としてそのアドレスを設定しておいてください。 下記の例では、プライマリサーバである ke2-server1 で PostgreSQL がプライマリモードで起動しており（pg_status が "up"、pg_role が "primary"）、ke2-server2 と ke2-server3 では PostgreSQL がまだ起動していないこと（pg_status が "down"）が分かります。

[ke2-server1]$ psql -h 10.20.0.100 -p 9999 -U pgpool postgres -c "show pool_nodes"
ユーザー pgpool のパスワード: 
 node_id |   hostname  | port | status | pg_status | lb_weight |  role   | pg_role | select_cnt | load_balance_node | replication_delay | replication_state | replication_sync_state | last_status_change  
---------+-------------+------+--------+-----------+-----------+---------+---------+------------+-------------------+-------------------+-------------------+------------------------+---------------------
 0       | ke2-server1 | 5432 | up     | up        | 0.333333  | primary | primary | 0          | true              | 0                 |                   |                        | 2024-06-11 18:18:20
 1       | ke2-server2 | 5432 | down   | down      | 0.333333  | standby | unknown | 0          | false             | 0                 |                   |                        | 2024-06-11 18:16:06
 2       | ke2-server3 | 5432 | down   | down      | 0.333333  | standby | unknown | 0          | false             | 0                 |                   |                        | 2024-06-11 18:16:06
(3 行)

(3) スタンバイサーバのオンラインリカバリ

Pgpool-II のオンラインリカバリ機能を利用し、ke2-server2 と ke2-server3 をスタンバイサーバとして起動させて、Pgpool-II 管理下に追加します。

オンラインリカバリさせるには、以下のように pcp_recovery_node コマンドを実行してください。

[任意のホスト]$ pcp_recovery_node -h $CLUSTER_VIP -p 9898 -U pgpool -n {ノードID} -W

{ノードID} の部分はオンラインリカバリさせるノード ID に置き換えてください。 上で確認したとおり ke2-server1 がノードID 0 でプライマリサーバとして動作していますので、ここではノード ID に 1 および 2 を指定して ke2-server2 と ke2-server3 をオンラインリカバリさせています。

[ke2-server1]$ pcp_recovery_node -h 10.20.0.100 -p 9898 -U pgpool -n 1 -W
Password:
pcp_recovery_node -- Command Successful

[ke2-server1]$ pcp_recovery_node -h 10.20.0.100 -p 9898 -U pgpool -n 2 -W
Password:
pcp_recovery_node -- Command Successful

(4) スタンバイサーバの状態確認

オンラインリカバリによって PostgreSQL のスタンバイサーバが起動していることを、再び以下のコマンドで確認してください。

[任意のホスト]$ psql -h $CLUSTER_VIP -p 9999 -U pgpool postgres -c "show pool_nodes"

以下の例では、ke2-server2 と ke2-server3 で PostgreSQL がスタンバイサーバとして起動していること（pg_status が "up"、pg_role が "standby"）が分かります。

[ke2-server1]$ psql -h 10.20.0.100 -p 9999 -U pgpool postgres -c "show pool_nodes"
ユーザー pgpool のパスワード: 
 node_id |   hostname  | port | status | pg_status | lb_weight |  role   | pg_role | select_cnt | load_balance_node | replication_delay | replication_state | replication_sync_state | last_status_change  
---------+-------------+------+--------+-----------+-----------+---------+---------+------------+-------------------+-------------------+-------------------+------------------------+---------------------
 0       | ke2-server1 | 5432 | up     | up        | 0.333333  | primary | primary | 0          | false             | 0                 |                   |                        | 2024-06-11 18:18:20
 1       | ke2-server2 | 5432 | up     | up        | 0.333333  | standby | standby | 0          | true              | 0                 | streaming         | async                  | 2024-06-11 18:22:54
 2       | ke2-server3 | 5432 | up     | up        | 0.333333  | standby | standby | 0          | false             | 0                 | streaming         | async                  | 2024-06-11 18:22:54
(3 行)

セットアップ手順

Swarm クラスタ構成 (ke2/cluster/swarm) の基本的なセットアップ手順を説明します。

本ページの手順は Docker Swarm クラスタを構成するいずれかのマネージャノード上で実行してください。

デプロイの準備

クラスタ構成の KE2.0 を開始するための準備を行ないます。 ke2-docker パッケージの、Swarm クラスタ構成用のディレクトリに移動します。

[ke2-server1]$ cd ke2/cluster/swarm

コンテナイメージの取得

以下のコマンドを実行してコンテナイメージを取得してください。

[ke2-server1]$ docker compose pull

※ インターネットに接続できない環境の場合は「オフライン環境での構築」を参考にしてください。

SSL 証明書の生成

以下のコマンドを実行して自己署名 SSL 証明書を生成してください。

[ke2-server1]$ ../../../scripts/create-cert.sh

共有ディレクトリの作成

ネットワークファイルシステム上に共有ディレクトリ (SHARED_DIR) と以下に示すサブディレクトリを作成してください。

- ${SHARED_DIR}/
	- log/
	- var/
	- ssl/

SHARED_DIR を /mnt/gluster とする場合は、例えば以下のようにディレクトリを作成できます。

[ke2-server1]$ mkdir -p /mnt/gluster/{log,var,ssl}

秘密鍵ファイルの準備

データベース上でのパスワード情報などの暗号化に用いる秘密鍵をファイル ${SHARED_DIR}/var/.secret_key に準備します。 Kompira 用データベースを新規に構築する場合は、たとえば以下のようにして空のファイルを用意してください。

[ke2-server1]$ touch /mnt/gluster/var/.secret_key

※ 外部データベースとして既に構築されている Kompira データベースを用いる場合は、そのデータベースにおける秘密鍵を ${SHARED_DIR}/var/.secret_key に書き込んでおいてください。

[ke2-server1]$ echo -n 'xxxxxxxxxxxxxxxx' > .secret_key

docker-swarm.yml の生成

docker-swarm.yml を生成するために、以下のコマンドを実行してください。 このとき少なくとも環境変数 SHARED_DIR で共有ディレクトリを指定するようにしてください。

[ke2-server1]$ SHARED_DIR=/mnt/gluster ./setup_stack.sh

Swarm クラスタの開始

エラーが無ければ docker-swarm.yml というファイルが生成されているはずです。 これでシステムを開始する準備ができました。以下のコマンドを実行して Kompira Enterprise 開始をします。

[ke2-server1]$ docker stack deploy -c docker-swarm.yml ke2

正常に動作しない場合は、以下のコマンドでクラスタを停止させて、設定を見直してみてください。

[ke2-server1]$ docker stack rm ke2

セットアップ後の動作確認

セットアップが完了したら、KE2.0 システムが正常に動作しているかを確認してください。 ブラウザで以下のアドレスにアクセスします。

https://<サーバーのアドレス>/.login

ログイン画面が表示されるため、以下の通り入力してログインしてください。

• ユーザ名：root
• パスワード：root

ログインが確認できたら、動作確認は完了です。

カスタマイズ

環境変数によるカスタマイズ

setup_stack.sh を実行するときに環境変数を指定することで、簡易的なカスタマイズを行なうことができます。

[ke2-server1]$ 環境変数=値... ./setup_stack.sh

カスタマイズ例:

[ke2-server1]$ DATABASE_URL="pgsql://kompira:kompira@10.20.0.100:9999/kompira" SHARED_DIR=/mnt/gluster ./setup_stack.sh

詳細なカスタマイズ

コンテナ構成などを詳細にカスタマイズしたい場合は、setup_stack.sh スクリプトで生成された docker-swarm.yml ファイルを、目的に合わせてカスタマイズしてください。

アップデート手順

Swarm クラスタ構成 (ke2/cluster/swarm) におけるアップデート手順を示します。

クラウド構成

クラウド構成の構築ガイドについては準備中です。

外部連携構成

いずれかの構成でセットアップした KE2.0 システムの外部に、ジョブマネージャを単体で配置したり、kompira_sendevt をインストールしてメッセージ送信に利用したい場合があります。ここでは、こうした外部連携の構成について説明します。

KE2.0 側での準備

外部にジョブマネージャや kompira_sendevt を配置して、KE2.0 システムと連携させたい場合、KE2.0 システム側で以下の準備が事前に必要になります。

• AMQPS 接続を許可するファイヤーウォールの設定
• rabbitmq に外部接続用のユーザの追加とパーミッションの設定

AMQPS の接続許可

まず OS ごとの手順で AMQPS (5671番ポート) の許可設定を行なってください。firewall-cmd を使う場合の例は以下のようになります。KE2.0 がクラスタ構成の場合は全てのノードで許可設定を行なってください。

$ sudo firewall-cmd --add-service=amqps --permanent
$ sudo firewall-cmd --reload

rabbitmq へのユーザ追加

続けて rabbitmq に外部から接続するためのユーザーを追加し、パーミッションを設定してください。 ここでは、ユーザ名 kompira / パスワード kompira で設定する場合の例を以下に示します。

$ docker exec $(docker ps -q -f name=rabbitmq) rabbitmqctl add_user kompira kompira
$ docker exec $(docker ps -q -f name=rabbitmq) rabbitmqctl set_permissions --vhost / kompira '.*' '.*' '.*'

外部 jobmngrd 構成

サーバ上でジョブマネージャだけをコンテナで動作させる構成について示します。

外部 jobmngrd の動作環境

動作環境の要件については KE2.0 本体と同様ですが、リソース要件については以下のように緩和します。

コンテナとして動作させるため、ホストサーバ上に事前に Docker のインストールは行なっておいてください。

外部 jobmngrd のセットアップ

外部 jobmngrd 構成をセットアップする手順について説明します。

KE2.0 システム側の事前準備については、KE2.0 側での準備 を参考に実施しておいてください。

ke2-docker パッケージの準備

KE2.0 の構築に必要な docker compose ファイルなどを含む ke2-docker パッケージを用意してください。 ke2-docker リポジトリ から、以下のいずれかの方法でサーバー上に展開してください。

• 以下のコマンドを実行して git リポジトリをクローンしてください。(git コマンドが必要です)
  • $ git clone https://github.com/fixpoint/ke2-docker.git
• ZIP ファイルとしてダウンロードし、用意したサーバー上に配置して展開してください。(unzip コマンドが必要です)

ke2-docker パッケージを展開できたら、外部 jobmngrd 構成用の docker-compose.yml ファイルを含むディレクトリに移動します。

$ cd ke2/extra/jobmngrd

コンテナイメージの取得

以下のコマンドを実行してコンテナイメージを取得してください。

$ docker compose pull

※ インターネットに接続できない環境の場合は「オフライン環境での構築」を参考にしてください。

コンテナの作成と開始

以下のコマンドを実行してコンテナを作成および開始を行なってください。

$ AMQP_URL=... docker compose up -d

このとき KE2.0 が動作しているシステムの rabbitmq に接続できるように、rabbitmq に追加したユーザやパスワードに合わせて AMQP_URL を指定してください。

$ AMQP_URL=amqps://kompira:kompira@{{rabbitmqのアドレス}}:5671 docker compose up -d

セットアップ後の動作確認

ブラウザで KE2.0 の「管理領域設定 > デフォルト」 (/config/realms/default) を確認して、「ジョブマネージャ状態」一覧にこのホストがステータス「動作中」として表示されていれば、外部 jobmngrd 構成のセットアップは成功です。

外部 kompira_sendevt

KE2.0 に対して外部からメッセージを送信するために、kompira_sendevt を使う方法について説明します。

Kompira-sendevt パッケージ

kompira_sendevt コマンドを含む Python パッケージ Kompira-sendevt は pypi.org で公開しています。

https://pypi.org/project/Kompira-sendevt/

なお、kompira_sendevt 専用の Docker イメージを配布する予定はありません。

Python のインストール

Python パッケージ Kompira-sendevt をインストールするには、インストール先に Python 自体がインストールされている必要があります。

そのため、まずはインストール先のサーバに Python をインストールしておいてください。Python のインストール方法については Python の公式ページを参照してください。

Python の対応バージョンは 3.8 以上とします。

外部 kompira_sendevt のインストール

Linux 環境へのインストール

Kompira-sendevt 用の独立した Python 仮想環境 (venv) を作成します。 ここでは /opt/kompira に作成する前提で説明します。

$ python -m venv /opt/kompira

ログファイルの出力先としてディレクトリ /var/log/kompira を作成します。

$ mkdir -p /var/log/kompira

pip コマンドで Kompira-sendevt パッケージをインストールしてください。

$ /opt/kompira/bin/pip install Kompira-sendevt==2.0.0b1

kompira_sendevt コマンドは /opt/kompira/bin にインストールされますので、 次のように kompira_sendevt コマンドを実行してみてください。

$ /opt/kompira/bin/kompira_sendevt --version
kompira_sendevt (Kompira version 2.0.0b1)

正しくインストールされていれば、バージョン番号が出力されます。

Windows 環境へのインストール

Kompira-sendevt 用の独立した Python 仮想環境 (venv) を作成します。 ここでは C:\Kompira に作成する前提で説明します。

C:\> python -m venv C:\Kompira

ログファイルの出力先としてディレクトリ C:\Kompira\Log を作成します。

C:\> mkdir C:\Kompira\Log

pip コマンドで Kompira-sendevt パッケージをインストールしてください。

C:\> C:\Kompira\Scripts\pip.exe install Kompira-sendevt==2.0.0b1

kompira_sendevt コマンドは C:\Kompira\Scripts にインストールされますので、 次のように kompira_sendevt コマンドを実行してみてください。

C:\> C:\Kompira\Scripts\kompira_sendevt.exe --version
kompira_sendevt (Kompira version 2.0.0b1)

正しくインストールされていれば、バージョン番号が出力されます。

オフライン環境での構築

インターネットに接続できない環境で KE2.0 をセットアップする必要がある場合、次のような手順が必要になります。

• オンライン環境でコンテナイメージを pull してファイルにセーブする
• オフライン環境のサーバにセーブファイルを転送してロードする

コンテナイメージのセーブ

オンライン環境で ke2-docker パッケージのいずれかの構成のディレクトリで、docker compose pull を実行してコンテナイメージを取得してください。

$ docker compose pull

docker images コマンドでいくつかのイメージが存在していることを確認してください。

$ docker images

docker save コマンドでコンテナイメージをセーブしてください。ファイルサイズが大きくなるのでここでは gzip で圧縮しています。

$ docker save $(docker images --format "{{.Repository}}") | gzip > ke2-docker-images.gz

このときコマンドを実行した docker 環境に存在する全てのコンテナイメージがセーブされます。 不要なコンテナイメージが含まれている場合は不要なイメージを削除してから実行するか、 docker save コマンドのオプションに必要なコンテナイメージだけを指定するようにしてください。

$ docker save kompira.azurecr.io/kompira-enterprise registry.hub.docker.com/library/{rabbitmq,postgres,redis,nginx} | gzip > ke2-docker-images.gz

イメージファイルの転送

インストール先となるオフライン環境のサーバに、上でセーブした ke2-docker-images.gz ファイルを転送してください。

コンテナイメージのロード

ke2-docker-images.gz ファイルを転送したサーバ上で docker load コマンドを実行して、コンテナイメージをロードしてください。

$ zcat ke2-docker-images.gz | docker load

docker images コマンドでいくつかのイメージが存在していることを確認してください。

$ docker images

この環境で各構成のセットアップ手順を実施するとき、docker compose pull 手順はスキップできるようになります。

設定ガイド

ここに設定ガイドを書きます。

システム設定

環境変数

Kompira コンテナイメージに与える環境変数を設定します。

環境変数はコンテナ上の /opt/kompira/.env ファイルや、docker compose ファイル内での environment 記述など複数の指定方法があります。

環境変数の設定方法と優先順位については以下を参考にしてください。

• Set environment variables within your container's environment
• Environment variables precedence in Docker Compose

DATABASE_URL / AMQP_URL / CACHE_URL

Kompira に必要なサブシステムである、データベースやメッセージキューおよびキャッシュへの接続先を URL 形式で指定します。 デフォルト値ではそれぞれ以下のように接続します。

• データベース: 同じサーバ上の PostgreSQL に Unix ドメインソケットで接続します。
• メッセージキュー: 同じサーバ上の RabbitMQ に TCP 接続します。
• キャッシュ: 同じサーバ上の Redis に TCP 接続します。

参考: https://django-environ.readthedocs.io/en/latest/types.html#environ-env-db-url

TIMEZONE / LOCALE_LANG

各コンテナのタイムゾーンとロケールを設定します。

MAX_EXECUTOR_NUM

Kompira エンジン上で動作する Executor プロセスの最大数を指定します。 未設定の場合は kengine コンテナの CPUコア数だけ Executor プロセスを起動します。 なお、MAX_EXECUTOR_NUM を CPU コア数より多くしても、実行する Executor プロセス数は CPU コア数で抑えられます。

プロセス数＝min(CPUコア数、MAX_EXECUTOR_NUM)

また、導入されているライセンスによっても実際に動作する Executor のプロセス数は制限されます。

kompira.conf

AMQP 接続やジョブマネージャの動作に関する設定を行なう設定ファイルで、コンテナ内の /opt/kompira/kompira.conf に配置されます。 ke2-docker パッケージで KE2.0 システムを構築する場合、同パッケージの configs/ ディレクトリに含まれる kompira.conf が /opt/kompira/kompira.conf にバインドされます。

kompira.conf ファイル形式

kompira.conf は以下のようなファイル形式で、Windows における INI ファイル形式に近いものになっています。

[セクション名A]
項目名A1 = 値1
項目名A2 = 値2

[セクション名B]
項目名B1 = 値1
項目名B2 = 値2

kompira.conf セクション一覧

kompira.conf には以下のセクションがあります。

• [kompira]: Kompiraシステム関連の設定
• [logging]: ログ出力関連の設定
• [amqp-connection]: RabbitMQ の接続情報関連の設定
• [agent]: ジョブマネージャの動作に関する設定
• [event]: イベント送信の設定

kompira.conf 項目一覧

kompira.conf で設定できる項目を以下に示します。

なお、Windows 環境では以下のようにデフォルト値が変化します。

• [logging] logdir: C:\Kompira\Log

注釈: リモート接続キャッシュは、リモートコマンド実行時のリモート接続を再利用することで、同一ノード、同一アカウントでの連続するリモートコマンド実行の処理を高速化する機能です。ただし、WinRS 接続では高速化の効果が得られないため、disable_cache の設定にかかわらずリモート接続キャッシュは使用しません。

監査ログの設定 (kompira_audit.yaml)

監査ログに関する設定を行なう設定ファイルで、コンテナ内の /opt/kompira/kompira_audit.yaml に配置されます。

ke2-docker パッケージで KE2.0 システムを構築する場合、同パッケージの configs/ ディレクトリに含まれる kompira_audit.yaml が /opt/kompira/kompira_audit.yaml にバインドされます。

kompira_audit.yaml の形式

設定ファイルは kompira_audit.yaml は YAML 形式で記述します。全体としては辞書構造で、以下の設定項目が必要になります。

環境変数による記録レベル値の設定

ke2-docker パッケージでデプロイ時に環境変数 AUDIT_LOGGING_LEVEL を指定すると、その値が監査ログの記録レベル値 (logging_level) として適用されます。これは設定ファイル kompira_audit.yaml での設定より優先します。

kompira_audit.yaml の自動再読み込み

監査ログの設定ファイルをサーバー上で更新すると、次の監査ログ記録のタイミングで自動的に再読み込みされます。サービスの再起動などは不要です。

デフォルトの kompira_audit.yaml

#--------------------------------------------------------------------
# kompira_audit.yaml
#
# Configuration file to control audit log output.
#--------------------------------------------------------------------
#
# logging_level: recording level value
#
# If the calculated operation level value is less than the recording
# level value, no audit log will be recorded.
#
logging_level: 2

#
# operation_levels: basic operation level table
#
# Table of operation level reference values for each operation.
# The operation level value for an operation is the maximum of
# several operation level criteria values.
#
operation_levels:
interface:
    web: 1
    api: 1
    mng: 2
class:
    session: 3
    user: 3
    group: 3
    object: 1
    task: 1
    incident: 1
    process: 1
    schedule: 1
    packages: 1
type:
    login: 3
    logout: 3
    create: 3
    rename: 3
    copy: 3
    move: 3
    export: 3
    import: 3
    execute: 3
    suspend: 3
    resume: 3
    terminate: 3
    read: 1
    list: 1
    search: 1
    edit: 1
    confirm: 1
    update: 2
    clear: 2
    recv: 2
    send: 2
    delete: 3
permit:
    allowed: 1
    denied: 3
result:
    succeeded: 1
    failed: 1

#
# target_levels: operation level table for object operation
#
# Operation level reference value to be applied to each target
# during object manipulation.
#
target_levels:
  - {path: '/config/*', type: null, level: 2}
  - {path: '/system/*', type: '/system/types/Config', level: 2}

Kompira 画像

ブラウザ画面で表示される画像は kompira コンテナ内の以下に配置されています。

/var/opt/kompira/html/kompira/img/

ここに配置されている画像ファイルは以下の通りです。画像ファイルを直接置き換えることで、画面の見た目を変更することができます。

サイズは一般的な解像度のディスプレイで表示される時のピクセル数を参考値として示しています。

nginx 設定

nginx-default.conf

nginx のコンフィグファイル。

ホスト側で設定した nginx-default.conf を kompira-web (nginx) コンテナの /etc/nginx/conf.d/default.conf にバインドされるように docker-compose.yml の設定を行う。

ロギング設定

デフォルトのログ出力

KE2.0 はデフォルトでは以下のようなログ出力の構成になっています。

• 各コンテナのメインログは docker のコンテナログとして記録されます。
  • 【要確認】コンテナログはデフォルトでは、20MB ごと 5世代分が保持されます。
  • コンテナログの確認方法については コンテナログ管理 を参照してください。
• プロセスログおよび監査ログについては、docker の kompira_log ボリュームにファイルとして記録されます。
  • ボリュームに記録されるログの確認方法については ボリュームログ管理 を参照してください。

docker 外部でのログ記録

(WIP) fluentd などを用いて docker 外部でログを記録する設定方法について記載します。

管理ガイド

ここに運用ガイドを書きます。

データ管理

ここではデータ管理の手法について示します。

• データのエクスポート
• データのインポート
• オブジェクトのコンパイル
• チャネルオブジェクトの操作
• プロセスオブジェクト管理
• バックアップとリストア

データのエクスポート

export_data 管理コマンドによるエクスポート

export_data 管理コマンドを用いると、指定したパス配下の Kompira オブジェクトを JSON 形式でエクスポートすることができます。 KE2.0 では kompira コンテナ上で export_data 管理コマンドを実行させるために、ホスト上では以下のように実行してください。

$ docker exec $(docker ps -q -f name=kompira) manage.py export_data [options...] <オブジェクトパス>

デフォルトではエクスポートデータは標準出力に出力されるので、ファイルに書き出したい場合はリダイレクトを利用するなどしてください。

$ docker exec $(docker ps -q -f name=kompira) manage.py export_data <オブジェクトパス> > exported_data.json

export_data 管理コマンドで --zip-mode オプションを指定した場合は、エクスポートデータはコンテナ側に ZIP ファイルとして書き出されることに注意してください。 エクスポートされた ZIP ファイルをホスト側で利用するには、例えば以下のようにエクスポート後にホスト側にコピーしてください。

$ docker exec $(docker ps -q -f name=kompira) manage.py export_data --zip-mode <オブジェクトパス>
$ docker exec $(docker ps -q -f name=kompira) ls  # 出力された zip ファイル名を確認
$ docker cp $(docker ps -q -f name=kompira):/opt/kompira/<zipファイル名> .

export_data 管理コマンドのオプション

export_data 管理コマンドには以下のオプションがあります。

1. --directory オプションを指定していない場合は / がエクスポートの起点となります。
2. 所有者であるユーザオブジェクトおよびその所属グループオブジェクトが追加で出力されます。

export_dir 管理コマンドによるエクスポート

export_dir 管理コマンドを用いると、指定したパス配下の Kompira オブジェクトをオブジェクト毎に YAML ファイルとしてエクスポートすることができます。 なお、以下の型を持つオブジェクトの場合は、代表するフィールドのデータのみがファイルとして出力され、 残りのフィールドは、.<オブジェクト名> という名前の YAML ファイルとして、プロパティ情報とともに出力されます。

KE2.0 では kompira コンテナ上で export_dir 管理コマンドを実行させるために、ホスト上では以下のように実行してください。

$ docker exec $(docker ps -q -f name=kompira) manage.py export_dir [options...] <オブジェクトパス>

export_dir 管理コマンドではコンテナ上のファイルシステムにファイルを書き出すことに注意してください。 エクスポートされたデータをホスト側で利用するには、例えば以下のようにエクスポート後にホスト側にコピーしてください。

$ docker exec $(docker ps -q -f name=kompira) manage.py export_dir --current /tmp <オブジェクトパス>
$ docker exec $(docker ps -q -f name=kompira) ls /tmp/  # 出力されたディレクトリ名を確認
$ docker cp $(docker ps -q -f name=kompira):/tmp/<エクスポートされたディレクトリ名> .

ここでは、コンテナ上の /tmp ディレクトリにエクスポートしたのちに、ディレクトリ一式をホスト上の指定したディレクトリ (.) にコピーしています。

export_dir 管理コマンドのオプション

export_dir 管理コマンドには以下のオプションがあります。

1. --directory オプションを指定していない場合は / がエクスポートの起点となります。
2. LINESEP には os_linesep, lf, crlf, no_change のいずれかを指定できます。os_linesep では OS 標準の改行コードに、lf では \n に、crlf では \r\n に変換します。no_change を指定したときは改行コードを変更しません。デフォルトでは os_linesep です

注釈: --linesep は :ref:テキスト形式 <data_export> のファイルにのみ影響します。

データのインポート

import_data 管理コマンドによるインポート

import_data 管理コマンドを用いると、export_data 管理コマンドでエクスポートしたファイルからデータを取り込むことができます。 KE2.0 では kompira コンテナ上で import_data 管理コマンドを実行させるために、ホスト上からは以下のように実行してください。

$ docker exec $(docker ps -q -f name=kompira) manage.py import_data [options...] <filename>...

ホスト上にあるエクスポートデータをインポートするには、例えば以下のようにインポート前にホスト側からコピーしてください。

$ docker cp <ファイル名> $(docker ps -q -f name=kompira):/tmp/
$ docker exec $(docker ps -q -f name=kompira) manage.py import_data /tmp/<ファイル名>

ここでは、コンテナ上の /tmp ディレクトリにエクスポートデータをコピーしてから、import_data 管理コマンドでインポートしています。

import_data 管理コマンドのオプション

import_data 管理コマンドには以下のオプションがあります。

1. --directory オプションを指定していない場合は / がインポートの起点となります。
2. --overwrite-mode オプションを指定していない場合、インポートデータに既存のオブジェクトが含まれていてもインポートされずにスキップします。
3. --update-config-mode オプションを指定するときは、--overwrite-mode オプションも同時に指定する必要があります

import_dir 管理コマンドによるインポート

import_dir 管理コマンドを用いると、export_dir 管理コマンドでエクスポートしたディレクトリ一式からデータを取り込むことができます。 KE2.0 では kompira コンテナ上で import_dir 管理コマンドを実行させるために、ホスト上からは以下のように実行してください。

$ docker exec $(docker ps -q -f name=kompira) manage.py import_dir [options...] <filename>...

ホスト上にあるエクスポートデータをインポートするには、例えば以下のようにインポート前にホスト側からコピーしてください。

$ docker cp <エクスポートしたディレクトリ名> $(docker ps -q -f name=kompira):/tmp/
$ docker exec $(docker ps -q -f name=kompira) manage.py import_dir /tmp/<エクスポートしたディレクトリ名>

ここでは、コンテナ上の /tmp ディレクトリにエクスポートデータをコピーしてから、import_dir 管理コマンドでインポートしています。

import_dir 管理コマンドのオプション

import_dir 管理コマンドには以下のオプションがあります。

1. --directory オプションを指定していない場合は / がインポートの起点となります。
2. --overwrite-mode オプションを指定していない場合、インポートデータに既存のオブジェクトが含まれていてもインポートされずにスキップします。
3. --update-config-mode オプションを指定するときは、--overwrite-mode オプションも同時に指定する必要があります
4. LINESEP には os_linesep, lf, crlf, no_change のいずれかを指定できます。os_linesep では OS 標準の改行コードに、lf では \n に、crlf では \r\n に変換します。no_change を指定したときは改行コードを変更しません。デフォルトでは crlf です。

注釈: --linesep は :ref:テキスト形式 <data_export> のファイルにのみ影響します。

オブジェクトのコンパイル

ジョブフローオブジェクトのコンパイル

以下のコマンドを実行する。

$ docker exec $(docker ps -q -f name=kompira) manage.py compile_jobflow [options...] <ジョブフロ―オブジェクトのパス>

オプションの詳細については、従来と同様 --help オプションで表示される。

ライブラリオブジェクトのコンパイル

以下のコマンドを実行する。

$ docker exec $(docker ps -q -f name=kompira) manage.py compile_library [options...] <ライブラリオブジェクトのパス>

オプションの詳細については、従来と同様 --help オプションで表示される。

チャネルオブジェクトの操作

チャネルオブジェクトのメッセージを見る

以下のコマンドを実行する。

$ docker exec $(docker ps -q -f name=kompira) manage.py peek_channel [options...] <チャネルオブジェクトのパス>

オプションの詳細については、従来と同様 --help オプションで表示される。

チャネルオブジェクトからメッセージを取り出す

以下のコマンドを実行する。

$ docker exec $(docker ps -q -f name=kompira) manage.py pop_channel [options...] <チャネルオブジェクトのパス>

オプションの詳細については、従来と同様 --help オプションで表示される。

プロセスオブジェクト管理

manage.py process 管理コマンドを用いて、Kompira プロセスオブジェクトに対して以下のような操作を行なうことができます。

• プロセスの一覧表示
• プロセスの個数表示
• プロセスの削除
• プロセスの中止
• プロセスの停止
• プロセスの続行

このとき、操作の対象とするプロセスを絞り込む条件を指定することができます。

• プロセスの状態
• 実行しているジョブフロー
• スケジュール起動のプロセスかどうか
• 起動オブジェクトが指定されたプロセスかどうか
• 実行したユーザ
• 開始日時および終了日時
• 実行時間
• コンソール出力に含まれる文字列

process 管理コマンドの実行

process 管理コマンドは以下のように kompira コンテナで実行してください。

$ docker exec $(docker ps -q -f name=kompira) manage.py process [options...]

プロセス操作オプション

Kompira プロセスに対して行う操作を指定するオプションを以下に示します。

操作を指定するオプションはいずれか1つのみ指定可能で、複数指定した場合は最後のオプションが適用されます。 上記のいずれも指定しなかった場合は、プロセスの一覧表示を行ないます。

大量のプロセスが処理対象となるような場合に、メモリや CPU などのリソース負荷が大きくなる場合がありますのでご注意ください。

プロセス情報の変更を伴う操作（削除、中止、停止、続行）が指定された場合は、実際に制御を適用するかの確認（yes/no の入力）が行なわれます。 制御前の確認を行なわずに適用したい場合は -y オプションを指定してください。制御を適用せずに動作を確認したい場合は --dry-run オプションを指定してください。

プロセス絞り込みオプション

操作対象とする Kompira プロセスを絞り込む条件を指定するオプションを以下に示します。

• 複数指定可能な絞り込みオプションを複数回指定した場合は、それらを OR 条件として絞り込みます。
• 異なる種類の絞り込みオプションを複数指定した場合は、それらを AND 条件として絞り込みます。
• オプションの日時はジョブフローの datetime() 組み込み関数が認識できる形式で指定できます。

その他のオプション

バックアップとリストア

【1.6】バックアップ

Kompiraの全てのデータをバックアップするための手順について説明します。

Kompiraはデータベース上以外に、サーバ上の :ref:file_hierarchy に挙げられているパスのデータを使用します。 Kompiraのデータをバックアップする際は、export_dataコマンドによるKompiraオブジェクトのバックアップに 加えて、必要に応じてサーバ上のファイルバックアップも行う必要があります。

Kompiraオブジェクトとライセンスファイルのバックアップを行う場合の例を以下に示します。

$ mkdir -p /tmp/kompira_backup
$ cd /tmp/kompira_backup
$ /opt/kompira/bin/manage.py export_data / --virtual-mode > backup.json
$ cp /var/opt/kompira/kompira.lic ./
$ cd /tmp
$ tar zcf kompira_backup.tar.gz ./kompira_backup

アカウント管理

ここではアカウント管理について示します。

• アカウントロックの解除

アカウントロック

アカウントがロックされるとロックされたユーザの情報表示画面の下部に警告メッセージとともにアクセス元のIPアドレスの一覧が表示されます。 ユーザの情報表示画面に表示されるロック解除ボタンを押すことで、当該ユーザのアカウントロックを解除することができます。

また、管理コマンドを用いることで履歴の確認やロックの解除を行なうこともできます。

アカウントロックの履歴表示

axes_list_attempts 管理コマンドを実行するとログインに失敗した履歴の一覧が表示されます。

docker exec $(docker ps -q -f name=kompira) manage.py axes_list_attempts

なお、ロックを解除すると該当する履歴は削除されます。

アカウントロックの解除

以下の管理コマンドを実行してロック解除することができます。

axes_reset 管理コマンドで全てのアカウントロックを一斉に削除します。

docker exec $(docker ps -q -f name=kompira) manage.py axes_reset

axes_reset_ip 管理コマンドは指定した IP アドレスからのアカウントロックを解除します。

docker exec $(docker ps -q -f name=kompira) manage.py axes_reset_ip [ip ...]

axes_reset_username 管理コマンドは指定したユーザのアカウントロックを解除します。

docker exec $(docker ps -q -f name=kompira) manage.py axes_reset_username [username ...]

ログ管理

コンテナログ管理

各コンテナのメインのログは docker 標準のロギング機構によって、コンテナごとにホスト上のボリューム内に記録されます。

動作中コンテナのログの確認

docker により記録されているコンテナごとのログは docker logs コマンドで確認することができます。 たとえば動作中の kengine コンテナのログは以下のようにコマンドを実行するとコンソールに表示されます。

$ docker logs $(docker ps -q -f name=kengine) 

コンテナの標準出力と標準エラー出力はそれぞれ記録されていて、docker logs コマンドではその出力が再現されます。 less コマンドなどで両方のログ出力を確認したい場合は、標準エラー出力を標準出力にリダイレクトして出力させると確認しやすくなります。

$ docker logs $(docker ps -q -f name=kengine) 2>&1 | less -RS

停止中コンテナのログの確認

停止中のコンテナのログを確認したい場合は、docker ps コマンドではコンテナ ID が取得できないので、別の手法を用いる必要があります。

別の方法としては例えば docker container ls -a コマンドで、停止中のコンテナも含めてその一覧を得る方法があります。

$ docker container ls -a -f name=kengine
CONTAINER ID   IMAGE                                 COMMAND                   CREATED         STATUS                          PORTS     NAMES
31fc2ccc0c5f   kompira-enterprise:2.0.0b1_31f7c1f2   "docker-entrypoint.s…"   2 minutes ago   Exited (0) About a minute ago             ke2-kengine-1

これを利用すれば停止中のコンテナのログを確認することもできます。

$ docker logs $(docker container ls -a -q -f name=kengine)

なお、コンテナが削除されるとログも削除されて確認できなくなるので注意してください。 コンテナの状態に関わらずログを確認できるようにしたい場合は、ログを docker 外部で記録することを検討してください。

コンテナログの一括取得

すべてのコンテナの最近の一定期間分のログを取得してファイルに書き出したいという場合は、例えば以下のように docker container コマンドの結果をもとにコンテナごとに docker logs コマンドでログを取得してファイルに出力してください。

$ docker container ls -a --format '{{.ID}} {{.Names}}' | while read id name; do docker logs --since "24h" --timestamps $id 2>&1 | gzip > "${name%.*}-${id}.log.gz"; done

この例では docker container ls コマンドに -a オプションを付けることで停止中のコンテナも対象にしています。また、docker logs コマンドに --since オプションで最近 24 時間分のログを取得対象にしているのと、--timestamps オプションでタイムスタンプを出力するようにしています。取得したログは gzip コマンドで圧縮して、{コンテナ名}-{ID}.log.gz というファイル名で書き出しています。

これを実行すると、例えば以下のように複数の圧縮ログファイルが得られます。

$ ls -l *.log.gz
-rw-r--r--. 1 root root   887 Aug  1 10:22 ke2_jobmngrd.2-34f59028949c.log.gz
-rw-r--r--. 1 root root  1558 Aug  1 10:22 ke2_kengine.2-188b800bdd72.log.gz
-rw-r--r--. 1 root root  1554 Aug  1 10:22 ke2_kengine.2-d84d727936cf.log.gz
-rw-r--r--. 1 root root  1561 Aug  1 10:22 ke2_kengine.2-eb46166069dc.log.gz
-rw-r--r--. 1 root root  1770 Aug  1 10:22 ke2_kengine.2-f5e6171597bd.log.gz
-rw-r--r--. 1 root root  1555 Aug  1 10:22 ke2_kengine.2-f7af3854014b.log.gz
-rw-r--r--. 1 root root 10798 Aug  1 10:22 ke2_kompira.1-01971df8db91.log.gz
-rw-r--r--. 1 root root  3655 Aug  1 10:22 ke2_nginx.1-6b9aa454d7d6.log.gz
-rw-r--r--. 1 root root  7815 Aug  1 10:22 ke2_rabbitmq.1-2704436f57df.log.gz

※ コンテナ名の部分はシステム構成によって変わります。また、kompira 以外のコンテナを動作させている場合は、そのログも出力されることに注意してください。

ボリュームログ管理

docker はボリュームという機能でホストとコンテナ間でファイルを共有することができます。 KE2.0 ではこれを利用して、一部のコンテナでログをボリュームに記録している場合があります。

プロセスログおよび監査ログの記録場所

シングル構成ではプロセスログおよび監査ログは docker の kompira_log ボリュームに記録されます。

docker ボリュームがホスト上のどこに配置されているかは、docker volume ls コマンドで知ることができます。 例えば以下のようにコマンドを実行することで kompira_log のサーバ上での場所が分かります。

$ docker volume ls -f name=kompira_log --format="{{.Mountpoint}}"
/var/lib/docker/volumes/ke2_kompira_log/_data

docker volume コマンドで表示されたディレクトリを確認すると、プロセスログおよび監査ログが記録されているはずです。

$ sudo ls -l /var/lib/docker/volumes/ke2_kompira_log/_data
合計 4
-rw-r--r--. 1 root root    0  7月 24 11:44 audit-ap-ke2-server1.log
-rw-r--r--. 1 root root 3668  7月 24 11:44 audit-ke-ke2-server1.log
-rw-r--r--. 1 root root    0  7月 24 11:44 process-ke-ke2-server1-0.log
-rw-r--r--. 1 root root    0  7月 24 11:44 process-ke-ke2-server1-1.log

ただし、デプロイ時に環境変数 KOMPIRA_LOG_DIR でログの出力先を指定している場合は、kompira_log ボリュームではなく指定したディレクトリに記録されます。

また、Swarm クラスタ構成では setup_stack.sh 実行時に指定した共有ディレクトリ (SHARED_DIR) 配下の $SHARED_DIR/log がデフォルトの KOMPIRA_LOG_DIR となり、そこにログが記録されます。

プロセスログ管理

ジョブフロー実行時のプロセスログは、kengine コンテナが直接ログファイルとして記録を行なっています。

プロセスログは Docker のデフォルトでは kompira_log ボリュームに記録されます。 または、デプロイ時に環境変数 KOMPIRA_LOG_DIR が指定されていれば、ホスト上のそのディレクトリに記録されます。

作成されるログファイル名は以下のようになります。

proces-${CONTAINERNAME}-${EXECUTORID}.log

• ${CONTAINERNAME} の部分はログを記録するコンテナの名称に展開されます。
• ${EXECUTORID} の部分は kengine 内部で動作しているエグゼキュータの ID に展開されます。

kompira_log ボリュームに記録されたプロセスログファイルの確認方法については、ボリュームログ管理 を参照してください。

監査ログ管理

ユーザが Kompira に対して各種操作をしたときに、その操作の種類や、認可されたかどうか、また成功したかどうか、といった情報をログに記録します。

実際に記録される監査ログファイルの仕様については 監査ログファイル を参照してください。

監査ログの対象となる操作

ブラウザでの操作や API を用いた連携操作、サーバ上の管理コマンドによる操作などが監査ログの記録対象となります。

一方で、以下については、監査ログの記録対象となりません。

• ジョブフロー動作によるデータ操作やプロセス操作
• Kompira システム外部での操作（DB管理コマンドを用いた直接的なデータ操作など）
• static コンテンツへのアクセス

操作レベルと記録レベル

ある記録対象の操作が監査ログに実際に記録されるかどうかは、その操作の種類や結果から算出される「操作レベル値」と、設定項目である「記録レベル値」によって決まります。算出された操作レベル値が設定項目の記録レベル値以上のとき、監査ログに当該エントリが出力されます。

監査ログの記録条件： 操作レベル値 ≧ 記録レベル値

操作レベル値は操作における複数の項目から算出します。いくつかの項目ごとに設定された操作レベルの基準値が決まり、その最大値が最終的な操作レベル値となります。通常この値は 1 から 3 の間の数値となります。各項目の操作レベル基準値のデフォルトについては 監査ログの項目詳細 を参照してください。

たとえば、「ブラウザ上で既存のジョブフローオブジェクトを編集した（許可され、成功した）」という場合、以下のような項目ごとの操作レベル基準値が適用されて、最終的な操作レベル値は 2 となります。

記録レベル値のデフォルトは 2 です。詳細については 監査ログの設定 を参照してください。

監査ログファイル

ここでは監査ログファイルの仕様について示します。

監査ログの記録先

ke2-docker パッケージで KE2.0 システムを構築する場合、監査ログファイルは Docker の kompira_log ボリュームに記録されます。 または、デプロイ時に環境変数 KOMPIRA_LOG_DIR が指定されていれば、ホスト上のそのディレクトリに記録されます。

作成されるログファイル名は以下のようになります。

audit-${CONTAINERNAME}.log

• ${CONTAINERNAME} の部分はログを記録するコンテナの名称に展開されます。

kompira_log ボリュームに記録された監査ログファイルの確認方法については、ボリュームログ管理 を参照してください。

監査ログのファイル形式

監査ログは UTF-8 でエンコードされたテキストファイルで、1エントリを1行の JSON 形式で出力します。

監査ログの記録項目

監査ログのサンプル

以下にブラウザで操作したときの監査ログファイル /var/log/kompira/audit-apache.log のサンプルを示します。ログは1エントリ1行で出力されていますが、ここでは分かりやすく整形して表示しています。

{
    "level": 3,
    "started": "2021-10-05T15:51:31.403016+09:00",
    "finished": "2021-10-05T15:51:31.452097+09:00",
    "exec": {
    "pid": 1286192,
    "name": "/usr/sbin/httpd",
    "user": "apache",
    "remote": "10.10.0.110"
    },
    "user": "root",
    "interface": "web",
    "class": "session",
    "target_path": null,
    "target_type": null,
    "type": "login",
    "permit": "allowed",
    "result": "succeeded",
    "reason": null,
    "detail": {
    "next_page": "/"
    }
}
{
    "level": 2,
    "started": "2021-10-05T15:51:43.447941+09:00",
    "finished": "2021-10-05T15:51:43.486984+09:00",
    "exec": {
    "pid": 1285426,
    "name": "/usr/sbin/httpd",
    "user": "apache",
    "remote": "10.10.0.110"
    },
    "user": "root",
    "interface": "web",
    "class": "object",
    "target_path": "/config/license",
    "target_type": "/system/types/License",
    "type": "read",
    "permit": "allowed",
    "result": "succeeded",
    "reason": null,
    "detail": {
    "http_method": "GET",
    "http_status": 200
    }
}

監査ログの項目詳細

ここでは、監査ログに記録される項目についての詳細を示します。 以下の節におけるテーブルで「操作レベル」は、操作レベル基準値のデフォルトを示しています。

操作レベル (level)

操作の内容や結果によって算出された操作レベルを数値で示します。この操作レベル値が設定項目の記録レベル値以上のとき、監査ログに当該エントリが出力されます。

操作日時 (started, finished)

項目 started は操作の開始日時を、項目 finished は操作の終了日時を示します。 これらは以下のように、ローカルタイムで ISO8601 形式で記録されます。

"2021-10-01T11:45:08.977356+09:00"

操作元情報 (exec)

操作元を示す辞書には以下のような情報が記録されます。

操作ユーザ (user)

操作を行った Kompira ユーザ名を記録します。ブラウザ上で Kompira にログインして操作をした場合は、そのログインユーザ名となります。サーバのコンソール上で管理コマンドによる操作を行なった場合などでは、Kompira の認証を伴っていないため空文字列になります。

操作方式 (interface)

どのような方式を用いて操作したのかの区分を記録します。

操作分類 (class)

何を操作したのか、その分類を示します。

操作対象 (target_path, target_type)

何を操作したのか、その具体的な対象を示します。

操作分類が session 以外のときは、操作対象をそのパスで識別することができます。以下のようにパスを項目 target_path として記録します。

"/system/user/id_1"

さらに、オブジェクト操作の場合では、その型オブジェクトのパスを項目 target_type に記録します。

"/system/types/Directory"

操作種別 (type)

どのような操作をしたのかという種類を記録します。

いくつかの操作種別は特定の操作分類でのみ利用されます。たとえばログインやログアウトは操作分類が session のときだけです。

ある操作種別が複数の操作分類で利用される場合はありますが、操作分類ごとに異なる操作レベル基準値を設定することはできません。

操作の結果 (permit, result)

操作の結果としてその認否と成否が記録されます。

項目 permit は操作が許可されたかどうかを示します。例えばオブジェクト操作では設定されたパーミッションによって、操作が許可されたり拒否されたりします。

項目 result は操作に成功したかどうかを示します。

詳細情報 (detail)

操作ごとに追加の詳細情報を辞書形式で記録します。

※ 詳細情報については、監査ログ機能がリリースされた後も仕様が調整される可能性がありますのでご注意ください。

ログイン

REST-API

エクスポート

インポート

オブジェクトの検索

オブジェクトの新規作成

ジョブフローやスクリプトジョブの実行

オブジェクトの名称変更

オブジェクトのコピー

オブジェクトの移動

オブジェクトの削除

チャネルへのメッセージ送信

管理コマンド: compile_jobflow / compile_library

管理コマンド: license_info / license_update

管理コマンド: process

その他の詳細情報

セキュリティ管理

• SSL証明書の管理
• 暗号化秘密鍵の管理

SSL 証明書管理

KE 2.0 システムでは HTTPS 接続および AMQPS 接続を行なうために、SSL 証明書が必要になります。 ke2-docker パッケージのデプロイ手順では、自己署名 SSL 証明書を作成しています。

SSL 証明書ファイルの作成

ke2-docker パッケージに付属の create-cert.sh スクリプトを実行すると、ssl ディレクトリに以下のファイルが生成されます。

• local-ca.crt: 作成する SSL 証明書に署名する CA 証明書
• local-ca.key: local-ca.crt の秘密鍵ファイル
• local-ca.srl: local-ca.crt で発行済みシリアル番号を保存するファイル
• server.crt: nginx/rabbitmq コンテナが利用するサーバ SSL 証明書（local-ca.crt によって署名されています）
• server.csr: server.crt を生成する時の CSR ファイル
• server.ext: server.crt に設定する拡張情報ファイル
• server.key: server.crt の秘密鍵ファイル

サーバ証明書 server.crt には create-cert.sh スクリプトを実行したホストのホスト名を元にサブジェクトが設定されます。

各コンテナでの SSL 証明書の適用

ke2-docker でデプロイした各コンテナでは、作成した SSL 証明書を適用するための設定を行なっています。

nginx コンテナ

nginx コンテナでは、SSL 証明書を利用した HTTPS 接続ができるように、以下のような設定を行なっています。

• SSL証明書ファイル一式を nginx コンテナの /etc/nginx/ssl ディレクトリにバインドするようにしています。
• /etc/nginx/ssl に配置された SSL 証明書を利用するように、ke2-docker 付属の nginx.conf で設定しています。

rabbitmq コンテナ

rabbitmq コンテナでは、SSL 証明書を利用した AMQPS 接続ができるように、以下のような設定を行なっています。

• SSL証明書ファイル一式を rabbitmq コンテナの /etc/rabbitmq/ssl ディレクトリにコピーするようにしています。
• /etc/rabbitmq/ssl に配置された SSL 証明書を利用するように、ke2-docker 付属の rabbitmq-ssl.conf で設定しています。
• rabbitmq-server で SSL 証明書による認証ができるように rabbitmq_auth_mechanism_ssl プラグインを有効化しています。

正式な SSL 証明書の適用方法

(WIP)

暗号化秘密鍵の管理

秘密鍵の変更

パスワードフィールドの暗号化に使用する秘密鍵を変更するには、change_secretkey コマンドを root 権限で実行します。 実行するとデータベースに暗号化されて保存されている全てのパスワードデータを新しい秘密鍵で再暗号化して保存し直します。

change_secretkey は以下の形式です。

$ docker exec $(docker ps -q -f name=kompira) manage.py change_secretkey [options...] <new_secretkey>

変更後のサービス再起動

変更後は、以下の手順にて kompira, kengine サービスを再起動する。

$ docker restart $(docker ps -q -f name=kompira)
$ docker restart $(docker ps -q -f name=kengine)

【確認】: swarm 環境での手順

【v1.6】: change_secretkey を実行後は、httpd サービスと kompirad サービスをリスタートしてください。 冗長構成の場合は、アクティブ側で change_secretkey を実行した後で、スタンバイ側への切り替えを行ってください。

change_secretkey コマンドのオプション

change_secretkey 管理コマンドには以下のオプションがあります。

注釈: 秘密鍵の文字列は /var/opt/kompira/.secret_key に保存されています。

システムパッケージ管理

Kompira 環境にインストールされている Python や Web 用のパッケージの情報が以下で閲覧できます。 各パッケージ種別ごとにインストールされているパッケージのバージョンやライセンスに関する情報を確認することができます。

注釈: システムパッケージ情報は Kompira をインストールまたはアップデートした後に kompirad が起動したタイミングで自動的に収集および更新されます。

パッケージ情報の管理

Kompira サーバ上で以下のコマンドを利用することでパッケージ情報を管理することができます。

$ docker exec $(docker ps -q -f name=kompira) manage.py packages_info [options...]

パッケージ情報の表示

オプションを省略または --show オプションを指定した場合、すでに収集されているパッケージ情報をコンソールに一覧表示します。

$ docker exec $(docker ps -q -f name=kompira) manage.py packages_info --show

パッケージ情報の一覧表示の例を以下に示します。

+------+----------------------+-----------+----------+-----------------+
| Type | Name                 | Installed | Latest   | License         |
+------+----------------------+-----------+----------+-----------------+
| pip  | AMQPStorm            | 2.10.8    | None     | MIT License     |
| pip  | APScheduler          | 3.10.4    | None     | MIT License     |
| pip  | Creoleparser         | 0.7.5     | None     | MIT License     |
| pip  | Django               | 4.2.14    | 5.0.7    | BSD License     |
| pip  | Genshi               | 0.7.9     | None     | BSD License     |
| pip  | GitPython            | 3.1.43    | None     | BSD License     |
| pip  | Jinja2               | 3.1.4     | None     | BSD License     |
    :         :                    :           :            :

パッケージ情報の収集

--collect オプションを指定した場合、インストールされているパッケージ情報を収集します。

$ docker exec $(docker ps -q -f name=kompira) manage.py packages_info --collect

このとき、各パッケージの最新バージョン情報を収集するためにインターネット接続が必要になります。 プロキシ接続が必要な場合は --proxy オプション（または https_proxy 環境変数）で指定してください。

インターネットに接続できないなど、最新バージョン情報の収集を行わない場合は --no-collect-latest オプションを追加で指定してください。 あるいは、明示的に最新バージョン情報の収集を行なうことを指定したい場合は --collect-latest オプションを追加で指定してください。

注釈: なお、収集されたパッケージ情報はコンテナ上の /var/opt/kompira/packages/ 配下に保存されます。

パッケージ情報の更新

--update オプションを指定した場合、収集済みパッケージ情報をもとに Kompira 上のシステムパッケージ情報オブジェクト（Wiki 型）を更新します。

$ docker exec $(docker ps -q -f name=kompira) manage.py packages_info --update

--update オプションと --collect オプションを併用した場合は、パッケージ情報の収集に続けてシステムパッケージ情報オブジェクトの更新を行ないます。

Python パッケージ管理

Python パッケージ (pip)のインストール先

KE2.0 では Python パッケージの参照先が、各コンテナで個別な場所と kompira および kengine コンテナ間で共有する場所があります。

• コンテナ個別: /usr/local/lib/python3.11/site-packages/
• コンテナ共有: /var/opt/kompira/lib/python3.11/site-packages/

ユーザーが作成するライブラリオブジェクトから参照する Python パッケージを追加する場合は、コンテナ共有な場所に配置する必要があります。 kompira コンテナの pip コマンドでインストールすると、デフォルトでコンテナ共有な場所にインストールするように構成しています。

docker exec $(docker ps -q -f name=kompira) pip install some-package

コンテナ共有ディレクトリは、kompira と kengine コンテナの両方から共有されているボリューム上にあるため、同じパッケージを両コンテナにインストールする必要はありません。

KE2.0 コンテナイメージでは、あらかじめ /usr/local/lib/python3.11/site-packages/.pth ファイルを作成してあり、そのファイルで上記パスを参照するように指定しています。

保守ガイド

ここに保守ガイドを書きます。

シングル構成の保守

以後の節では、シングル構成を保守する手順などについて示します。

各手順では共通的な準備やオプションの指定方法がありますので、以下を参考にしてください。

docker compose ファイルの指定

以後の説明ではシステム構築に用いた docker-compose.yml ファイルがあるディレクトリで docker compose コマンドを実行する前提になっています。 別のディレクトリで docker compose コマンドを実行する場合、または docker-compose.yml 以外の docker compose ファイルでシステムを構築している場合は、各 docker compose コマンドに -f <docker compose ファイル> オプションを付けて実行するようにしてください。

例:

$ docker compose -f /foo/bar/docker-compose-custom.yml start

システムの起動

シングル構成の起動および停止の手順について示します。

システムの起動手順

システム構築に用いた docker-compose.yml ファイルがあるディレクトリで、以下のコマンドを実行します。

$ docker compose start

なお、初回起動時には docker compose start ではなく docker compose up -d コマンドを実行しますが、これは各構成の構築手順で実施済みである前提です。

また、docker-compose.yml に restart: always という設定がある場合は、サーバ起動時に自動起動するようになっています。

システムの停止

シングル構成の停止の手順について示します。

システムの停止手順

システム構築に用いた docker-compose.yml ファイルがあるディレクトリで、以下のコマンドを実行します。

$ docker compose stop

システムの削除

シングル構成のシステムを削除する手順について示します。

コンテナの削除

以下のコマンドを実行すると、システムが停止するとともにすべてのコンテナが削除されます。

$ docker compose down

この状態ではデータ領域となるボリュームは残っていますので、再び docker compose up -d コマンドでシステムを開始すると、以前のデータにアクセスすることができます。

コンテナとボリュームの削除

以下のように -v オプションを指定して down した場合は、コンテナだけでなくボリュームも削除されます。

$ docker compose down -v

この場合は、以前のデータにアクセスすることは出来なくなりますので注意してください。

クラスタ構成の保守

以後の節では、クラスタ構成を保守する手順などについて示します。

システムの削除

クラスタ構成のシステムを削除する手順について示します。

Swarm クラスタ構成の削除手順

Swarm クラスタのいずれかのマネージャーノード上（以下の例では ke2-server1）で以下のコマンドを実行してください。

[ke2-server1]$ docker stack rm ke2

クラスタで動作している全てのサービスを停止して、コンテナやボリュームが削除されます。