はじめに

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

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

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

最終更新日: 2024/10/29

改版履歴

2024/10/16 (2.0.2)

コンテナイメージ

• KOMPIRA_IMAGE_TAG=2.0.2 に対応しました。

変更

• 暗号化秘密鍵の手順を更新しました。
• システム管理/システムステータスの確認を追加しました。
• クラスタ構成のアップデート手順を更新しました。
• クラスタ構成の保守ガイドを追加しました。
• ke2-docker に合わせて環境変数の説明を更新しました。
• 環境変数によるロギング設定について追記しました。
• pip install するときの kompira-sendevt のバージョン指定を更新しました。
• docker-compose-plugin について v2.24.6 以上が必要であることをシステム要件に追記しました。

2024/08/01 (2.0.0)

• KE2.0.0 リリース

用語

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

ライセンス

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

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

システム概要

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

システム要件

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

ホストのシステム要件

• 必要なスペックは Kompira 上で動作するジョブフロー規模、自動化の処理要件によって異なります。
• 記載要件は最低レベルで記載しております。お客様の運用環境によっては異なる場合がございますのでご了承ください。

動作確認済みホスト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) の基本的なアップデート手順を示します。

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

ここでは GlusterFS や Pgpool-II/PostgreSQL のアップデートについては対象外としています。

注意事項

クラスタ構成を部分的に順次アップデートしていくローリングアップデートには対応していません。 システム全体を停止させてアップデートを行なう手順をとるため、アップデート作業中はサービス停止状態になりますのでご注意ください。

また、実行中のジョブフロープロセスが存在すると強制的に異常終了となります。 可能であれば、すべてのジョブフロープロセスを適切に停止させてから、アップデート手順を実施することをお勧めします。

クラスタシステムの削除

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

[ke2-server1]$ docker stack rm ke2
Removing service ke2_jobmngrd
Removing service ke2_kengine
Removing service ke2_kompira
Removing service ke2_nginx
Removing service ke2_rabbitmq
Removing service ke2_redis
Removing config swarm_rabbitmq-config-cluster
Removing config swarm_kompira-config
Removing config swarm_rabbitmq-config-auth
Removing config swarm_kompira-audit
Removing config swarm_rabbitmq-config-ssl
Removing config swarm_bootstrap-rabbitmq
Removing config swarm_nginx-config
Removing network swarm_default

このコマンドを実行すると、クラスタで動作している全てのコンテナが停止して、クラスタスタックと構成サービスの定義などが削除されます。

この時点で、ノードの再起動や docker サービスの再起動を行なっても Kompira サービスは起動しない状態になっています。そのため以後の手順に進む前に、GlusterFS や Pgpool-II/PostgreSQL など Kompira 以外のミドルウェアのアップデートを実施することも可能です。ただし、その場合は、次の手順に進む前に、手を加えたシステム・ミドルウェアなどが再び正常に動作していることを確認するようにしてください。

ke2-docker パッケージの更新

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

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

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

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

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

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

クラスタ構成の再セットアップ

ke2-docker パッケージにアップデート/変更点がなかった場合は、この手順はスキップすることができます。

ke2-docker にアップデートがある場合、セットアップ手順 を注意深く確認してください。

• セットアップ手順の「Swarm クラスタの開始」の一つ手前の手順までを、必要に応じて実施してください。
• すでに同じ内容で実施済みの手順についてはスキップすることができます。
  • 例えば「共有ディレクトリの作成」という手順の場合、作成すべきディレクトリ構成が同じであり、すでに作成済みであればスキップできます。
• ただし「アップデート時の注意点」といった記述がある場合は、それに従ってください。

※ docker-swarm.yml を生成しなおしていてカスタマイズが必要な場合は、この段階で改めてカスタマイズを適用してください。

Swarm クラスタの開始

以前生成した／または新たに生成した docker-swarm.yml ファイルを指定して、Swarm クラスタを開始してください。

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

問題なければ、アップデートした Kompira が起動しているはずです。

クラウド構成

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

外部連携構成

いずれかの構成でセットアップした 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

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

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

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

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

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

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

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

オフライン環境での構築

インターネットに接続できない環境で 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 の動作環境を指定することが出来ます。 以下では各構成で共通的な環境変数について示します。 各構成で独自の環境変数が定義されている場合もありますので、それぞれの説明を参照してください。

HOSTNAME

デプロイする各コンテナには、ホストサーバのホスト名をベースにしたホスト名を内部的に付与するようにしています。 そのため、デプロイ時にホストサーバのホスト名を環境変数 HOSTNAME で参照しています。

環境変数 HOSTNAME でホストサーバのホスト名を参照できない環境の場合は、デプロイ前に環境変数 HOSTNAME を設定するようにしてください。

KOMPIRA_IMAGE_NAME / KOMPIRA_IMAGE_TAG

デプロイする Kompira コンテナのイメージとタグを指定します。 独自に用意したコンテナイメージや、特定のバージョンのコンテナイメージを利用したい場合にこの環境変数で指定することができます。

KOMPIRA_IMAGE_TAG のデフォルト値は ke2-docker 更新時点で公開されていた最新の kompira コンテナイメージを示しています（例えば "2.0.2" など）。KOMPIRA_IMAGE_TAG に "latest" と指定すると、デプロイ時に公開されている最新の kompira コンテナイメージを利用することができます。

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

TZ / LANGUAGE_CODE

各コンテナのタイムゾーンと言語コードを設定します。

• タイムゾーンは、画面やログで表示される時刻のタイムゾーンの指定になります。
• 言語コードは "ja" (日本語) または "en" (英語) が指定できます。この値は、初回起動時にインポートする初期データの言語の指定になります。

MAX_EXECUTOR_NUM

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

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

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

LOGGING_XXX / AUDIT_LOGGING_XXX

Kompira コンテナイメージにおけるプロセスログおよび監査ログの設定について指定します。

• LOGGING_LEVEL: プロセスログの記録レベルを指定します。
  • デフォルトは "INFO" です。
• AUDIT_LOGGING_LEVEL: 監査ログの記録レベルを指定します。
  • デフォルトは 2 です。
• LOGGING_DIR / AUDIT_LOGGING_DIR: ログの出力先ディレクトリを指定します。
  • デフォルトは "/var/log/kompira" です。標準的なデプロイ手順ではこのディレクトリはホストの kompira_log ボリュームにマウントされます。
• LOGGING_BACKUP: ログローテート時に保存されるバックアップ数を指定します。
  • LOGGING_BACKUP のデフォルトは 7 です。
  • AUDIT_LOGGING_BACKUP のデフォルトは 365 です。
• LOGGING_WHEN / AUDIT_LOGGING_WHEN: ログローテートのタイミングを指定します。デフォルトは "MIDNIGHT" です。
• LOGGING_INTERVAL / AUDIT_LOGGING_INTERVAL: ログローテートのインターバルを指定します。デフォルトは 1 です。

ログのローテーションは LOGGING_WHEN および LOGGING_INTERVAL の積に基づいて行います。 LOGGING_WHEN は LOGGING_INTERVAL の単位を指定するために使います。使える値は下表の通りです。大小文字の区別は行いません。

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 外部でログを記録する設定方法について記載します。

管理ガイド

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

管理コマンド

運用ガイドの説明において管理コマンド manage.py を実行する場面がたびたび登場します。 KE2.0 では基本的に manage.py は kompira コンテナ内部で実行する必要があるため、動作中の kompira コンテナのコンテナ ID を知る必要があります。

