インストール

本章ではPG-Stromのインストール手順について説明します。

チェックリスト

  • ハードウェア
    • CUDA ToolkitのサポートするLinuxオペレーティングシステムを動作可能な x86_64 アーキテクチャのハードウェアが必要です。
    • CPU、ストレージ、およびネットワークデバイスには特別な要件はありませんが、note002:HW Validation Listはハードウェア選定の上で参考になるかもしれません。
    • GPUダイレクトSQL実行を利用するにはNVME規格に対応したSSD、またはRoCEに対応した高速NICが必要で、GPUと同一のPCIe Root Complex配下に接続されている必要があります。
  • GPUデバイス
    • PG-Stromを実行するには少なくとも一個のGPUデバイスがシステム上に必要です。これらはCUDA Toolkitでサポートされており、computing capability が6.0以降のモデル(Pascal世代以降)である必要があります。
    • 002: HW Validation List - List of supported GPU modelsを参考にGPUを選定してください。
  • Operating System
    • PG-Stromの実行には、CUDA Toolkitによりサポートされているx86_64アーキテクチャ向けのLinux OSが必要です。推奨環境はRed Hat Enterprise LinuxまたはRocky Linuxバージョン 8.xです。
    • GPUダイレクトSQL(cuFileドライバ)を利用するには、CUDA Toolkitに含まれるnvidia-fsドライバと、Mellanox OFED (OpenFabrics Enterprise Distribution) ドライバのインストールが必要です。
  • PostgreSQL
    • PG-Strom v5.0の実行にはPostgreSQLバージョン15以降が必要です。
    • PG-Stromが内部的に利用しているAPIの中には、これ以前のバージョンでは提供されていないものが含まれています。
  • CUDA Toolkit
    • PG-Stromの実行にはCUDA Toolkit バージョン12.2update2以降が必要です。
    • PG-Stromが内部的に利用しているAPIの中には、これ以前のバージョンでは提供されていないものが含まれています。

インストール手順

一連のインストール手順は以下の通りとなります。

  1. H/Wの初期設定
  2. OSのインストール
  3. MOFEDドライバのインストール
  4. CUDA Toolkit のインストール
  5. HeteroDB拡張モジュールのインストール
  6. PostgreSQLのインストール
  7. PG-Stromのインストール
  8. PostgreSQL拡張モジュールのインストール(必要に応じて)
    • PostGIS
    • contrib/cube

OSのインストール

CUDA ToolkitのサポートするLinuxディストリビューションを選択し、個々のディストリビューションのインストールプロセスに従ってインストール作業を行ってください。 CUDA ToolkitのサポートするLinuxディストリビューションは、NVIDIA DEVELOPER ZONEにおいて紹介されています。

例えば、Red Hat Enterprise Linux 8.x系列の場合、ベース環境として「最小限のインストール」を選択し、さらに以下のアドオンを選択してください。

  • 開発ツール

RHEL8/Rocky8 Package Selection

サーバーへのOSインストール後、サードパーティーのパッケージをインストールするために、パッケージリポジトリの設定を行います。

なお、インストーラで「開発ツール」を選択しなかった場合、以下のコマンドでOSインストール後に追加インストールする事が可能です。

# dnf groupinstall 'Development Tools'

Tip

サーバに搭載されているGPUが新しすぎる場合、OS起動中にクラッシュ等の問題が発生する場合があります。 その場合、カーネル起動オプションにnouveau.modeset=0を追加して標準のグラフィックスドライバを無効化する事で 問題を回避できるかもしれません。

nouveauドライバの無効化

NVIDIA製GPU向けオープンソースの互換ドライバであるnouveauドライバがロードされている場合、nvidiaドライバをロードする事ができません。 この場合は、nouveauドライバの無効化設定を行った上でシステムを一度再起動してください。

nouveauドライバを無効化するには、以下の設定を/etc/modprobe.d/disable-nouveau.confという名前で保存し、dracutコマンドを実行してLinux kernelのブートイメージに反映します。 その後、システムを一度再起動してください。

# cat > /etc/modprobe.d/disable-nouveau.conf <<EOF
blacklist nouveau
options nouveau modeset=0
EOF
# dracut -f
# shutdown -r now

IOMMUの無効化

GPU-Direct SQLはCUDAのGPUDirect Storage (cuFile)というAPIを使用しています。

GPUDirect Storageの利用に先立って、OS側でIOMMUの設定を無効化する必要があります。

NVIDIA GPUDirect Storage Installation and Troubleshooting Guideの記述を参考に、カーネル起動オプションの設定を行ってください。

IOMMUを無効化するには、カーネル起動オプションにamd_iommu=off (AMD製CPUの場合)または、intel_iommu=off (Intel製CPUの場合)の設定を付加します。

