はじめに

MarkLogicはREST-APIを使えます。REST-APIを使えば、データアクセスだけでなく、MarkLogic自体の設定や環境構築も行えます。このREST-APIとChefやAnsibleなどの構成管理ツールを組み合わせることで、大規模なクラスタ環境の構築など、MarkLogicの環境構築の自動化を実現できるようになります。

今回はMarkLogicのインストールからクラスタ構築まで、主にREST-APIを使ってコマンドラインで実施する手順をご紹介します。

なお、MarkLogicの環境構築に関するREST-APIの公式ドキュメントはこちらをご確認ください。

環境

以下の環境で実施します。

環境	バージョン
CentOS7	7.4.1708
MarkLogic	9.0-3.1

MarkLogicサーバはクラスタ構成にするため、３台以上のホストを用意します。本記事では４台構成の例を記します。ホスト名は"host1"、"host2"、"host3"、"host4"とします。

MarkLogicのクラスタ構築は、最初の１ホスト目にクラスタの設定を行い、２台目以降はそのクラスタに追加する流れとなります。
この最初の1台目のホストを「起動用ホスト」と記します。
２台目以降のホストを「参加ホスト」と記します。

作業の流れ

MarkLogicのインストールからクラスタ構築までの流れは以下のようになります。

No	実施ホスト	実施内容	HTTPメソッド	REST-API
1	全ホスト	YUMを使ってMarkLogicをインストールする	-	-
2	起動用ホスト	初期化	POST	/admin/v1/init
3	起動用ホスト	初期設定	POST	/admin/v1/instance-admin
4	参加ホスト	初期化	POST	/admin/v1/init
5	参加ホスト	ホストの構成情報を取得	GET	/admin/v1/server-config
6	参加ホスト	ホストの構成情報を起動用ホストに送信し、クラスタの構成情報を受信	POST	/admin/v1/cluster-config
7	参加ホスト	クラスタの構成情報を参加ホストに送信	POST	/admin/v1/cluster-config
8	全ホスト	MarkLogicのホスト名を変更（必要に応じて）	PUT	/manage/v2/hosts/[対象ホスト名]/properties
9	起動用ホスト	データベースの作成	POST	/manage/v2/databases
10	全ホスト	フォレストの作成	POST	/manage/v2/forests

１．YUMを使ってMarkLogicをインストールする

yumを使ってMarkLogicをインストールします。

yum install [MarkLogicのRPMファイル] -y

２．起動用ホストの初期化

起動用ホストを初期化します。

curl -X POST -d "" \
http://[起動用ホスト]:8001/admin/v1/init

３．起動用ホストの初期設定

起動用ホストの初期設定を行います。管理者のユーザ名やパスワード、REALMなどを設定します。

curl -X POST -H "Content-type: application/x-www-form-urlencoded" \
--data "admin-username=[ユーザ名]" \
--data "admin-password=[パスワード]" \
--data "realm=[REALM(publicなど)]" \
http://[起動用ホスト]:8001/admin/v1/instance-admin

４．参加ホストの初期化

参加ホストを初期化します。全ての参加ホストについて実行します。

curl -X POST -d "" \
http://[参加ホスト]:8001/admin/v1/init

５．参加ホストの構成情報を取得

ホストをクラスタに参加させるには、参加ホストの構成情報を取得して、それを起動用ホストに送信する必要があります。

参加ホストから構成情報を取得するには以下のように実行します。
取得した構成情報は変数に格納しておき、起動用ホストに送信する際に使用します。

JOINER_CONFIG=`curl -X GET -H "Accept: application/xml" \
http://[参加ホスト]:8001/admin/v1/server-config`

６．参加ホストの構成情報を起動用ホストに送信し、起動用ホストからクラスタ構成情報を受信する

前段の処理で取得した参加ホストの構成情報を起動用ホストに送信します。
その結果として、クラスタ側の構成情報が返却されます。クラスタの構成情報はZIPファイルとなります。

認証モードは"basic"、"digest"、"anyauth"のいずれかで、デフォルトは"anyauth"になります。
ユーザ名、パスワードは、手順３で指定した内容になります。
クラスタ構成情報ファイルは、ZIP形式の出力ファイルとなります。本手順は全ての参加ホストで実施するため、ホストの区別がつくファイル名を指定します。

curl --[認証モード(anyauth)] --user [ユーザ名]:[パスワード] -X POST \
-o [クラスタ構成情報ファイル(ZIP)] \
-d "group=Default" \
--data-urlencode "server-config=${JOINER_CONFIG}" \
-H "Content-type: application/x-www-form-urlencoded" \
http://[起動用ホスト]:8001/admin/v1/cluster-config

７．クラスタ構成情報を参加ホストに送信する

前段の手順で取得したクラスタ構成情報のZIPファイルを各参加ホストに送信します。
以上で、全ホストがクラスタに参加した状態となります。

curl -X POST -H "Content-type: application/zip" \
--data-binary @[クラスタ構成情報ファイル(ZIP)] \
http://[参加ホスト]:8001/admin/v1/cluster-config

