GPDB插件安装工具之gppkg

gppkg命令

gppkg是一个python3编写的打包脚本，在整个集群中安装.gppkg格式的Greenplum数据库扩展（例如PL/Java、PL/R和MADlib）及其依赖项，位于/usr/local/cloudberry-db/bin/gppkg(自己安装的gpdb目录)，安装到$GPHOME里面。

gppkg -i xxx.gppkg

其他命令：

gppkg [-i package | -u package | -r  name-version | -c] 
        [-d master_data_directory] [-a] [-v]

gppkg --migrate GPHOME_1 GPHOME_2 [-a] [-v]

gppkg [-q | --query] query_optiongppkg -? | --help | -h 

gppkg --version

gppkg打包原理

如果想生成对应插件的gppkg包，只需要：

gppkg_spec.yml
xxx.rpm or xxx.deb
deps/yyy.rpm or deps/yyy.deb 表示当前插件依赖的其他rpm包，目录必须为deps

最后，通过tar压缩生成gppkg文件。

img

目录层级结构如下：

[admin@i-ycmhbaza ~]$ tree sample/
sample/
├── deps
│   └── other_dep.rpm
├── gppkg_spec.yml
└── sample.rpm

1 directory, 3 files

gppkg打包实现：gpMgmt/bin/gppylib/operations/package.py

gppkg命令实现：gpMgmt/bin/gppylib/programs/gppkg.py

gppkg安装原理

xxx.gppkg文件会被gppkg识别后进行解析，进行tar包解压，并解压到$GPHOME/.tmp目录。
使用rpm命令验证./tmp里面的rpm(或deb)包是否已经存在，插入操作下如果包已经安装会报错，更新操作则直接覆盖安装。

# install
rpm --test -i /usr/local/greenplum-db-devel/.tmp/zombodb_centos_pg14-3000.1.5_1.x86_64.rpm --dbpath /usr/local/greenplum-db-devel/share/packages/database --prefix /usr/local/greenplum-db-devel
# update
rpm --test -U --force /usr/local/greenplum-db-devel/.tmp/zombodb_centos_pg14-3000.1.5_1.x86_64.rpm --dbpath /usr/local/greenplum-db-devel/share/packages/database --prefix /usr/local/greenplum-db-devel

执行PreInstall hook
把gppk通过scp分发到各个segment以及本地的standby节点，所以这里有两个执行函数，remote与local，local做的事情便是执行下面rpm命令，并移动gppkg包到share/packages/archive。remote便是将local的执行逻辑在远端执行(会通过ssh登陆上去执行)。

# insert
rpm -i --force /usr/local/greenplum-db-devel/.tmp/zombodb_centos_pg14-3000.1.5_1.x86_64.rpm --dbpath /usr/local/greenplum-db-devel/share/packages/database --prefix=/usr/local/greenplum-db-devel
# update
rpm -U --force /usr/local/greenplum-db-devel/.tmp/zombodb_centos_pg14-3000.1.5_1.x86_64.rpm --dbpath /usr/local/greenplum-db-devel/share/packages/database --prefix=/usr/local/greenplum-db-devel

执行PostInstall hook

上述两个hook的检查逻辑都比较类似，对于hook结构一样均为：

# On coordinator node only
- Coordinator:  "echo 'This is a sample message shown before successful installation';"
# On segment nodes only
- Segment:  "echo 'This is a sample message shown before successful installation';"
# On all nodes
- All:  "echo 'This is a sample message shown before successful installation';"

所以执行hook的逻辑便是根据yml中的定义，决定在Coordinator、Segment、Standby，对于Coordinator会在Coordinator(本地)+Standy(远程)，Segment(远程)，All=Coordinator(本地)+Standy(远程)+Segment(远程)。

gppkg_spec.yml文件格式

Pkgname: 当前插件的名字

Architecture: 通常是操作系统uname -m的结果，x86_64或aarch64，见附录实现。

OS: 通常是centos、ubuntu、kylin，见附录实现。

Version: 通常是插件的版本。

GPDBVersion: 通常是CBDB的主版本号。

Description: 通常是该包的描述信息。