エディタで/etc/default/grubを編集し、GRUB_CMDLINE_LINUX_DEFAULT=行に上記のオプションを付加してください。

例えば、以下のような設定となるはずです。

  :
GRUB_CMDLINE_LINUX="rhgb quiet amd_iommu=off"
  :

以下のコマンドを実行し、この設定をカーネル起動オプションに反映します。

$ sudo update-grub
$ sudo shutdown -r now

追加リポジトリの有効化

EPEL(Extra Packages for Enterprise Linux)

PG-Stromの実行に必要なソフトウェアモジュールのいくつかは、EPEL(Extra Packages for Enterprise Linux)の一部として配布されています。 これらのソフトウェアを入手するためにEPELパッケージ群のリポジトリ定義をyumシステムに追加する必要があります。

EPELリポジトリから入手するパッケージの一つがDKMS(Dynamic Kernel Module Support)です。これは動作中のLinuxカーネルに適合したLinuxカーネルモジュールをオンデマンドでビルドするためのフレームワークで、NVIDIAのGPUデバイスドライバなど関連するカーネルモジュールが使用しています。 Linuxカーネルモジュールは、Linuxカーネルのバージョンアップに追従して再ビルドが必要であるため、DKMSなしでのシステム運用は現実的ではありません。

EPELリポジトリの定義は epel-release パッケージにより提供され、Fedora Projectのサイトから入手する事ができます。

-- For RHEL8
# dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

-- For Rocky8
# dnf install epel-release

Red Hat CodeReady Linux Builder

MOFED(Mellanox OpenFabrics Enterprise Distribution)ドライバのインストールには、Red Hat Enterprise Linux 8.xの標準インストール構成では無効化されている Red Hat CodeReady Linux Builder リポジトリを有効化する必要があります。Rokey Linuxにおいては、このリポジトリは PowerTools と呼ばれています。

このリポジトリを有効化するには、以下のコマンドを実行します。

-- For RHEL8
# subscription-manager repos --enable codeready-builder-for-rhel-8-x86_64-rpms

-- For Rocky8
# dnf config-manager --set-enabled powertools

MOFEDドライバのインストール

MOFEDドライバは、こちらからダウンロードする事ができます。

本節ではtgzアーカイブからのインストール例を紹介します。

MOFED Driver Selection

tgzアーカイブを展開し、mlnxofedinstallスクリプトを実行します。この時、GPUDirect Storageのサポートを有効化するオプションを付加するのを忘れないでください。

# tar xvf MLNX_OFED_LINUX-5.8-3.0.7.0-rhel8.8-x86_64.tgz
# cd MLNX_OFED_LINUX-5.8-3.0.7.0-rhel8.8-x86_64
# ./mlnxofedinstall --with-nvmf --with-nfsrdma --add-kernel-support
# dracut -f

MOFEDドライバのビルドおよびインストール中、不足パッケージのインストールを要求される事があります。 その場合、エラーメッセージを確認して要求されたパッケージの追加インストールを行ってください。

Error: One or more required packages for installing MLNX_OFED_LINUX are missing.
Please install the missing packages using your Linux distribution Package Management tool.
Run:
yum install tcsh tcl tk kernel-modules-extra gcc-gfortran python36

MOFEDドライバのインストールが完了すると、nvmeドライバなど、OS標準のものが置き換えられているはずです。

例えば以下の例では、OS標準のnvme-rdmaドライバ(/lib/modules/<KERNEL_VERSION>/kernel/drivers/nvme/host/nvme-rdma.ko.xz)ではなく、追加インストールされた/lib/modules/<KERNEL_VERSION>/extra/mlnx-nvme/host/nvme-rdma.koが優先して使用されています。

# modinfo nvme-rdma
filename:       /lib/modules/4.18.0-477.10.1.el8_8.x86_64/extra/mlnx-nvme/host/nvme-rdma.ko
license:        GPL v2
rhelversion:    8.8
srcversion:     533BB7E5866E52F63B9ACCB
depends:        nvme-core,mlx_compat,rdma_cm,ib_core,nvme-fabrics
name:           nvme_rdma
vermagic:       4.18.0-477.10.1.el8_8.x86_64 SMP mod_unload modversions
parm:           register_always:Use memory registration even for contiguous memory regions (bool)

既にロードされているカーネルモジュール(例: nvme)を置き換えるため、ここで一度システムのシャットダウンと再起動を行います。

mlnxofedinstallスクリプトの完了後に、dracut -fを実行するのを忘れないでください。

heterodb-swdcのインストール

PG-Stromほか関連パッケージはHeteroDB Software Distribution Centerから配布されています。 これらのソフトウェアを入手するために、HeteroDB-SWDCのリポジトリ定義をyumシステムに追加する必要があります。