なお、docker コマンドはコンテナ ID でなくコンテナ名を指定して実行することもできますが、構成によってコンテナ名が変わるため本マニュアルではコンテナ ID を指定して実行する手順で説明を共通化しています。

コンテナID とコンテナ名

コンテナ ID とコンテナ名は例えば以下のように docker ps コマンドで確認できます。

$ docker ps --format "{{.ID}} {{.Names}}"
aa5314b683e1 ke2-nginx-1
38dac7c77f60 ke2-kompira-1
a5caf7bd1ab6 ke2-kengine-1
dcadb5893a30 ke2-jobmngrd-1
bbdf0ed2bf9f ke2-postgres-1
2825a9737c12 ke2-rabbitmq-1
865c495d50b6 ke2-redis-1

上の結果では ke2-kompira-1 が該当して、コンテナ ID が 38dac7c77f60 であることが分かります。

kompira コンテナの実際のコンテナ名はシステム構成や構築した手順によって変わりますが、以下のように docker ps コマンドを使って名前に "kompira" という文字列を含むコンテナのコンテナIDを知ることができます。

$ docker ps -q -f name=kompira
38dac7c77f60

この手法を用いて、kompira コンテナ内部で manage.py コマンドを実行したい場合は以下のように行ないます。

$ docker exec $(docker ps -q -f name=kompira) manage.py <subcommand> ...

クラスタ構成での管理コマンドの実行

【要確認】 クラスタ構成の場合は、どのノード上で管理コマンドを実行するべきかという疑問が生じますが、対象とするコンテナが正常に動作しているノードであればどこで実行しても問題ありません。

ライセンス管理

KE2.0 におけるライセンス管理について示します。

ライセンス情報

Kompira のライセンス情報にはいくつかのフィールドが含まれています。 ライセンス管理画面で確認できる項目の一覧を以下に示します。

ここの「システムID」がライセンスを管理する上でのシステム固有IDとなっており、ライセンス申請する際に必要な情報となります。 また発行されたライセンスファイルにもシステムIDが含まれており、システムIDが一致していないとライセンスを更新することができません。

KE2.0 のライセンス情報では、v1.6 までのライセンス情報から以下の変更があります。

• ライセンス管理がノード単位からシステム単位に変更になり、ライセンス対象を特定する情報が「ノードID」から「システムID」に変更になりました。
• ジョブフローの並列実行が可能になり、「エグゼキュータ数」フィールドが追加になりました。

ライセンスの管理

ライセンスの確認、申請、および更新の手順については以下のページを参照してください。

• ライセンスの確認
• ライセンスの申請
• ライセンスの更新

ライセンスの確認

ブラウザまたは管理コマンドでライセンスの確認を行なうことができます。

ライセンス管理ページ

ブラウザでライセンス管理ページ (/config/license) を開くと、ライセンス情報を確認することができます。

license_info 管理コマンド

kompira コンテナで license_info 管理コマンドを用いて Kompira のライセンス状態を確認することもできます。

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

以下はライセンスが登録されている場合の実行例です。

*** Kompira License Information ***
License ID:     KE2-0000XXXX
Edition:        Development
System ID:      XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Expire date:    2025-12-31
The number of registered nodes: 2 / 100
The number of registered executors:     2 / 2
The number of registered jobflows:      3
The number of registered scripts:       0
Licensee:       kompira@example.co.jp
Signature:      XXXXXXXXXXXXXXXX....XXXXXXXXXXXXXXXX

ライセンスが登録されていない場合は、仮ライセンス情報が表示されます。

*** Kompira License Information ***
License ID:     KP-TEMP-0000000000
Edition:        temporary
System ID:      XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Expire date:    2024-07-07
The number of registered nodes: 0 / 100
The number of registered executors:     2 / 2
The number of registered jobflows:      2 / 100
The number of registered scripts:       0 / 100
Licensee:
Signature:      None

Kompira is running with temporary license.

ライセンスの申請

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

その際、ライセンスの確認 で表示されたシステム ID (System ID) をお伝えください。

ライセンスの更新

ブラウザまたは管理コマンドでライセンスの更新を行なうことができます。

ライセンス管理ページ

ライセンス管理ページ (/config/license) で「編集」ボタンを押下すると、ライセンスファイルを登録する画面に遷移します。 発行されたライセンスファイルを選択して「保存」を押下すると、ライセンス情報を更新することができます。

license_update 管理コマンド

ライセンスファイルをコマンドから更新する場合、ライセンスファイルをコンテナのファイルシステム上にコピーしてから、update_license コマンドを実行する。

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

license_update コマンドのオプション

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

なお、KE2.0 ではライセンス情報はデータベース上で管理されています。 KE1.6 までのようにファイルコピー操作でライセンスを適用することは出来ないのでご注意ください。 また、license_update コマンドにおける --no-backup オプションは廃止されています。

システム管理

KE 2.0 におけるシステム管理について示します。

• システムステータスの確認

システムステータスの確認

エンドポイント /.status に HTTP/HTTPS アクセスすることで、システムを構成する各コンテナのステータスを確認することができます。

監視システムで Kompira の状態を監視したい、また、クラスタ構成で前段でロードバランサーを設定してステータスによって振り分けたい、といった場合に利用することができます。

注意: このエンドポイントは認証無しにアクセスすることができるようになっています。外部からのアクセスを防ぐ必要がある場合は、Kompira システムの外部のファイアーウォールなどでブロックするようにしてください。

※ システムステータスの確認は KE v2.0.1 から対応しました。

ステータスコード

システムステータス /.status にアクセスすると、レスポンスのステータスコードでシステムの全体的な状況を示します。

• 200 OK: 正常
• 503 Service Unavailable: 重要なコンテナ (redis, postgreqsl) が動作していない。
• 504 Gateway Timeout: kompira コンテナが動作していない、または、ステータス取得にタイムアウトした。

※ kompira コンテナより前段のコンポーネントが上記以外のエラーコードを返す場合も考えられます。

応答がない場合は、Kompira システムのホストサーバがダウンしている、ネットワークが導通していない、Docker およびコンテナが正常に動作していない、といった障害が発生していることが考えられます。

システムステータスが異常を示している、またはシステムステータスが取得できない、といった場合は、システムに何らかの問題が生じていると考えられます。トラブルシュートを参考にして、システムの診断を行なって回復手順を試してみてください。

ブラウザアクセス時のシステムステータス

エンドポイント /.status にブラウザでアクセスすると、以下のような画面が表示されます。

これは、全てのコンテナが正常に動作しているときの表示になります。

一方で、異常や警告が発生しているコンテナがあると、以下のように当該コンテナが赤(異状)や黄色(警告)の表示になります。

各コンテナの領域をクリックすると以下のように詳細な情報が表示されますが、その内容は次に示す API アクセス時のレスポンスと同じです。

ここまではステータスコードとしては 200 となる例を示していました。重要なコンテナ (redis, postgreqsl) が動作していない場合はステータスコードが 503 となり、以下のように画面の表示上でもステータスコードを確認することができます。

API アクセス時のシステムステータス

エンドポイント /.status に API アクセスすると、JSON 形式のレスポンスを得ることができます。 API アクセスするには、リクエストのヘッダに Accept: application/json を含めてください。または、クエリ文字列に format=json を含めて /.status?format=json にアクセスする方法もあります。

API アクセスでは、各コンテナのステータスを含む情報を以下のような辞書形式で返します。