接下来是几个hook，PreInstall, PostInstall, PreUninstall, PostUninstall, PostUpdate。Hook的意义在于可以通过shell脚本在插件安装前后去控制相关行为，例如想在安装之后打印一些提示信息，做一些环境变量的source动作，通过hook可以方便实现。

示例：以zombodb提示信息为例，绿色标注为PostUpdate所做的操作。

[gpadmin@i-ycmhbaza artifacts]$ gppkg -u zombodb-1.1-gpdb-centos-x86_64.gppkg 
20230105:16:07:44:005742 gppkg:i-ycmhbaza:gpadmin-[INFO]:-Starting gppkg with args: -u zombodb-1.1-gpdb-centos-x86_64.gppkg
20230105:16:07:44:005742 gppkg:i-ycmhbaza:gpadmin-[WARNING]:-WARNING: The process of updating a package includes removing all
20230105:16:07:44:005742 gppkg:i-ycmhbaza:gpadmin-[WARNING]:-previous versions of the system objects related to the package. For
20230105:16:07:44:005742 gppkg:i-ycmhbaza:gpadmin-[WARNING]:-example, previous versions of shared libraries are removed.
20230105:16:07:44:005742 gppkg:i-ycmhbaza:gpadmin-[WARNING]:-After the update process, a database function will fail when it is
20230105:16:07:44:005742 gppkg:i-ycmhbaza:gpadmin-[WARNING]:-called if the function references a package file that has been removed.
Do you still want to continue ? Yy|Nn (default=N):
> y
20230105:16:07:46:005742 gppkg:i-ycmhbaza:gpadmin-[INFO]:-Updating package zombodb-1.1-gpdb-centos-x86_64.gppkg
20230105:16:07:46:005742 gppkg:i-ycmhbaza:gpadmin-[INFO]:-Validating rpm installation cmdStr='rpm --test -U --force /usr/local/greenplum-db-devel/.tmp/zombodb_centos_pg14-3000.1.5_1.x86_64.rpm --dbpath /usr/local/greenplum-db-devel/share/packages/database --prefix /usr/local/greenplum-db-devel'
20230105:16:07:46:005742 gppkg:i-ycmhbaza:gpadmin-[INFO]:-Installing zombodb-1.1-gpdb-centos-x86_64.gppkg locally
20230105:16:07:46:005742 gppkg:i-ycmhbaza:gpadmin-[INFO]:-Validating rpm installation cmdStr='rpm --test -U --force /usr/local/greenplum-db-devel/.tmp/zombodb_centos_pg14-3000.1.5_1.x86_64.rpm --dbpath /usr/local/greenplum-db-devel/share/packages/database --prefix /usr/local/greenplum-db-devel'
20230105:16:07:46:005742 gppkg:i-ycmhbaza:gpadmin-[INFO]:-Installing rpms cmdStr='rpm -U --force /usr/local/greenplum-db-devel/.tmp/zombodb_centos_pg14-3000.1.5_1.x86_64.rpm --dbpath /usr/local/greenplum-db-devel/share/packages/database --prefix=/usr/local/greenplum-db-devel'
20230105:16:07:46:005742 gppkg:i-ycmhbaza:gpadmin-[INFO]:-Completed local installation of zombodb-1.1-gpdb-centos-x86_64.gppkg.
20230105:16:07:46:005742 gppkg:i-ycmhbaza:gpadmin-[INFO]:-Zombodb has been updated successfully
20230105:16:07:46:005742 gppkg:i-ycmhbaza:gpadmin-[INFO]:-zombodb-1.1-gpdb-centos-x86_64.gppkg successfully updated.

	`PreInstall`	`PostInstall`	`PreUninstall`	`PostUninstall`	`PostUpdate`
操作	安装前操作	安装后操作	卸载前操作	卸载后操作	更新后操作

这五个hook的格式如下所示，Coordinator、Segment、All三者写一个即可，如果同时写，执行顺序是coordinator>segment>all，只会选择一个执行。每个后面""括起来的是bash脚本，分号结束当前行。

PostInstall:
# On coordinator node only
- Coordinator:  "echo 'This is a sample message shown after successful installation';"
# On segment nodes only
- Segment:  "echo 'This is a sample message shown after successful installation';"
# On all nodes
- All:  "echo 'This is a sample message shown after successful installation';"