HeteroDB-SWDCリポジトリの定義はheterodb-swdcパッケージにより提供されます。 WebブラウザなどでHeteroDB Software Distribution Centerへアクセスし、ページの先頭にリンクの記載されているheterodb-swdc-1.2-1.el8.noarch.rpmをダウンロードしてインストールしてください。 heterodb-swdcパッケージがインストールされると、HeteroDB-SWDCからソフトウェアを入手するためのyumシステムへの設定が追加されます。

以下のようにheterodb-swdcパッケージをインストールします。

# dnf install https://heterodb.github.io/swdc/yum/rhel8-noarch/heterodb-swdc-1.2-1.el8.noarch.rpm

CUDA Toolkitのインストール

本節ではCUDA Toolkitのインストールについて説明します。 既に最新のCUDA Toolkitをインストール済みである場合、本節の初期設定と合致しているかどうか確認してください。

NVIDIAはCUDA Toolkitのインストールに2通りの方法を提供しています。一つは自己実行型アーカイブ(runfile)によるもの。もう一つはRPMパッケージによるものです。 インストールオプションを指定するため、ここではrunfileを用いる方法を推奨します。

CUDA Toolkitのインストール用パッケージはNVIDIA DEVELOPER ZONEからダウンロードする事ができます。 適切なOS、アーキテクチャ、ディストリビューション、バージョンを指定し、『runfile(local)』版を選択してください。

CUDA Toolkit download

『runfile(local)』を選択すると、自己実行型アーカイブをダウンロードするURLと、それを起動するためのシェルコマンドが表示されます。 ガイダンス通りにインストールを進めてください。

$ wget https://developer.download.nvidia.com/compute/cuda/12.3.1/local_installers/cuda_12.3.1_545.23.08_linux.run
$ sudo sh cuda_12.3.1_545.23.08_linux.run

インストーラが起動すると、いくつかのインストールオプションを指定する事ができます。

まず、デフォルトではチェックの外れている[X] Kernel Objects --> [X] nvidia-fs にチェックを入れてください。これはGPU-Direct SQLを使用するために必須のオプションです。

CUDA Runfile Installer1

次に、Options --> Driver Options を下ってゆき、[X] Install the kernel open module flavor にチェックを入れてください。将来的に、GPUDirect Storage機能はオープンソース版のドライバでのみサポートされるという事が予告されています。

CUDA Runfile Installer1

正常にインストールが完了すると、/usr/local/cuda配下にCUDA Toolkitが導入されています。

$ ls /usr/local/cuda
bin     include  libnsight         nvml       samples  tools
doc     jre      libnvvp           nvvm       share    version.txt
extras  lib64    nsightee_plugins  pkgconfig  src

インストールが完了したら、GPUが正しく認識されている事を確認してください。nvidia-smiコマンドを実行すると、以下の出力例のように、システムに搭載されているGPUの情報が表示されます。

$ nvidia-smi
Mon Dec 18 18:02:14 2023
+---------------------------------------------------------------------------------------+
| NVIDIA-SMI 545.23.08              Driver Version: 545.23.08    CUDA Version: 12.3     |
|-----------------------------------------+----------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |         Memory-Usage | GPU-Util  Compute M. |
|                                         |                      |               MIG M. |
|=========================================+======================+======================|
|   0  NVIDIA L40S                    Off | 00000000:41:00.0 Off |                    0 |
| N/A   40C    P0              90W / 350W |      4MiB / 46068MiB |      3%      Default |
|                                         |                      |                  N/A |
+-----------------------------------------+----------------------+----------------------+

+---------------------------------------------------------------------------------------+
| Processes:                                                                            |
|  GPU   GI   CI        PID   Type   Process name                            GPU Memory |
|        ID   ID                                                             Usage      |
|=======================================================================================|
|  No running processes found                                                           |
+---------------------------------------------------------------------------------------+

GPUDirect Storageの確認

上記の手順でCUDA Toolkitのインストールが完了すると、GPUDirect Storageが利用可能な状態となっているはずです。 以下の通り、gdscheckツールを用いてストレージデバイス毎のコンフィグを確認してください。