{
    "redis": {
        "status": <Status of Redis: "OK"|"NG"|"ERROR">
    },
    "postgres": {
        "status": <Status of PostgreSQL: "OK"|"NG"|"ERROR">
    },
    "rabbitmq": {
        "status": <Status of RabbitMQ: "OK"|"NG"|"ERROR">
    },
    "kompira": {
        "status": <Status of Kompira server: "OK"|"WARNING"|"ERROR">
        "detail": {
            "version": <Version of kompira>,
            "hostname": <Hostname of kompira>,
            "proc_id": <process id>,
            "started_datetime": <Date and time the kompira server started>,
            "license_expire": <Date the license expires>,
            "license_error": <License error> or null
        }
    },
    "kengine": {
        "status": <Status of Kompira engine: "OK"|"NG"|"ERROR">
        "total_num": <Total number of kompira engines>,
        "running_num": <Number of running kompira engines>,
        "executor_num": <Number of active executors>,
        "detail": [
            {
                "engine_id": <Engine ID>,
                "status": <Status of engine: "STARTED"|"RUNNING"|"UNKNOWN">,
                "role": <Role of engine: "leader"|"follower">,
                "hostname": <Hostname of kengine>,
                "executor_num": <Number of executor>,
                "started_datetime": <Date and time the kompira engine started>,
                "proc_id": <process id>
            },
            ...
        ]
    },
    "jobmngrd": {
        "status": <Status of Kompira jobmngrd: "OK"|"NG"|"ERROR">
        "total_num": <Total number of jobmngrd>,
        "active_num": <Number of active jobmngrd>,
        "detail": [
            {
                "realm_name": <Realm name>,
                "status": <Status of jobmngrd: "RUNNING"|"UNKNOWN">,
                "hostname": <Hostname of jobmngrd>,
                "version": <Version of jobmngrd>,
                "ssl": <SSL version>,
                "pid": <process id>
            },
            ...
        ]
    }
}

レスポンス辞書の、コンテナごとのステータス値 (.status) は、以下のような状態を示しています。

• "OK": 正常
• "WARNING": 正常（ただし警告を示す情報がある）
  • kompira: ライセンスエラーが生じている。
• "NG": 異状（対象コンテナにアクセスできるが、正常性を示していない）
  • redis: PING 要求に応答しない。
  • postgres: クエリ "SELECT 1" に応答しない。
  • rabbitmq: 接続後に内部で例外が発生している。
  • kengine: 実行状態のエンジンが 1 つも存在しない、または、アクティブなエグゼキュータが 1 つも存在しない。
  • jobmngrd: アクティブなジョブマネージャが 1 つも存在しない。
• "ERROR": エラー
  • 対象コンテナが動作していない、または、アクセスできない。

データ管理

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

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

データのエクスポート

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)

暗号化秘密鍵の管理

パスワードフィールドの暗号化には暗号化秘密鍵が必要になります。 この暗号化秘密鍵はシステムの初回起動時にランダムに自動生成されて秘密鍵ファイルに記録されています。

ここでは、この秘密鍵の管理手順について示します。

秘密鍵の変更

パスワードフィールドの暗号化に使用する秘密鍵を変更するには、管理コマンド manage.py change_secretkey を実行したあとに、kompira および kengine コンテナを再起動します。

注意: 秘密鍵を変更した後は kompira および kengine コンテナを再起動する必要があります。そのため、実行中のジョブフローがある場合は全て異常終了することに注意してください。可能であれば実行中のジョブフローが存在しないときに実施するようにしてください。

change_secretkey の実行

change_secretkey を実行すると、データベースに暗号化されて保存されている全てのパスワードデータを、新しい秘密鍵で再暗号化して保存し直します。

change_secretkey コマンドの形式は以下の通りです。新しい秘密鍵は文字列で <new_secretkey> の部分に指定してください。

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

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

注釈: 秘密鍵の文字列はコンテナから見える /var/opt/kompira/.secret_key に保存されますが、ホスト上では構成によって異なるパスに存在することになります。

秘密鍵変更後のコンテナ再起動

秘密鍵を変更した後は、kompira および kengine コンテナを再起動してください。 この手順を実行すると kengine コンテナが再起動するため、実行中のジョブフローは全て異常終了することに注意してください。

シングル構成の場合

シングル構成においては、以下の手順で kompira, kengine コンテナを再起動してください。

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

クラスタ構成の場合

Swarm クラスタ構成においては、いずれかの Swarm マネージャノード上で、以下の手順で全ノードの kompira, kengine コンテナを再起動してください。

[ke2-server1]$ docker service update --force ke2_kompira
[ke2-server1]$ docker service update --force ke2_kengine

システムパッケージ管理

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

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

クラスタ構成の保守

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

• クラスタの停止
• クラスタの開始
• ノードの停止
• ノードの起動
• コンテナの移動
• システムの削除

クラスタの停止

クラスタ構成のシステム全体を停止させる場合の手順を示します。

注意事項

システム全体を停止する手順を実行すると以下のような影響があります。

• 実行中のジョブフローはすべて異常終了になります。自動再起動が有効なプロセスについては、システム全体を再開させた時に自動的に再起動します。

  補足: 実行中のジョブフロープロセスに自動再起動が有効と設定されている場合、そのプロセスを実行中の kengine が動作しているノードを停止すると、別の動作中のノードで同じジョブフローを自動的に再起動するという動きをとります。そのため、システム全体を停止する手順としてノードを順番に停止させていく過程で、1台の停止ごとに時間があくと、ジョブフロープロセスの強制終了と自動再起動が短時間に繰り返される場合があることに注意してください。そうした振る舞いが好ましくない場合は、クラスタを停止させる前に、当該ジョブフロープロセスを手動で中止しておいてください。手動で中止したプロセスは自動再起動の対象外となります。ただし、システム全体を再開させた場合の自動的な再起動も行われませんので、必要に応じて手動で起動するようにしてください。

• 停止期間中に実行予定となっていたスケジュールは（再起動後も）実行されません。

3台構成のクラスタでは2台目のノードを停止した時点で、クラスタ構成メンバーが過半数を割るため、システムとしては正常に動作しなくなりはじめます（なお、過半数ノード停止状態でのシステム正常動作はサポート範囲外です）。ブラウザでアクセスしても「502 Bad Gateway」などのエラーになったり、docker コマンドでノード一覧を確認しようとしても以下のようにエラーになります。

$ docker node ls
Error response from daemon: rpc error: code = Unknown desc = The swarm does not have a leader.
It's possible that too few managers are online. Make sure more than half of the managers are online.

こうしたエラーは想定通りとなりますので、残ったノードについても続けて停止してください。

クラスタ停止手順

クラスタを構成するノードを順番に停止させてください。

基本的に停止させるノードの順番は問いませんが、クラスタを再開するときは「ノードを停止させた逆順に開始する」ことが望ましいため、停止させたノードの順番は記録しておいてください。

各ノードを、例えば ke2-server3, ke2-server2, ke2-server1 の順で停止させた場合、クラスタを再開するときは ke2-server1, ke2-server2, ke2-server3 の順で起動することを推奨します。

各ノードの停止

クラスタを構成するホストサーバを順番にシャットダウンしてください。

$ sudo poweroff

※ poweroff コマンドが存在しないホストサーバの場合、shutdown -h now など代替のコマンドを利用してください。

または、対象ホストサーバ上で docker.socket を停止させることで、ホストサーバを停止させずにノード停止と同様の状態にすることができます。 （docker.service を停止させても、docker.socket を停止させていないと自動的に再起動することに注意してください）