Coordinator表示在当前本地master节点执行，自下面这个commit，把Master改为了Coordinator。执行的时候还会判断是否有standby节点，如果有，则会ssh上去，执行这个hook shell脚本。

https://code.hashdata.xyz/cloudberry/gpdb/-/commit/f0626f7393e9461784bd5c8d3d01933644754499

Segment表示在远端的segment节点执行。

All是Coordinator+Segment执行方式的组合，即：master、standby、segment都会执行。

最后，完整的yml文件格式如下：

Pkgname: sample
Architecture: x86_64
OS: aarch64
Version: 1.2
GPDBVersion: 1
Description: Sample GPDB package
PreInstall:
# On coordinator node only
- Coordinator:  "echo 'This is a sample message shown before successful installation';"
# On segment nodes only
- Segment:  "echo 'This is a sample message shown before successful installation';"
# On all nodes
- All:  "echo 'This is a sample message shown before successful installation';"
PostInstall:
# On coordinator node only
- Coordinator:  "echo 'This is a sample message shown after successful installation';"
# On segment nodes only
- Segment:  "echo 'This is a sample message shown after successful installation';"
# On all nodes
- All:  "echo 'This is a sample message shown after successful installation';"
PreUninstall:
# On coordinator node only
- Coordinator:  "echo 'This is a sample message shown before successful uninstall';"
# On segment nodes only
- Segment:  "echo 'This is a sample message shown before successful uninstall';"
# On all nodes
- All:  "echo 'This is a sample message shown before successful uninstall';"
PostUninstall:
# On coordinator node only
- Coordinator:  "echo 'This is a sample message shown after successful uninstallation';"
# On segment nodes only
- Segment:  "echo 'This is a sample message shown after successful uninstallation';"
# On all nodes
- All:  "echo 'This is a sample message shown after successful uninstallation';"
PostUpdate:
# On coordinator node only
- Coordinator:  "echo 'This is a sample message shown after successful update';"
# On segment nodes only
- Segment:  "echo 'This is a sample message shown after successful update';"
# On all nodes
- All:  "echo 'This is a sample message shown after successful update';"

yml生成方式

参考上述样例，会发现都有gppkg_spec.yml.in文件，里面会带有#arch等信息，这些信息可以动态的被自己的脚本所替换，替换成真正的内容，例如：运行在x86机器上就是x86_64，这样yml便是动态的，而不是固定写死的内容。通过#xx方式+脚本替换生成最终的gppkg_spec.yml文件。

错误小提示

如果使用gppkg -update升级gppkg包，那么必须在yml中指定PostUpdatehook，否则如下所示报错：Cannot find package pdate

[gpadmin@i-ycmhbaza artifacts]$ gppkg -update zombodb-1.1-gpdb-centos-x86_64.gppkg 
20230105:15:30:39:023153 gppkg:i-ycmhbaza:gpadmin-[INFO]:-Starting gppkg with args: -update zombodb-1.1-gpdb-centos-x86_64.gppkg
20230105:15:30:39:023153 gppkg:i-ycmhbaza:gpadmin-[WARNING]:-WARNING: The process of updating a package includes removing all
20230105:15:30:39:023153 gppkg:i-ycmhbaza:gpadmin-[WARNING]:-previous versions of the system objects related to the package. For
20230105:15:30:39:023153 gppkg:i-ycmhbaza:gpadmin-[WARNING]:-example, previous versions of shared libraries are removed.
20230105:15:30:39:023153 gppkg:i-ycmhbaza:gpadmin-[WARNING]:-After the update process, a database function will fail when it is
20230105:15:30:39:023153 gppkg:i-ycmhbaza:gpadmin-[WARNING]:-called if the function references a package file that has been removed.
Do you still want to continue ? Yy|Nn (default=N):
> y
20230105:15:30:41:023153 gppkg:i-ycmhbaza:gpadmin-[ERROR]:-Cannot find package pdate
20230105:15:30:41:023153 gppkg:i-ycmhbaza:gpadmin-[CRITICAL]:-gppkg failed. (Reason='') exiting...