# /usr/local/cuda/gds/tools/gdscheck -p
 GDS release version: 1.0.0.82
 nvidia_fs version:  2.7 libcufile version: 2.4
 ============
 ENVIRONMENT:
 ============
 =====================
 DRIVER CONFIGURATION:
 =====================
 NVMe               : Supported
 NVMeOF             : Supported
 SCSI               : Unsupported
 ScaleFlux CSD      : Unsupported
 NVMesh             : Unsupported
 DDN EXAScaler      : Unsupported
 IBM Spectrum Scale : Unsupported
 NFS                : Unsupported
 WekaFS             : Unsupported
 Userspace RDMA     : Unsupported
 --Mellanox PeerDirect : Enabled
 --rdma library        : Not Loaded (libcufile_rdma.so)
 --rdma devices        : Not configured
 --rdma_device_status  : Up: 0 Down: 0
 =====================
 CUFILE CONFIGURATION:
 =====================
 properties.use_compat_mode : true
 properties.gds_rdma_write_support : true
 properties.use_poll_mode : false
 properties.poll_mode_max_size_kb : 4
 properties.max_batch_io_timeout_msecs : 5
 properties.max_direct_io_size_kb : 16384
 properties.max_device_cache_size_kb : 131072
 properties.max_device_pinned_mem_size_kb : 33554432
 properties.posix_pool_slab_size_kb : 4 1024 16384
 properties.posix_pool_slab_count : 128 64 32
 properties.rdma_peer_affinity_policy : RoundRobin
 properties.rdma_dynamic_routing : 0
 fs.generic.posix_unaligned_writes : false
 fs.lustre.posix_gds_min_kb: 0
 fs.weka.rdma_write_support: false
 profile.nvtx : false
 profile.cufile_stats : 0
 miscellaneous.api_check_aggressive : false
 =========
 GPU INFO:
 =========
 GPU index 0 NVIDIA A100-PCIE-40GB bar:1 bar size (MiB):65536 supports GDS
 GPU index 1 NVIDIA A100-PCIE-40GB bar:1 bar size (MiB):65536 supports GDS
 ==============
 PLATFORM INFO:
 ==============
 IOMMU: disabled
 Platform verification succeeded

Tips

RAIDを使用する場合の追加設定

GPUDirect Storageを利用してSoftware RAID (md-raid0) 区画からデータを読み出す場合、 以下の一行を/lib/udev/rules.d/63-md-raid-arrays.rules 設定に追加する必要があります。

IMPORT{​program}="/usr/sbin/mdadm --detail --export $devnode"

その後、設定を反映させるためにシステムを再起動してください。 詳しくはNVIDIA GPUDirect Storage Installation and Troubleshooting Guideを参照してください。

PCI Bar1メモリの設定

GPU-Direct SQLは、GPUデバイスメモリをホストシステム上のPCI BAR1領域(物理アドレス空間)にマップし、そこをDestinationとするP2P-RDMA要求をNVME機器に対して行う事で、ロスのない高速なデータ読出しを実現します。

十分な多重度を持ったP2P-RDMAを行うには、GPUがバッファをマップするのに十分なPCI BAR1領域を有している必要があります。大半のGPUではPCI BAR1領域の大きさは固定で、PG-Stromにおいては、それがGPUデバイスメモリのサイズを上回っている製品を推奨しています。

しかし、一部のGPU製品においては『動作モード』を切り替える事でPCI BAR1領域のサイズを切り替える事ができるものが存在します。お使いのGPUがそれに該当する場合は、NVIDIA Display Mode Selector Toolを参照の上、PCI BAR1領域のサイズを最大化するモードへと切り替えてください。

2023年12月時点では、以下のGPUの場合にNVIDIA Display Mode Selector Toolを利用して*Display Offモードへと切り替える必要があります。

  • NVIDIA L40S
  • NVIDIA L40
  • NVIDIA A40
  • NVIDIA RTX 6000 Ada
  • NVIDIA RTX A6000
  • NVIDIA RTX A5500
  • NVIDIA RTX A5000

システムに搭載されているGPUのメモリサイズやPCI BAR1サイズを確認するには、nvidia-smi -qコマンドを利用します。以下のように、メモリ関連の状態が表示されます。

$ nvidia-smi -q
        :
    FB Memory Usage
        Total                             : 46068 MiB
        Reserved                          : 685 MiB
        Used                              : 4 MiB
        Free                              : 45377 MiB
    BAR1 Memory Usage
        Total                             : 65536 MiB
        Used                              : 1 MiB
        Free                              : 65535 MiB
        :

HeteroDB 拡張モジュール

heterodb-extraモジュールは、PG-Stromに以下の機能を追加します。

  • マルチGPUの対応
  • GPUダイレクトSQL
  • GiSTインデックス対応
  • ライセンス管理機能

これらの機能を使用せず、オープンソース版の機能のみを使用する場合は heterodb-extra モジュールのインストールは不要です。 本節の内容は読み飛ばして構いません。

以下のように、SWDCからheterodb-extraパッケージをインストールしてください。

# dnf install heterodb-extra

ライセンスの有効化

heterodb-extraモジュールの全ての機能を利用するには、HeteroDB社が提供するライセンスの有効化が必要です。ライセンスなしで運用する事も可能ですが、その場合、下記の機能が制限を受けます。

  • マルチGPUの利用
  • GPUダイレクトSQLにおける複数NVME-SSDによるストライピング(md-raid0)
  • GPUダイレクトSQLにおけるNVME-oFデバイスの利用
  • GPU版PostGISにおけるGiSTインデックスの利用

ライセンスファイルは以下のような形式でHeteroDB社から入手する事ができます。