$ sudo systemctl stop docker.socket

注意事項に記載のとおり、あるノードを停止したあとに過半数のノードが残っていない場合、例えば3台構成で1台になった時点で、docker node コマンドによる構成ノードの確認や、docker service ps コマンドによるコンテナの状態確認などは行えなくなりますので、ご注意ください。

必須ではありませんが、あるノードを停止したあとに、2台以上のノードが残っている段階では、停止したノードが docker node ls コマンドで STATUS が "Down" になったのを確認してから、次のノードの停止手順に進むことを推奨します。通常であればサーバをシャットダウンして数十秒程度以内に Down 状態になります。

以下の例ではノード ke2-server3 が Down 状態になっていることが分かります。

$ docker node ls
ID                            HOSTNAME      STATUS    AVAILABILITY   MANAGER STATUS   ENGINE VERSION
l96i39jjjq8ntkzu2p2vvejvf     ke2-server1   Ready     Active         Reachable        26.1.4
sw6kopnwous6gfz0zg1qcp1ho *   ke2-server2   Ready     Active         Leader           26.1.4
0i62egrvpwj0lpittkx9dw9na     ke2-server3   Down      Active         Unreachable      26.1.4

クラスタの開始

全体を停止させていたクラスタ構成のシステムを開始する手順を示します。

なお、ここではノードやコンテナの構成および設定などについて、停止前から変更を加えていないことを前提としています。

注意事項

3台数構成の swarm クラスタでは2台以上のノードで docker が開始しないと、クラスタノードの構成と各コンテナの起動は始まりません。 以下に説明する手順においても、途中までは各コンテナの動作は始まりませんので注意してください。

また、いくつかのコンテナには以下のような依存関係があり、依存するコンテナが正常に動作していないと起動しないようになっています。

たとえば、kompira や kengine コンテナは redis, postgres, rabbitmq コンテナに依存していますので、それらが正常に動作するまで起動に時間がかかったり、状況によってはコンテナの再起動を自動的に何度か繰り返す場合があります。通常であれば数分程度で安定しますので、一時的なコンテナの再起動などがあっても静観するようにしてください。

開始失敗時の対策

全てのノードを起動してから、5分以上経過してもいずれかのコンテナが正常に起動していない（コンテナの起動に失敗する、コンテナが再起動を繰り返す）ような場合は、システムに何らかの異常をきたしている可能性があります。そのような場合、以下を参考に対策してみてください。

• 一度クラスタ全体を停止させてから、クラスタ全体の開始を再度試してみてください。
• それでも状況が改善しない場合は、トラブルシュートを参考にして、システムの診断を行なって回復手順を試してみてください。
• それでも状況が改善しない場合は、サポート窓口またはコミュニティサイトにお問い合わせください。

クラスタ開始手順

クラスタを構成するノードを順番に起動させてください。

【要確認】このとき、可能であれば最後に停止させたノードから起動させてください。

【要確認】なお、各ミドルウェア (glusterfs, docker など) がすべて自動起動するように構成されている場合は、クラスタを構成する全てのノードを一度に起動させても問題ありませんが、各ノード起動による状態の変遷を確認しながらクラスタを開始することを推奨します。

各ノードを、ここでは ke2-server1, ke2-server2, ke2-server3 の順で起動するとした場合、以下のような流れになります。

• ke2-server1 起動:
  • ノードの正常起動を確認
  • ※ Pgpool-II/PostgreSQL の起動とオンラインリカバリ (primary ノードの起動)
• ke2-server2 起動:
  • ノードの正常起動を確認
  • 共有ファイルシステムのマウント
  • ※ Pgpool-II/PostgreSQL の起動とオンラインリカバリ (standby ノードの起動)
  • docker の起動 (共有ファイルシステムとデータベースを確認してから、ke2-server1 もここで起動します)
  • クラスタノードのステータスを確認 (2台が Ready になっている)
  • コンテナの開始を確認 (2台のノードでコンテナが開始している)
• ke2-server3 起動:
  • ノードの正常起動を確認
  • 共有ファイルシステムのマウント
  • ※ Pgpool-II/PostgreSQL の起動とオンラインリカバリ (standby ノードの起動)
  • docker の起動
  • クラスタノードのステータスを確認 (3台が Ready になっている)
  • コンテナの開始を確認 (全てのノードでコンテナが開始している)
  • 全体のステータスを確認

※ 手順「pgpool-II/PostgreSQL の起動とオンラインリカバリ」は、外部データベースを利用した構成では不要です。

ノードの正常起動を確認

クラスタを構成するノードが正常に起動していることを、必要に応じて確認してください。

• SSH またはコンソールで対象ノードにログインできる。
• ホスト名およびネットワークアドレスが正しく構成されている。
• 所属ネットワークへの導通（例えばデフォルトゲートウェイへの ping）が確認できる。
• 2台目以降のノードを起動した場合は、クラスタを構成するノード間の導通についても確認する。

共有ファイルシステムのマウント

Kompira クラスタが利用している共有ファイルシステムをマウントしてください。 ここでは glusterfs を利用して構成している場合の例を示します。

ただし、起動ノードが 1 台の段階ではマウント処理はできません。2台のノード起動後にマウントするようにしてください。

• glusterd サービスを起動してください。

  • glusterd サービスの起動自体はノードが 1 台の段階でも実施することができます。

    $ sudo systemctl start glusterd
    

  • なお GlusterFS の準備 を参考に glusterfs を構築している場合は自動起動しているはずです。

• glusterfs ボリュームをマウントしてください。

  • 自動マウントする設定をしている場合でも、マウントされていることを必ず確認してください。
  • マウントされていない場合は、例えば mount コマンドを用いて手動でマウントしてください（マウントポイントは構成に合わせてください）。

    $ sudo mount /mnt/gluster
    

少なくとも 2台の glusterfs ノードが起動していない段階では、マウントに失敗することに注意してください。

$ sudo mount /mnt/gluster
Mount failed. Check the log file  for more details.

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

注意: 外部データベースを利用してシステムを構成している場合は、この手順はスキップしてください。ただし、クラスタを開始するときは、事前に外部データベースが正常に動作していて接続可能な状態であることを確認するようにしてください。

Kompira クラスタを構成しているノード上で（docker コンテナ外部で） Pgpool-II/PostgreSQL クラスタも構成している場合は、docker を起動する前に Pgpool-II/PostgreSQL の起動とオンラインリカバリを実施してください。

• 1台目のノードを起動した段階:
  • postgreSQL を起動してください。
    • 【重要】postgresql が primary となるノード（例えば最後に停止したノード）を、1台目のノードとして起動してください。
    • または、このノードの postgresql が primary になるように起動してください。
      • 例えば、pgsql12 以降では $PGDATA/standby.signal を削除してから起動してください。
  • Pgpool-II を起動してください。

    $ sudo systemctl start pgpool
    

  • 詳細については Pgpool-II の準備 の「Pgpool-II の起動」を参考にしてください。
• 2台目以降のノードを起動した段階:

  • Pgpool-II を起動してください。

    $ sudo systemctl start pgpool
    

  • Pgpool-II で当該ノードの postgresql に対するオンラインリカバリを実施してください。ここで、$CLUSTER_VIP は Pgpool-II で使用する仮想IPアドレスを、{ノードID} はオンラインリカバリする対象のノードIDを指定してください。

    $ pcp_recovery_node -h $CLUSTER_VIP -p 9898 -U pgpool -n {ノードID} -W
    

  • 詳細については Pgpool-II の準備 の「スタンバイサーバのオンラインリカバリ」を参考にしてください。