８．必要に応じてMarkLogicのホスト名を変更する

MarkLogicのクラスタでは、クラスタに参加するホストの識別をホスト名で行っています。そのため、ホスト名が変更されるような環境の場合、正しくクラスタが機能しなくなることがあります。

例えばAWS上にMarkLogicをインストールすると、そのMarkLogicのホスト名はパブリックDNS名が設定されます。
Elastic IPアドレスなどを設定していない場合、AWSのEC2インスタンスのように、再起動するたびにホスト名が変わるような環境の場合、MarkLogicのクラスタが正しく機能しなくなります。

このような環境の場合、MarkLogicのホスト名を固定的な名前に変更する必要があります。変更する新たなホスト名は/etc/hostsなどで解決できる名前としてください。クラスタに参加する全ホストが解決できる必要があります。

なお、ホスト名を変更するREST-APIを使用するには、現在のホスト名が必要となります。現在のホスト名は以下の手順で取得します。

curl --[認証モード(anyauth)] --user [ユーザ名]:[パスワード] \
-X GET -H "Accept: application/xml" \
http://[対象ホスト]:8001/admin/v1/server-config

以下のようなXMLが返却されます。この中にhost-nameエレメントがあり、現在のホスト名が設定されています。

<?xml version="1.0"?>
 <host xmlns="http://marklogic.com/manage">
 <timestamp>2018-01-10T13:00:00.467232+09:00</timestamp>
 <version>9.0-3.1</version>
 <platform>linux</platform>
 ・・・
 <host-name>ec2-*******.ap-northeast-1.compute.amazonaws.com</host-name>
 ・・・
</host>

続いて、新たなホスト名を設定します。変更するホスト名はhost-propertiesというエレメントのXMLで定義します。
先ほど取得した現在のホスト名はREST-APIの中で使用しています。

curl --[認証モード(anyauth)] --user [ユーザ名]:[パスワード] -X PUT \
-d "<host-properties xmlns=\"http://marklogic.com/manage\"><host-name>[変更後のホスト名]</host-name></host-properties>" \
-i -H "Content-type: application/xml" \
http://[対象ホスト]:8002/manage/v2/hosts/[変更前のホスト名]/properties

９．データベースを作成する

構築したクラスタにデータベースを作成します。ここでは初期設定のデータベースを構築するのみとし、データベース名だけ指定します。

curl -X POST --[認証モード(anyauth)] --user [ユーザ名]:[パスワード] \
--header "Content-type:application/json" \
-d '{"database-name":"[データベース名]"}' \
http://[起動用ホスト]:8002/manage/v2/databases

１０．フォレストを作成する

前段で作成したデータベースに対してフォレストを作成します。
クラスタの規模が大きくなるほど、フォレストの作成は複雑になります。フォレストを作成するには以下の点を決める必要があります。
特にChefやAnsibleのような構成管理ツールで自動構築するような場合は、ディレクトリ名のルール化などが必要となります。

各ホストのフォレスト数
フォレストを格納するディレクトリ
レプリカの保存先ホスト
レプリカを格納するディレクトリ

フォレストをREST-APIで作成するには、フォレストの定義情報をXML/JSON形式で定義し、それをREST-APIで各ホストに送信します。

以下は１つのフォレストを作成するためのJSON定義の例です。以下の定義ではレプリカフォレストを１つ作成しています。

{"forest-name":"[フォレスト名]",
"host":"[ホスト名]",
"database":"[データベース名]",
"data-directory":"[フォレストを格納するディレクトリ]",
"forest-replicas":{
  "forest-replica":[
    { "replica-name":"[レプリカ名]",
      "host":"[レプリカを保存するホスト名]",
      "data-directory":"[レプリカを格納するディレクトリ]"
    }]
  }
}

上記で作成したフォレスト定義をREST-APIでクラスタの起動用ホストに送信します。フォレストを作成する参加ホストに送信するわけではありません。

curl --[認証モード(anyauth)] --user [ユーザ名]:[パスワード] -X POST \
--data [フォレスト定義(JSON)] -i -H "Content-type: application/json" \
http://[起動用ホスト]:8002/manage/v2/forests

以上でフォレスト及びレプリカフォレストが作成されます。

おわりに

MarkLogicのインストールやクラスタ環境はブラウザベースで簡単に構築できますが、REST-APIのみでも構築可能です。
ChefやAnsibleなどの構成管理ツールと併せて利用すれば、大規模な環境も簡単に構築できます。

\def\textsmall#1{%
  {\rm\scriptsize #1}
}

免責事項

$\textsmall{当ユーザ会は本文書及びその内容に関して、いかなる保証もするものではありません。}$
$\textsmall{万一、本文書の内容に誤りがあった場合でも当ユーザ会は一切責任を負いかねます。}$
$\textsmall{また、本文書に記載されている事項は予告なしに変更または削除されることがありますので、予めご了承ください。}$