IAgIVdKxhe+BSer3Y67jQW0+uTzYh00K6WOSH7xQ26Qcw8aeUNYqJB9YcKJTJb+QQhjmUeQpUnboNxVwLCd3HFuLXeBWMKp11/BgG0FSrkUWu/ZCtDtw0F1hEIUY7m767zAGV8y+i7BuNXGJFvRlAkxdVO3/K47ocIgoVkuzBfLvN/h9LffOydUnHPzrFHfLc0r3nNNgtyTrfvoZiXegkGM9GBTAKyq8uWu/OGonh9ybzVKOgofhDLk0rVbLohOXDhMlwDl2oMGIr83tIpCWG+BGE+TDwsJ4n71Sv6n4bi/ZBXBS498qShNHDGrbz6cNcDVBa+EuZc6HzZoF6UrljEcl=
----
VERSION:2
SERIAL_NR:HDB-TRIAL
ISSUED_AT:2019-05-09
EXPIRED_AT:2019-06-08
GPU_UUID:GPU-a137b1df-53c9-197f-2801-f2dccaf9d42f

これを /etc/heterodb.license にコピーし、PostgreSQLを再起動します。

以下のようにPostgreSQLの起動ログにライセンス情報が出力され、ライセンスの有効化が行われた事が分かります。

    :
 LOG:  HeteroDB Extra module loaded [api_version=20231105,cufile=on,nvme_strom=off,githash=9ca2fe4d2fbb795ad2d741dcfcb9f2fe499a5bdf]
 LOG:  HeteroDB License: { "version" : 2, "serial_nr" : "HDB-TRIAL", "issued_at" : "2022-11-19", "expired_at" : "2099-12-31", "nr_gpus" : 1, "gpus" : [ { "uuid" : "GPU-13943bfd-5b30-38f5-0473-78979c134606" } ]}
 LOG:  PG-Strom version 5.0.1 built for PostgreSQL 15 (githash: 972441dbafed6679af86af40bc8613be2d73c4fd)
    :

PostgreSQLのインストール

本節ではRPMによるPostgreSQLのインストールについて紹介します。 ソースからのインストールに関しては既にドキュメントが数多く存在し、./configureスクリプトのオプションが多岐にわたる事から、ここでは紹介しません。

Linuxディストリビューションの配布するパッケージにもPostgreSQLは含まれていますが、必ずしも最新ではなく、PG-Stromの対応バージョンよりも古いものである事が多々あります。例えば、Red Hat Enterprise Linux 7.xで配布されているPostgreSQLはv9.2.xですが、これはPostgreSQLコミュニティとして既にEOLとなっているバージョンです。

PostgreSQL Global Development Groupは、最新のPostgreSQLおよび関連ソフトウェアの配布のためにyumリポジトリを提供しています。 EPELの設定のように、yumリポジトリの設定を行うだけの小さなパッケージをインストールし、その後、PostgreSQLやその他のソフトウェアをインストールします。

yumリポジトリ定義の一覧は http://yum.postgresql.org/repopackages.php です。

PostgreSQLメジャーバージョンとLinuxディストリビューションごとに多くのリポジトリ定義がありますが、あなたのLinuxディストリビューション向けのPostgreSQL 11以降のものを選択する必要があります。

以下のステップで PostgreSQL のインストールを行います。

  • yumリポジトリの定義をインストール
  • OS標準のPostgreSQLモジュールの無効化
  • PostgreSQLパッケージのインストール

例えばPostgreSQL v15を使用する場合、PG-Stromのインストールには postgresql15-serverおよびpostgresql15-develパッケージが必要です。

以下は、RHEL8においてPostgreSQL v15をインストールする手順の例です。

# dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm
# dnf -y module disable postgresql
# dnf install -y postgresql15-devel postgresql15-server

Note

Red Hat Enterprise Linux 8.x の場合、パッケージ名postgresqlがディストリビューション標準のものと競合してしまい、PGDG提供のパッケージをインストールする事ができません。そのため、dnf -y module disable postgresql コマンドを用いてディストリビューション標準のpostgresqlモジュールを無効化します。

PostgreSQL Global Development Groupの提供するRPMパッケージは/usr/pgsql-<version>という少々変則的なディレクトリにソフトウェアをインストールするため、psql等の各種コマンドを実行する際にはパスが通っているかどうか注意する必要があります。

postgresql-alternativesパッケージをインストールしておくと、各種コマンドへのシンボリックリンクを/usr/local/bin以下に作成するため各種オペレーションが便利です。また、複数バージョンのPostgreSQLをインストールした場合でも、alternativesコマンドによってターゲットとなるPostgreSQLバージョンを切り替える事が可能です。

# dnf install postgresql-alternatives

PG-Stromのインストール