docker の起動

起動したノードで docker が起動していない場合（または自動起動しないように設定している）は、以下のように開始してください。 なお、Swarm クラスタの準備 を参考にクラスタを構築している場合は、docker は自動起動するようになっています。

$ sudo systemctl start docker

共有ファイルシステムやデータベースが外部構成でも自動起動する設定にもなっていない（自動起動しないようにしている）場合は、docker についても自動起動しないように構成することも検討してみてください。docker を含めて2台以上のノードが起動してから正常なクラスタ動作を開始できるサービスが多いので、2台のノードを起動してから各サービスを手動で開始する手順をとることで、各手順ごとに状態を確認しながら作業することが出来るようになります。

クラスタノードのステータスを確認

2台以上のノードを起動して docker を開始したら、docker node ls コマンドを用いてクラスタノードの状態を確認してください。 ただし、ステータスが取得できるようになるのに、ノード起動後少し時間がかかる場合があるので注意してください。

例えば、2台目のノードを起動したあと以下のように 2 台の STATUS が "Ready" になり、そのうち一台の MANAGER STATUS が "Leader" になるはずです。 また、まだ起動していない3台目のノードについては、STATUS が "Down" となり MANAGER STATUS が "Unreachable" となっていることが分かります。

$ docker node ls
ID                            HOSTNAME      STATUS    AVAILABILITY   MANAGER STATUS   ENGINE VERSION
l96i39jjjq8ntkzu2p2vvejvf *   ke2-server1   Ready     Active         Reachable        26.1.4
sw6kopnwous6gfz0zg1qcp1ho     ke2-server2   Ready     Active         Leader           26.1.4
0i62egrvpwj0lpittkx9dw9na     ke2-server3   Down      Active         Unreachable      26.1.4

3台目のノードを起動したあとであれば、以下のようにすべてのノードの STATUS が "Ready" になるはずです。

$ docker node ls
ID                            HOSTNAME      STATUS    AVAILABILITY   MANAGER STATUS   ENGINE VERSION
l96i39jjjq8ntkzu2p2vvejvf *   ke2-server1   Ready     Active         Reachable        26.1.4
sw6kopnwous6gfz0zg1qcp1ho     ke2-server2   Ready     Active         Leader           26.1.4
0i62egrvpwj0lpittkx9dw9na     ke2-server3   Ready     Active         Reachable        26.1.4

なお、1台目のノードを起動しただけの時点では、マネージャノード数が足りずに以下のようにエラーになります。

$ docker node ls
Error response from daemon: rpc error: code = Unknown desc = The swarm does not have a leader.
It's possible that too few managers are online. Make sure more than half of the managers are online.

コンテナの開始を確認

各ノードでクラスタノードの状態を確認できたら、docker service ps コマンドを用いてコンテナの開始状況を確認してください。このコマンドは終了しているコンテナの情報も表示するため、ここでは以下のように実行中となるはずのコンテナだけを表示して確認しています。

$ docker service ps -f desired-state=running $(docker service ls -q)

なお、このコマンドは docker が正常に開始している任意のノードで実行できます。

例えば、2台目のノードを起動したあとにコンテナが正常に起動を開始している状況の例を以下に示します。 3台目のノードが起動していないために、NODE は空欄になっており（当該コンテナがどこでも起動していない）、ERROR には "no suitable node" などのエラーが表示されていることがわかります。

$ docker service ps -f desired-state=running $(docker service ls -q)
ID             NAME             IMAGE                                                  NODE          DESIRED STATE   CURRENT STATE           ERROR                              PORTS
i85kdpqhato3   ke2_jobmngrd.1   kompira.azurecr.io/kompira-enterprise:latest                         Running         Pending 3 minutes ago   "no suitable node (max replica…"
24z2rcnhc4ll   ke2_jobmngrd.2   kompira.azurecr.io/kompira-enterprise:latest           ke2-server2   Running         Running 3 minutes ago
2xo9xug784u3   ke2_jobmngrd.3   kompira.azurecr.io/kompira-enterprise:latest           ke2-server1   Running         Running 3 minutes ago
vg0zk3qsc446   ke2_kengine.1    kompira.azurecr.io/kompira-enterprise:latest                         Running         Pending 3 minutes ago   "no suitable node (max replica…"
gdvrufzwbov5   ke2_kengine.2    kompira.azurecr.io/kompira-enterprise:latest           ke2-server1   Running         Running 3 minutes ago
v5cewfo0ewme   ke2_kengine.3    kompira.azurecr.io/kompira-enterprise:latest           ke2-server2   Running         Running 3 minutes ago
bs2c7tfddwy7   ke2_kompira.1    kompira.azurecr.io/kompira-enterprise:latest           ke2-server2   Running         Running 3 minutes ago
g2cp91cwhxd3   ke2_kompira.2    kompira.azurecr.io/kompira-enterprise:latest           ke2-server1   Running         Running 3 minutes ago
mc45a9ilfmg6   ke2_kompira.3    kompira.azurecr.io/kompira-enterprise:latest                         Running         Pending 3 minutes ago   "no suitable node (max replica…"
j47uexpxtz8k   ke2_nginx.1      registry.hub.docker.com/library/nginx:1.27-alpine                    Running         Pending 3 minutes ago   "no suitable node (host-mode p…"
szgmu5n2f3t7   ke2_nginx.2      registry.hub.docker.com/library/nginx:1.27-alpine      ke2-server2   Running         Running 2 minutes ago                                      *:443->443/tcp,*:443->443/tcp,*:80->80/tcp,*:80->80/tcp
k32ba9qgcuyj   ke2_nginx.3      registry.hub.docker.com/library/nginx:1.27-alpine      ke2-server1   Running         Running 3 minutes ago                                      *:80->80/tcp,*:80->80/tcp,*:443->443/tcp,*:443->443/tcp
zeazgzl9ch9w   ke2_rabbitmq.1   registry.hub.docker.com/library/rabbitmq:3.13-alpine                 Running         Pending 3 minutes ago   "no suitable node (max replica…"
yfvlqgh9urr2   ke2_rabbitmq.2   registry.hub.docker.com/library/rabbitmq:3.13-alpine   ke2-server2   Running         Running 3 minutes ago
khp2uezdem9z   ke2_rabbitmq.3   registry.hub.docker.com/library/rabbitmq:3.13-alpine   ke2-server1   Running         Running 3 minutes ago
s7c9pqm0gf7g   ke2_redis.1      registry.hub.docker.com/library/redis:7.2-alpine       ke2-server1   Running         Running 3 minutes ago

2台目のクラスタが正常に起動したとしても各コンテナは順次起動していきます。 そのため早すぎる段階でコマンドを実行しても、すべてのコンテナが開始していない場合があります（コマンド実行結果の一覧に表示されない）ので注意してください。

$ docker service ps -f desired-state=running $(docker service ls -q)
ID             NAME             IMAGE                                                  NODE          DESIRED STATE   CURRENT STATE                    ERROR                              PORTS
i85kdpqhato3   ke2_jobmngrd.1   kompira.azurecr.io/kompira-enterprise:latest                         Running         Pending 2 seconds ago            "no suitable node (max replica…"
v5cewfo0ewme   ke2_kengine.3    kompira.azurecr.io/kompira-enterprise:latest           ke2-server2   Running         Running less than a second ago
mc45a9ilfmg6   ke2_kompira.3    kompira.azurecr.io/kompira-enterprise:latest                         Running         Pending 2 seconds ago            "no suitable node (max replica…"
yfvlqgh9urr2   ke2_rabbitmq.2   registry.hub.docker.com/library/rabbitmq:3.13-alpine   ke2-server2   Running         Running less than a second ago

3台目のノードを起動したあとに全てのコンテナが起動を開始している状況の例を以下に示します。 全てのコンテナの行で NODE がいずれかのノードのホスト名を示していて、ERROR 列はすべて空欄になっていることが分かります。

$ docker service ps -f desired-state=running $(docker service ls -q)
ID             NAME             IMAGE                                                  NODE          DESIRED STATE   CURRENT STATE            ERROR     PORTS
3ruhydde239r   ke2_jobmngrd.1   kompira.azurecr.io/kompira-enterprise:latest           ke2-server3   Running         Running 31 seconds ago
24z2rcnhc4ll   ke2_jobmngrd.2   kompira.azurecr.io/kompira-enterprise:latest           ke2-server2   Running         Running 4 minutes ago
2xo9xug784u3   ke2_jobmngrd.3   kompira.azurecr.io/kompira-enterprise:latest           ke2-server1   Running         Running 4 minutes ago
zl3f74s8xtfh   ke2_kengine.1    kompira.azurecr.io/kompira-enterprise:latest           ke2-server3   Running         Running 31 seconds ago
gdvrufzwbov5   ke2_kengine.2    kompira.azurecr.io/kompira-enterprise:latest           ke2-server1   Running         Running 4 minutes ago
v5cewfo0ewme   ke2_kengine.3    kompira.azurecr.io/kompira-enterprise:latest           ke2-server2   Running         Running 4 minutes ago
bs2c7tfddwy7   ke2_kompira.1    kompira.azurecr.io/kompira-enterprise:latest           ke2-server2   Running         Running 4 minutes ago
g2cp91cwhxd3   ke2_kompira.2    kompira.azurecr.io/kompira-enterprise:latest           ke2-server1   Running         Running 4 minutes ago
2kiwn6dvorv5   ke2_kompira.3    kompira.azurecr.io/kompira-enterprise:latest           ke2-server3   Running         Running 31 seconds ago
mqod5o21dvrp   ke2_nginx.1      registry.hub.docker.com/library/nginx:1.27-alpine      ke2-server3   Running         Running 28 seconds ago             *:443->443/tcp,*:443->443/tcp,*:80->80/tcp,*:80->80/tcp
szgmu5n2f3t7   ke2_nginx.2      registry.hub.docker.com/library/nginx:1.27-alpine      ke2-server2   Running         Running 4 minutes ago              *:443->443/tcp,*:443->443/tcp,*:80->80/tcp,*:80->80/tcp
k32ba9qgcuyj   ke2_nginx.3      registry.hub.docker.com/library/nginx:1.27-alpine      ke2-server1   Running         Running 4 minutes ago              *:80->80/tcp,*:80->80/tcp,*:443->443/tcp,*:443->443/tcp
q007y2p80gs8   ke2_rabbitmq.1   registry.hub.docker.com/library/rabbitmq:3.13-alpine   ke2-server3   Running         Running 31 seconds ago
yfvlqgh9urr2   ke2_rabbitmq.2   registry.hub.docker.com/library/rabbitmq:3.13-alpine   ke2-server2   Running         Running 4 minutes ago
khp2uezdem9z   ke2_rabbitmq.3   registry.hub.docker.com/library/rabbitmq:3.13-alpine   ke2-server1   Running         Running 4 minutes ago
s7c9pqm0gf7g   ke2_redis.1      registry.hub.docker.com/library/redis:7.2-alpine       ke2-server1   Running         Running 4 minutes ago

なお、1台目のノードを起動しただけの時点では、マネージャノード数が足りずに以下のようにエラーになります。

$ docker service ps -f desired-state=running $(docker service ls -q)
Error response from daemon: rpc error: code = Unknown desc = The swarm does not have a leader. It's possible that too few managers are online. Make sure more than half of the managers are online.
"docker service ps" requires at least 1 argument.
See 'docker service ps --help'.

Usage:  docker service ps [OPTIONS] SERVICE [SERVICE...]

List the tasks of one or more services

全体のステータスを確認

全てのノードが起動できたら、クラスタを構成する各コンテナが正常に動作しているか確認してください。

• ブラウザで /.status 画面を開いて全てのコンテナが正常を示している（赤い表示になっていない）ことを確認してください。
• ブラウザで Kompira にログインできることを確認してください。
• 自動起動または自動再起動するジョブフローが存在する場合は、期待通りにプロセスが開始しているかを確認してください。なお、システムが正常な場合、(3台構成の場合) 2台目のノードを起動した時点で、このプロセスの自動起動処理は開始しています。

全てのノードが正常起動して、全てのコンテナが正常に動作していれば、クラスタ開始の成功となります。

ノードの停止

クラスタ構成において運用状態のまま一部のノードを停止させる手順を示します。

なお、ここでは一部のノードを停止する前は、全てのノード・全てのコンテナが正常に動作していることを前提としています。

制限事項

クラスタ構成においてシステムの運用を継続しつつ一部のノードを停止させたい場合、「停止させるノードは1台まで」 にしてください。

※ 5台以上の多ノード構成場合は2台まで停止できる可能性がありますが、現時点でサポート対象となるのは1台までの停止です。

注意事項

ノードを停止させると、実行中のジョブフローの動作などに影響を与える場合があります。 可能であればジョブフローが全て停止している状態で実施されることをお勧めします。

• 【重要】当該ノードで redis コンテナが動作していた場合、ノードを停止させると redis コンテナが別のノードに移動します。このとき一時的に redis がダウン状態になるため、以下のような影響があります。システム影響が大きいため redis コンテナが動作しているノードの停止は十分注意して実施してください。
  • ブラウザアクセスや REST-API アクセスが一時的にエラーになる場合があります。
  • 実行中のジョブフロープロセスが異常終了する場合があります。
• 当該ノードの kengine コンテナ上の Executor で実行中のジョブフローは強制終了されます。
  • 当該のジョブフロープロセスに「自動再起動」フラグが設定されている場合は、別のノード上で同じジョブフローが同じパラメータで新たに再起動されます。
• 【要確認】当該ノードの kengine が leader として動作 (role="leader") していた場合、ノードを停止させると leader が別のノードに移動します。

ノードの停止手順

停止対象のホストサーバをシャットダウンしてください。

$ sudo poweroff

※ poweroff コマンドが存在しないホストサーバの場合、shutdown -h now など代替のコマンドを利用してください。

または、対象ホストサーバ上で docker.socket を停止させることで、ホストサーバを停止させずにノード停止と同様の状態にすることができます。 （docker.service を停止させても、docker.socket を停止させていないと自動的に再起動することに注意してください）

$ sudo systemctl stop docker.socket

確認手順

クラスタの過半数のノードが正常に動作している場合、システムとしては正常に動作します。 一部のノードを停止したあとに、残ったノードでシステムが正常に動作しているかを確認してください。

• ブラウザで /.status 画面を開いて全てのコンテナが正常を示している（赤い表示になっていない）ことを確認してください。
• ブラウザで Kompira にログインできることを確認してください。
• 自動再起動が有効に設定されたジョブフロープロセスが実行中であった場合、別のノードで同じジョブフローが新たに開始していることを確認してください。