本節ではPG-Stromのインストール方法について説明します。 推奨はRPMによるインストールですが、開発者向けにソースコードからのビルド方法についても紹介します。

RPMによるインストール

PG-Stromおよび関連パッケージはHeteroDB Software Distribution Centerより配布されています。 既にyumシステムへリポジトリを追加済みであれば、それほど作業は多くありません。

基盤となるPostgreSQLのバージョンごとに別個のPG-StromのRPMパッケージが準備されており、PostgreSQL v15用であればpg_strom-PG15パッケージを、PostgreSQL v16用であればpg_strom-PG16パッケージをインストールします。

これは、PostgreSQL拡張モジュールのバイナリ互換性に伴う制約です。

# dnf install -y pg_strom-PG15

以上でパッケージのインストールは完了です。

ソースからのインストール

開発者向けに、ソースコードからPG-Stromをビルドする方法についても紹介します。

ソースコードの入手

RPMパッケージと同様に、ソースコードのtarballをHeteroDB Software Distribution Centerから入手する事ができます。

ただ、tarballのリリースにはある程度のタイムラグが生じてしまうため、最新の開発版を使いたい場合にはPG-StromのGitHubリポジトリmasterブランチをチェックアウトする方法の方が好まれるかもしれません。

$ git clone https://github.com/heterodb/pg-strom.git
Cloning into 'pg-strom'...
remote: Counting objects: 13797, done.
remote: Compressing objects: 100% (215/215), done.
remote: Total 13797 (delta 208), reused 339 (delta 167), pack-reused 13400
Receiving objects: 100% (13797/13797), 11.81 MiB | 1.76 MiB/s, done.
Resolving deltas: 100% (10504/10504), done.

PG-Stromのビルド

PG-Stromをビルドする時のコンフィグは、インストール先のPostgreSQLと厳密に一致していなければいけません。例えば、同じ構造体がビルド時のコンフィグによりPostgreSQLとPG-Stromで異なったレイアウトを持ってしまったとすれば、非常に発見の難しいバグを生み出してしまうかもしれません。 したがって、(一貫性のない状態を避けるため)PG-Stromは独自にconfigureスクリプトを走らせたりはせず、pg_configを使ってPostgreSQLのビルド時設定を参照します。

pg_configにパスが通っており、それがインストール先のPostgreSQLのものであれば、そのままmakemake installを実行します。 直接パスが通っていない場合は、makeコマンドにPG_CONFIG=...パラメータを与え、pg_configのフルパスを渡します。

$ cd pg-strom
$ make PG_CONFIG=/usr/pgsql-15/bin/pg_config
$ sudo make install PG_CONFIG=/usr/pgsql-15/bin/pg_config

インストール後の設定

データベースクラスタの作成

データベースクラスタの作成が済んでいない場合は、initdbコマンドを実行してPostgreSQLの初期データベースを作成します。

RPMインストールにおけるデフォルトのデータベースクラスタのパスは/var/lib/pgsql/<version number>/dataです。 postgresql-alternativesパッケージをインストールしている場合は、PostgreSQLのバージョンに拠らず/var/lib/pgdataで参照する事ができます。

# su - postgres
$ initdb -D /var/lib/pgdata/
The files belonging to this database system will be owned by user "postgres".
This user must also own the server process.

The database cluster will be initialized with locale "en_US.UTF-8".
The default database encoding has accordingly been set to "UTF8".
The default text search configuration will be set to "english".

Data page checksums are disabled.

fixing permissions on existing directory /var/lib/pgdata ... ok
creating subdirectories ... ok
selecting dynamic shared memory implementation ... posix
selecting default max_connections ... 100
selecting default shared_buffers ... 128MB
selecting default time zone ... Asia/Tokyo
creating configuration files ... ok
running bootstrap script ... ok
performing post-bootstrap initialization ... ok
syncing data to disk ... ok

initdb: warning: enabling "trust" authentication for local connections
You can change this by editing pg_hba.conf or using the option -A, or
--auth-local and --auth-host, the next time you run initdb.

Success. You can now start the database server using:

    pg_ctl -D /var/lib/pgdata/ -l logfile start

postgresql.confの編集

続いて、PostgreSQLの設定ファイルである postgresql.conf を編集します。