注意事項にあるように redis コンテナが移動するケースなどで、一時的にエラーが発生することがありますが、通常であれば時間経過とともに安定します。

停止失敗時の対策

一部のノードを停止したあとにエラーが発生するようになり、5分以上経過してもシステムが正常な状況に回復しないような場合は、システムに何らかの異常をきたしている可能性があります。そのような場合、以下を参考に対策してみてください。

• トラブルシュートを参考にして、システムの診断を行なって回復手順を試してみてください。
• それでも状況が改善しない場合は、サポート窓口またはコミュニティサイトにお問い合わせください。

ノードの起動

クラスタ構成において運用状態のまま停止させていた一部ノードを起動する手順を示します。

なお、ここではクラスタを構成する過半数のノードが起動していて、全てのコンテナが正常に動作していることを前提としています。

起動手順

前提条件から、3台構成のクラスタで言えば2台のノードでシステムが正常動作中で、最後の3台目を起動するのと同じ状況ですので、クラスタの開始 の3台目のノードの開始と同様の手順になります。

• ke2-server3 起動:
  • ノードの正常起動を確認
  • 共有ファイルシステムのマウント
  • ※ Pgpool-II/PostgreSQL の起動とオンラインリカバリ (standby ノードの起動)
  • docker の起動
  • クラスタノードのステータスを確認 (3台が Ready になっている)
  • コンテナの開始を確認 (全てのノードでコンテナが開始している)
  • 全体のステータスを確認

ここでは簡略化した説明に留めますので、詳しくは クラスタの開始 を参照してください。

ホストサーバの起動

停止させていたホストサーバを起動してください。

共有ファイルシステムのマウント

Kompira クラスタが利用している共有ファイルシステム (glusterfs など) をマウントしてください。 ここでは glusterfs を利用して構成している場合の例を示します。

glusterd サービスを起動して、glusterfs ボリュームをマウントしてください（マウントポイントは構成に合わせてください）。

$ sudo systemctl start glusterd
$ sudo mount /mnt/gluster

pgpool-II/PostgreSQL の起動とオンラインリカバリ

注意: 外部データベースを利用してシステムを構成している場合は、この手順はスキップしてください。

pgpool サービスを起動して、起動したノードの postgresql に対するオンラインリカバリを実施してください。ここで、$CLUSTER_VIP は Pgpool-II で使用する仮想IPアドレスを、{ノードID} はオンラインリカバリする対象のノードIDを指定してください。

$ sudo systemctl start pgpool
$ pcp_recovery_node -h $CLUSTER_VIP -p 9898 -U pgpool -n {ノードID} -W

docker の起動

docker サービスを起動してください。

$ sudo systemctl start docker

クラスタノードのステータスを確認 (3台が Ready になっている)

docker node ls コマンドを用いてクラスタノードの状態を確認してください。

$ docker node ls
ID                            HOSTNAME      STATUS    AVAILABILITY   MANAGER STATUS   ENGINE VERSION
l96i39jjjq8ntkzu2p2vvejvf *   ke2-server1   Ready     Active         Reachable        26.1.4
sw6kopnwous6gfz0zg1qcp1ho     ke2-server2   Ready     Active         Leader           26.1.4
0i62egrvpwj0lpittkx9dw9na     ke2-server3   Ready     Active         Reachable        26.1.4

コンテナの開始を確認 (全てのノードでコンテナが開始している)

docker service ps コマンドを用いて全てのノードで全てのコンテナの開始していることを確認してください。

$ docker service ps -f desired-state=running $(docker service ls -q)

全体のステータスを確認

ノードが起動できたら、クラスタを構成する各コンテナが正常に動作しているか確認してください。

• ブラウザで /.status 画面を開いて全てのコンテナが正常を示している（赤い表示になっていない）ことを確認してください。
• ブラウザで Kompira にログインできることを確認してください。

コンテナの移動

ke2-docker を用いた構成した Docker swarm クラスタ構成では、明示的にコンテナを移動する操作を行なう必要はありません。 まず、ほとんどのコンテナは全てのノードでレプリカされて、全てがアクティブとして動作するため、コンテナを移動する意味はありません。

KE2.0 の時点では唯一、redis コンテナについては 単一のノードでのみ動作するように構成されています。 そのため redis コンテナについてはどのノードで動作しているのか、動作するノードが移動するケースについて、また、強制的に動作ノードを移動させたい場合の手法について説明します。

redis コンテナを実行しているノードの確認

現在どのノードで redis コンテナが動作しているかについては、docker service ps コマンドを用いて確認することができます。

$ docker service ps ke2_redis
ID             NAME              IMAGE                                              NODE          DESIRED STATE   CURRENT STATE          ERROR                              PORTS
j002f9kno7ma   ke2_redis.1       registry.hub.docker.com/library/redis:7.2-alpine   ke2-server1   Running         Running 25 hours ago
g7lg28hnfupv    \_ ke2_redis.1   registry.hub.docker.com/library/redis:7.2-alpine   ke2-server1   Shutdown        Failed 25 hours ago    "No such container: ke2_redis.…"
ngwsnwc20fqk    \_ ke2_redis.1   registry.hub.docker.com/library/redis:7.2-alpine   ke2-server1   Shutdown        Failed 25 hours ago    "No such container: ke2_redis.…"

コマンドを実行して表示される結果の DESIRED STATE が "Running" となっている行の NODE で、現在 redis コンテナを実行しているノードが確認できます。 以下のようにいくつかオプションを付けて実行すると、当該するノードの情報だけ表示することができます。

$ docker service ps -f desired-state=running --format "{{.Node}}" ke2_redis
ke2-server1

redis コンテナが移動するタイミング

クラスタが開始したとき（2台目のノードが開始したとき）いずれかのノードで redis コンテナが起動します。 基本的に redis コンテナはそのノードから移動せずに動作しつづけますが、以下のようなときには別のノードに移動して動作を再開する場合があります。

• redis コンテナがダウンしたとき（移動せず同じノードで再起動となる場合もあります）
• redis コンテナが動作しているノードがダウンしたとき
• 強制的に redis コンテナを移動させたとき

redis コンテナの移動方法【非推奨】

Docker swarm クラスタにおいて、あるコンテナを指定したノードに移動させる決まった手順はありません。 以下のように docker service update コマンドを用いることで、redis コンテナの状態更新が行なわれて、その結果として別のノードに移動する場合があります（同じノードでの再起動となる場合もあります）。

$ docker service update --force ke2_redis

ただし、redis コンテナが移動（もしくは再起動）すると動作中のジョブフローが異常終了するなどの影響が起きる場合がありますので、特別な理由がない限り redis コンテナの移動は控えることを推奨します。

システムの削除

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

クラスタの削除手順

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

[ke2-server1]$ docker stack rm ke2
Removing service ke2_jobmngrd
Removing service ke2_kengine
Removing service ke2_kompira
Removing service ke2_nginx
Removing service ke2_rabbitmq
Removing service ke2_redis
Removing config swarm_rabbitmq-config-cluster
Removing config swarm_kompira-config
Removing config swarm_rabbitmq-config-auth
Removing config swarm_kompira-audit
Removing config swarm_rabbitmq-config-ssl
Removing config swarm_bootstrap-rabbitmq
Removing config swarm_nginx-config
Removing network swarm_default

このコマンドを実行すると、クラスタで動作している全てのコンテナが停止して、クラスタスタックと構成サービスの定義などが削除されます。 停止したあとに docker stack ls, docker service ls, docker config ls コマンドを実行すると、いずれも空になっているはずです。

$ docker stack ls
NAME      SERVICES
$ docker service ls
ID        NAME      MODE      REPLICAS   IMAGE     PORTS
$ docker config ls
ID        NAME      CREATED   UPDATED

この状態になると、ノードを再起動したり docker サービスを再起動しても、Kompira サービスは起動しません。

なお、この時点では Swarm クラスタ構成自体は残っています。

$ docker node ls
ID                            HOSTNAME      STATUS    AVAILABILITY   MANAGER STATUS   ENGINE VERSION
l96i39jjjq8ntkzu2p2vvejvf *   ke2-server1   Ready     Active         Reachable        26.1.4
sw6kopnwous6gfz0zg1qcp1ho     ke2-server2   Ready     Active         Leader           26.1.4
0i62egrvpwj0lpittkx9dw9na     ke2-server3   Ready     Active         Reachable        26.1.4

そのため、Swarm クラスタ構成の セットアップ手順 からデプロイしなおすことが出来ます。

コンテナの削除手順

クラスタが停止してもコンテナが残っている場合があります。 docker container ls -a コマンドで停止したものも含めてコンテナの一覧を確認できます。

$ docker container ls -a
CONTAINER ID   IMAGE                                          COMMAND                  CREATED      STATUS    PORTS     NAMES
059775d2d864   kompira.azurecr.io/kompira-enterprise:latest   "docker-entrypoint.s…"   5 days ago   Dead                ke2_kompira.3.chic2oqd0l46t6c6i3q1yd5rk

残っているコンテナを削除したい場合は、docker container prune コマンドで一括削除できます。 本当に削除するか確認されるので、実行する場合は y を入力してください。

$ docker container prune
WARNING! This will remove all stopped containers.
Are you sure you want to continue? [y/N] y
Deleted Containers:
059775d2d864483ba451d268b41e70c8761c9efaf559e7979e65253e91568926

Total reclaimed space: 803.1kB

この手順は、クラスタを構成する各ノードで実施してください。

イメージの削除手順

クラスタを停止してもコンテナイメージは残っています。 docker image ls -a コマンドで全てのコンテナイメージの一覧を確認できます。

$ docker image ls -a
REPOSITORY                                 TAG                IMAGE ID       CREATED        SIZE
kompira.azurecr.io/kompira-enterprise      <none>             95fb2b1e3ef0   7 days ago     503MB
kompira.azurecr.io/kompira-enterprise      <none>             2fc0e8aea9b4   7 days ago     503MB
kompira-enterprise                         2.0.1a1_62f84257   f60f16a921fb   7 days ago     503MB
kompira-enterprise                         2.0.1a1_66ee42a9   c702af2baab6   7 days ago     503MB
kompira.azurecr.io/kompira-enterprise      <none>             3efb4ead515c   8 days ago     503MB
kompira-enterprise                         2.0.0_a4071bf5     eac7265ec11b   2 weeks ago    503MB
kompira-enterprise                         2.0.0_8875d278     75f9622860d7   2 weeks ago    503MB
registry.hub.docker.com/library/rabbitmq   <none>             0ca98669e517   2 weeks ago    141MB
kompira-enterprise                         2.0.0_a3309cf7     0d540ff81113   3 weeks ago    503MB
registry.hub.docker.com/library/rabbitmq   <none>             2262fa9f479a   4 weeks ago    141MB
registry.hub.docker.com/library/rabbitmq   <none>             4083c19b838f   5 weeks ago    141MB
kompira-enterprise                         2.0.0_56cb960d     868774a8f9bf   5 weeks ago    504MB
registry.hub.docker.com/library/nginx      <none>             c7b4f26a7d93   6 weeks ago    43.2MB
registry.hub.docker.com/library/nginx      <none>             0f0eda053dc5   6 weeks ago    43.3MB
kompira.azurecr.io/kompira-enterprise      <none>             de61c5570c0d   7 weeks ago    504MB
registry.hub.docker.com/library/rabbitmq   <none>             5d6e30bc0bea   8 weeks ago    141MB
registry.hub.docker.com/library/nginx      <none>             1ae23480369f   3 months ago   43.2MB
registry.hub.docker.com/library/redis      <none>             ab3bbb60f1b6   4 months ago   40.7MB
registry.hub.docker.com/library/redis      <none>             97ed3031282d   4 months ago   40.7MB

残っているコンテナイメージを削除したい場合は、docker image prune -a コマンドで一括削除できます。 本当に削除するか確認されるので、実行する場合は y を入力してください。

$ docker image prune -a
WARNING! This will remove all images without at least one container associated to them.
Are you sure you want to continue? [y/N] y
Deleted Images:
untagged: registry.hub.docker.com/library/nginx@sha256:a5127daff3d6f4606be3100a252419bfa84fd6ee5cd74d0feaca1a5068f97dcf
deleted: sha256:c7b4f26a7d93f4f1f276c51adb03ef0df54a82de89f254a9aec5c18bf0e45ee9
deleted: sha256:df45629925efee5af98c24cd09fa6eb06f53bf8a31eb6255e25efd729c902e1e
deleted: sha256:e9d09343f346fd7a1ae6dde03c9d2a948dba60c99be0083f703c10acb691a29b
    :
untagged: kompira.azurecr.io/kompira-enterprise@sha256:c40e73309d67cf98eedd111ef783e1350379c280440718b1ec57de8c4e8839a2
deleted: sha256:2fc0e8aea9b48d0f98b64480eb13792baa3da0cddb3716e676a04e0b5f274923
deleted: sha256:27161d5e2678b37f620e2273bdefd619791dc937b711a03c163f6e8fd4a37155
deleted: sha256:d940d53c7b474ee3fdbcc9f1830eb2bb0a2d69f3c35511e491b1228a47c4fe9e
    :

Total reclaimed space: 5.414GB

この手順は、クラスタを構成する各ノードで実施してください。

ボリュームの削除手順

クラスタを停止しても名前付きボリュームは残っています。 docker voluems ls コマンドでボリュームの一覧を確認できます。

$ docker volume ls
DRIVER    VOLUME NAME
local     swarm_kompira_rmq

残っているボリュームを削除したい場合は、docker volume prune -a コマンドで一括削除できます。 本当に削除するか確認されるので、実行する場合は y を入力してください。

$ docker volume prune -a
WARNING! This will remove all local volumes not used by at least one container.
Are you sure you want to continue? [y/N] y
Deleted Volumes:
swarm_kompira_rmq

Total reclaimed space: 1.141MB

この手順は、クラスタを構成する各ノードで実施してください。

ネットワークの削除

クラスタを停止しても Docker のネットワーク定義は残っています。 docker network ls コマンドでネットワークの一覧を確認できます。

$ docker network ls
NETWORK ID     NAME              DRIVER    SCOPE
d43ebc7d365d   bridge            bridge    local
937af22066a7   docker_gwbridge   bridge    local
a2a80d3dca46   host              host      local
uswsxaj23dbt   ingress           overlay   swarm
c0fa71959a20   none              null      local

docker network prune コマンドで、カスタム定義されたネットワークを削除することができます。 ただし Kompira 2.0 ではカスタム定義しているネットワークはありませんので、通常は実際に削除されるネットワークはないはずです。

$ docker network prune
WARNING! This will remove all custom networks not used by at least one container.
Are you sure you want to continue? [y/N] y

(WIP) トラブルシュートガイド

• 各コンテナの障害時の影響範囲
• 障害時の初期診断手順
• 障害パターンごとの調査手順と対策