PG-Stromを動作させるためには、最低限、以下のパラメータの設定が必要です。 これ以外のパラメータについても、システムの用途や想定ワークロードを踏まえて検討してください。

  • shared_preload_libraries
    • PG-Stromモジュールはshared_preload_librariesパラメータによりpostmasterプロセスの起動時にロードされる必要があります。オンデマンドでの拡張モジュールのロードはサポート対象外です。したがって、以下の設定項目は必須です。
    • shared_preload_libraries = '$libdir/pg_strom'
  • max_worker_processes
    • PG-Stromは数個のバックグラウンドワーカーを内部的に使用します。そのため、デフォルト値である 8 では、それ以外の処理に利用できるバックグラウンドワーカープロセス数があまりにも少なすぎてしまいます。
    • 以下のように、ある程度の余裕を持った値を設定すべきです。
    • max_worker_processes = 100
  • shared_buffers
    • ワークロードによりますが、shared_buffersの初期設定は非常に小さいため、PG-Stromが有効に機能する水準のデータサイズに対しては、ストレージへの読み書きが律速要因となってしまい、GPUの並列計算機能を有効に利用できない可能性があります。
    • 以下のように、ある程度の余裕を持った値を設定すべきです。
    • shared_buffers = 10GB
    • 明らかにメモリサイズよりも大きなデータを処理する必要がある場合は、SSD-to-GPUダイレクトSQL実行の利用を検討してください。
  • work_mem
    • ワークロードによりますが、work_memの初期設定は非常に小さいため、解析系クエリで最適なクエリ実行計画が選択されない可能性があります。
    • 典型的な例は、ソート処理にオンメモリのクイックソートではなく、ディスクベースのマージソートを選択するといったものです。
    • 以下のように、ある程度の余裕を持った値を設定すべきです。
    • work_mem = 1GB

OSのリソース制限の拡張

GPUダイレクトSQLを使用する場合は特に、同時に大量のファイルをオープンする事があるため、プロセスあたりファイルディスクリプタ数の上限を拡大しておく必要があります。

また、PostgreSQLのクラッシュ時に確実にコアダンプを生成できるよう、コアファイルのサイズ上限を制限しないことを推奨します。

PostgreSQLをsystemd経由で起動する場合、リソース制限に関する設定は/etc/systemd/system/postgresql-XX.service.d/pg_strom.confに記述します。

RPMによるインストールの場合、デフォルトで以下の内容が設定されます。

環境変数 CUDA_ENABLE_COREDUMP_ON_EXCEPTION に関する設定がコメントアウトされています。これは開発者向けのオプションで、これを有効にして起動すると、GPU側でエラーが発生した場合にGPUのコアダンプを生成させる事ができます。詳しくはCUDA-GDB:GPU core dump supportをご覧ください。

[Service]
LimitNOFILE=65536
LimitCORE=infinity
#Environment=CUDA_ENABLE_COREDUMP_ON_EXCEPTION=1

PostgreSQLの起動

PostgreSQLを起動します。

正常にセットアップが完了していれば、ログにPG-StromがGPUを認識した事を示すメッセージが記録されているはずです。 以下の例では、NVIDIA A100 (PCIE版; 40GB) を認識しており、また、NVME-SSDごとに近傍のGPUがどちらであるのか出力されています。

# systemctl start postgresql-13
# journalctl -u postgresql-13
-- Logs begin at Thu 2021-05-27 17:02:03 JST, end at Fri 2021-05-28 13:26:35 JST. --
May 28 13:09:33 kujira.heterodb.in systemd[1]: Starting PostgreSQL 13 database server...
May 28 13:09:33 kujira.heterodb.in postmaster[6336]: 2021-05-28 13:09:33.500 JST [6336] LOG:  NVRTC 11.3 is successfully loaded.
May 28 13:09:33 kujira.heterodb.in postmaster[6336]: 2021-05-28 13:09:33.510 JST [6336] LOG:  failed on open('/proc/nvme-strom'): No such file or directory - likely nvme_strom.ko is not loaded
May 28 13:09:33 kujira.heterodb.in postmaster[6336]: 2021-05-28 13:09:33.510 JST [6336] LOG:  HeteroDB Extra module loaded (API=20210525; NVIDIA cuFile)
May 28 13:09:33 kujira.heterodb.in postmaster[6336]: 2021-05-28 13:09:33.553 JST [6336] LOG:  HeteroDB License: { "version" : 2, "serial_nr" : "HDB-TRIAL", "issued_at" : "2021-05-27", "expired_at" : "2021-06-26", "gpus" : [ { "uuid" : "GPU-cca38cf1-ddcc-6230-57fe-d42ad0dc3315" }, { "uuid" : "GPU-13943bfd-5b30-38f5-0473-78979c134606" } ]}
May 28 13:09:33 kujira.heterodb.in postmaster[6336]: 2021-05-28 13:09:33.553 JST [6336] LOG:  PG-Strom version 2.9 built for PostgreSQL 13
May 28 13:09:43 kujira.heterodb.in postmaster[6336]: 2021-05-28 13:09:43.748 JST [6336] LOG:  PG-Strom: GPU0 NVIDIA A100-PCIE-40GB (108 SMs; 1410MHz, L2 40960kB), RAM 39.59GB (5120bits, 1.16GHz), PCI-E Bar1 64GB, CC 8.0
May 28 13:09:43 kujira.heterodb.in postmaster[6336]: 2021-05-28 13:09:43.748 JST [6336] LOG:  PG-Strom: GPU1 NVIDIA A100-PCIE-40GB (108 SMs; 1410MHz, L2 40960kB), RAM 39.59GB (5120bits, 1.16GHz), PCI-E Bar1 64GB, CC 8.0
May 28 13:09:43 kujira.heterodb.in postmaster[6336]: 2021-05-28 13:09:43.755 JST [6336] LOG:  - nvme0n1 (INTEL SSDPEDKE020T7; 0000:5e:00.0)
May 28 13:09:43 kujira.heterodb.in postmaster[6336]: 2021-05-28 13:09:43.755 JST [6336] LOG:  - nvme1n1 (INTEL SSDPE2KX010T8; 0000:8a:00.0 --> GPU0)
May 28 13:09:43 kujira.heterodb.in postmaster[6336]: 2021-05-28 13:09:43.755 JST [6336] LOG:  - nvme2n1 (INTEL SSDPE2KX010T8; 0000:8b:00.0 --> GPU0)
May 28 13:09:43 kujira.heterodb.in postmaster[6336]: 2021-05-28 13:09:43.755 JST [6336] LOG:  - nvme4n1 (INTEL SSDPE2KX010T8; 0000:8d:00.0 --> GPU0)
May 28 13:09:43 kujira.heterodb.in postmaster[6336]: 2021-05-28 13:09:43.755 JST [6336] LOG:  - nvme3n1 (INTEL SSDPE2KX010T8; 0000:8c:00.0 --> GPU0)
May 28 13:09:43 kujira.heterodb.in postmaster[6336]: 2021-05-28 13:09:43.755 JST [6336] LOG:  - nvme6n1 (INTEL SSDPE2KX010T8; 0000:b5:00.0 --> GPU1)
May 28 13:09:43 kujira.heterodb.in postmaster[6336]: 2021-05-28 13:09:43.755 JST [6336] LOG:  - nvme7n1 (INTEL SSDPE2KX010T8; 0000:b6:00.0 --> GPU1)
May 28 13:09:43 kujira.heterodb.in postmaster[6336]: 2021-05-28 13:09:43.755 JST [6336] LOG:  - nvme5n1 (INTEL SSDPE2KX010T8; 0000:b4:00.0 --> GPU1)
May 28 13:09:43 kujira.heterodb.in postmaster[6336]: 2021-05-28 13:09:43.755 JST [6336] LOG:  - nvme8n1 (INTEL SSDPE2KX010T8; 0000:b7:00.0 --> GPU1)
May 28 13:09:43 kujira.heterodb.in postmaster[6336]: 2021-05-28 13:09:43.909 JST [6336] LOG:  redirecting log output to logging collector process
May 28 13:09:43 kujira.heterodb.in postmaster[6336]: 2021-05-28 13:09:43.909 JST [6336] HINT:  Future log output will appear in directory "log".
May 28 13:09:44 kujira.heterodb.in systemd[1]: Started PostgreSQL 13 database server.

PG-Stromエクステンションの作成

最後に、PG-Stromに関連するSQL関数などのDBオブジェクトを作成します。 この手順はPostgreSQLのEXTENSION機能を用いてパッケージ化されており、SQLコマンドラインでCREATE EXTENSIONコマンドを実行するだけです。

なお、この手順は新しいデータベースを作成するたびに必要になる事に注意してください。 新しいデータベースを作成した時点で既にPG-Strom関連オブジェクトが作成されていてほしい場合は、予めtemplate1データベースでPG-Stromエクステンションを作成しておけば、CREATE DATABASEコマンドの実行時に新しいデータベースへ設定がコピーされます。

$ psql -U postgres
psql (15.1)
Type "help" for help.

postgres=# create extension pg_strom ;
CREATE EXTENSION

以上でインストール作業は完了です。

PostGISのインストール

PG-Stromは一部のPostGIS関数のGPU処理をサポートしています。 本節ではPostGISのインストール手順について説明を行いますが、必要に応じて読み飛ばしてください。

PostgreSQLと同様に、PostgreSQL Global Development GroupのyumリポジトリからPostGISモジュールをインストールする事ができます。 以下の例は、PostgreSQL v15向けにビルドされたPostGIS v3.2をインストールするものです。

-- For RHEL8
# dnf install -y postgis32_15 --enablerepo=codeready-builder-for-rhel-8-x86_64-rpms

-- For Rocky8
# dnf install -y postgis32_15 --enablerepo=powertools

データベースクラスタを作成してPostgreSQLサーバを起動し、SQLクライアントからCREATE EXTENSIONコマンドを実行してGeometryデータ型や地理情報分析のためのSQL関数を作成します。 これでPostGISのインストールは完了です。

postgres=# CREATE EXTENSION postgis;
CREATE EXTENSION